contrib/mdocml/mandoc_html.3

   1 .\"     $Id: mandoc_html.3,v 1.1 2014/07/23 18:13:09 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: July 23 2014 $
  18 .Dt MANDOC_HTML 3
  19 .Os
  20 .Sh NAME
  21 .Nm mandoc_html
  22 .Nd internals of the mandoc HTML formatter
  23 .Sh SYNOPSIS
  24 .In "html.h"
  25 .Ft void
  26 .Fn print_gen_decls "struct html *h"
  27 .Ft void
  28 .Fn print_gen_head "struct html *h"
  29 .Ft struct tag *
  30 .Fo print_otag
  31 .Fa "struct html *h"
  32 .Fa "enum htmltag tag"
  33 .Fa "int sz"
  34 .Fa "const struct htmlpair *p"
  35 .Fc
  36 .Ft void
  37 .Fo print_tagq
  38 .Fa "struct html *h"
  39 .Fa "const struct tag *until"
  40 .Fc
  41 .Ft void
  42 .Fo print_stagq
  43 .Fa "struct html *h"
  44 .Fa "const struct tag *suntil"
  45 .Fc
  46 .Ft void
  47 .Fo print_text
  48 .Fa "struct html *h"
  49 .Fa "const char *word"
  50 .Fc
  51 .Sh DESCRIPTION
  52 The mandoc HTML formatter is not a formal library.
  53 However, as it is compiled into more than one program, in particular
  54 .Xr mandoc 1
  55 and
  56 .Xr man.cgi 8 ,
  57 and because it may be security-critical in some contexts,
  58 some documentation is useful to help to use it correctly and
  59 to prevent XSS vulnerabilities.
  60 .Pp
  61 The formatter produces HTML output on the standard output.
  62 Since proper escaping is usually required and best taken care of
  63 at one central place, the language-specific formatters
  64 .Po
  65 .Pa *_html.c ,
  66 see
  67 .Sx FILES
  68 .Pc
  69 are not supposed to print directly to
  70 .Dv stdout
  71 using functions like
  72 .Xr printf 3 ,
  73 .Xr putc 3 ,
  74 .Xr puts 3 ,
  75 or
  76 .Xr write 2 .
  77 Instead, they are expected to use the output functions declared in
  78 .Pa html.h
  79 and implemented as part of the main HTML formatting engine in
  80 .Pa html.c .
  81 .Ss Data structures
  82 These structures are declared in
  83 .Pa html.h .
  84 .Bl -tag -width Ds
  85 .It Vt struct html
  86 Internal state of the HTML formatter.
  87 .It Vt struct htmlpair
  88 Holds one HTML attribute.
  89 Members are
  90 .Fa "enum htmlattr key"
  91 and
  92 .Fa "const char *val" .
  93 Helper macros
  94 .Fn PAIR_*
  95 are provided to support initialization of such structures.
  96 .It Vt struct tag
  97 One entry for the LIFO stack of HTML elements.
  98 Members are
  99 .Fa "enum htmltag tag"
 100 and
 101 .Fa "struct tag *next" .
 102 .El
 103 .Ss Private interface functions
 104 The function
 105 .Fn print_gen_decls
 106 prints the opening
 107 .Ao Pf \&? Ic xml ? Ac
 108 and
 109 .Aq Pf \&! Ic DOCTYPE
 110 declarations required for the current document type.
 111 .Pp
 112 The function
 113 .Fn print_gen_head
 114 prints the opening
 115 .Aq Ic META
 116 and
 117 .Aq Ic LINK
 118 elements for the document
 119 .Aq Ic HEAD ,
 120 using the
 121 .Fa style
 122 member of
 123 .Fa h
 124 unless that is
 125 .Dv NULL .
 126 It uses
 127 .Fn print_otag
 128 which takes care of properly encoding attributes,
 129 which is relevant for the
 130 .Fa style
 131 link in particular.
 132 .Pp
 133 The function
 134 .Fn print_otag
 135 prints the start tag of an HTML element with the name
 136 .Fa tag ,
 137 including the
 138 .Fa sz
 139 attributes that can optionally be provided in the
 140 .Fa p
 141 array.
 142 It uses the private function
 143 .Fn print_attr
 144 which in turn uses the private function
 145 .Fn print_encode
 146 to take care of HTML encoding.
 147 If required by the element type, it remembers in
 148 .Fa h
 149 that the element is open.
 150 The function
 151 .Fn print_tagq
 152 is used to close out all open elements up to and including
 153 .Fa until ;
 154 .Fn print_stagq
 155 is a variant to close out all open elements up to but excluding
 156 .Fa suntil .
 157 .Pp
 158 The function
 159 .Fn print_text
 160 prints HTML element content.
 161 It uses the private function
 162 .Fn print_encode
 163 to take care of HTML encoding.
 164 If the document has requested a non-standard font, for example using a
 165 .Xr roff 7
 166 .Ic \ef
 167 font escape sequence,
 168 .Fn print_text
 169 wraps
 170 .Fa word
 171 in an HTML font selection element using the
 172 .Fn print_otag
 173 and
 174 .Fn print_tagq
 175 functions.
 176 .Pp
 177 The functions
 178 .Fn bufinit ,
 179 .Fn bufcat* ,
 180 and
 181 .Fn buffmt*
 182 do not directly produce output but buffer text in the
 183 .Fa buf
 184 member of
 185 .Fa h .
 186 They are not used internally by
 187 .Pa html.c
 188 but intended for use by the language-specific formatters
 189 to ease preparation of strings for the
 190 .Fa p
 191 argument of
 192 .Fn print_otag
 193 and for the
 194 .Fa word
 195 argument of
 196 .Fn print_text .
 197 Consequently, these functions do not do any HTML encoding.
 198 .Pp
 199 The functions
 200 .Fn html_strlen ,
 201 .Fn print_eqn ,
 202 .Fn print_tbl ,
 203 and
 204 .Fn print_tblclose
 205 are not yet documented.
 206 .Sh FILES
 207 .Bl -tag -width mandoc_aux.c -compact
 208 .It Pa main.h
 209 declarations of public functions for use by the main program,
 210 not yet documented
 211 .It Pa html.h
 212 declarations of data types and private functions
 213 for use by language-specific HTML formatters
 214 .It Pa html.c
 215 main HTML formatting engine and utility functions
 216 .It Pa mdoc_html.c
 217 .Xr mdoc 7
 218 HTML formatter
 219 .It Pa man_html.c
 220 .Xr man 7
 221 HTML formatter
 222 .It Pa tbl_html.c
 223 .Xr tbl 7
 224 HTML formatter
 225 .It Pa eqn_html.c
 226 .Xr eqn 7
 227 HTML formatter
 228 .It Pa out.h
 229 declarations of data types and private functions
 230 for shared use by all mandoc formatters,
 231 not yet documented
 232 .It Pa out.c
 233 private functions for shared use by all mandoc formatters
 234 .It Pa mandoc_aux.h
 235 declarations of common mandoc utility functions, see
 236 .Xr mandoc 3
 237 .It Pa mandoc_aux.c
 238 implementation of common mandoc utility functions
 239 .El
 240 .Sh SEE ALSO
 241 .Xr mandoc 1 ,
 242 .Xr mandoc 3 ,
 243 .Xr man.cgi 8
 244 .Sh AUTHORS
 245 .An -nosplit
 246 The mandoc HTML formatter was written by
 247 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
 248 This manual was written by
 249 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .