contrib/mdocml/mandoc_html.3

   1 .\"     $Id: mandoc_html.3,v 1.8 2017/05/12 17:58:21 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2014, 2017 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: May 12 2017 $
  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 "const char *fmt"
  34 .Fa ...
  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 .Ft char *
  52 .Fo html_make_id
  53 .Fa "const struct roff_node *n"
  54 .Fc
  55 .Ft int
  56 .Fo html_strlen
  57 .Fa "const char *cp"
  58 .Fc
  59 .Sh DESCRIPTION
  60 The mandoc HTML formatter is not a formal library.
  61 However, as it is compiled into more than one program, in particular
  62 .Xr mandoc 1
  63 and
  64 .Xr man.cgi 8 ,
  65 and because it may be security-critical in some contexts,
  66 some documentation is useful to help to use it correctly and
  67 to prevent XSS vulnerabilities.
  68 .Pp
  69 The formatter produces HTML output on the standard output.
  70 Since proper escaping is usually required and best taken care of
  71 at one central place, the language-specific formatters
  72 .Po
  73 .Pa *_html.c ,
  74 see
  75 .Sx FILES
  76 .Pc
  77 are not supposed to print directly to
  78 .Dv stdout
  79 using functions like
  80 .Xr printf 3 ,
  81 .Xr putc 3 ,
  82 .Xr puts 3 ,
  83 or
  84 .Xr write 2 .
  85 Instead, they are expected to use the output functions declared in
  86 .Pa html.h
  87 and implemented as part of the main HTML formatting engine in
  88 .Pa html.c .
  89 .Ss Data structures
  90 These structures are declared in
  91 .Pa html.h .
  92 .Bl -tag -width Ds
  93 .It Vt struct html
  94 Internal state of the HTML formatter.
  95 .It Vt struct tag
  96 One entry for the LIFO stack of HTML elements.
  97 Members are
  98 .Fa "enum htmltag tag"
  99 and
 100 .Fa "struct tag *next" .
 101 .El
 102 .Ss Private interface functions
 103 The function
 104 .Fn print_gen_decls
 105 prints the opening
 106 .Ao Pf \&? Ic xml ? Ac
 107 and
 108 .Aq Pf \&! Ic DOCTYPE
 109 declarations required for the current document type.
 110 .Pp
 111 The function
 112 .Fn print_gen_head
 113 prints the opening
 114 .Aq Ic META
 115 and
 116 .Aq Ic LINK
 117 elements for the document
 118 .Aq Ic HEAD ,
 119 using the
 120 .Fa style
 121 member of
 122 .Fa h
 123 unless that is
 124 .Dv NULL .
 125 It uses
 126 .Fn print_otag
 127 which takes care of properly encoding attributes,
 128 which is relevant for the
 129 .Fa style
 130 link in particular.
 131 .Pp
 132 The function
 133 .Fn print_otag
 134 prints the start tag of an HTML element with the name
 135 .Fa tag ,
 136 optionally including the attributes specified by
 137 .Fa fmt .
 138 If
 139 .Fa fmt
 140 is the empty string, no attributes are written.
 141 Each letter of
 142 .Fa fmt
 143 specifies one attribute to write.
 144 Most attributes require one
 145 .Va char *
 146 argument which becomes the value of the attribute.
 147 The arguments have to be given in the same order as the attribute letters.
 148 If an argument is
 149 .Dv NULL ,
 150 the respective attribute is not written.
 151 .Bl -tag -width 1n -offset indent
 152 .It Cm c
 153 Print a
 154 .Cm class
 155 attribute.
 156 This attribute letter can optionally be followed by the modifier letter
 157 .Cm T .
 158 In that case, a
 159 .Cm title
 160 attribute with the same value is also printed.
 161 .It Cm h
 162 Print a
 163 .Cm href
 164 attribute.
 165 This attribute letter can optionally be followed by a modifier letter.
 166 If followed by
 167 .Cm R ,
 168 it formats the link as a local one by prefixing a
 169 .Sq #
 170 character.
 171 If followed by
 172 .Cm I ,
 173 it interpretes the argument as a header file name
 174 and generates a link using the
 175 .Xr mandoc 1
 176 .Fl O Cm includes
 177 option.
 178 If followed by
 179 .Cm M ,
 180 it takes two arguments instead of one, a manual page name and
 181 section, and formats them as a link to a manual page using the
 182 .Xr mandoc 1
 183 .Fl O Cm man
 184 option.
 185 .It Cm i
 186 Print an
 187 .Cm id
 188 attribute.
 189 .It Cm \&?
 190 Print an arbitrary attribute.
 191 This format letter requires two
 192 .Vt char *
 193 arguments, the attribute name and the value.
 194 The name must not be
 195 .Dv NULL .
 196 .It Cm s
 197 Print a
 198 .Cm style
 199 attribute.
 200 If present, it must be the last format letter.
 201 In contrast to the other format letters, this one does not yet
 202 print the value and does not take an argument.
 203 Instead, the rest of the format string consists of pairs of
 204 argument type letters and style name letters.
 205 .El
 206 .Pp
 207 Argument type letters each require one argument as follows:
 208 .Bl -tag -width 1n -offset indent
 209 .It Cm h
 210 Requires one
 211 .Vt int
 212 argument, interpreted as a horizontal length in units of
 213 .Dv SCALE_EN .
 214 .It Cm s
 215 Requires one
 216 .Vt char *
 217 argument, used as a style value.
 218 .It Cm u
 219 Requires one
 220 .Vt struct roffsu *
 221 argument, used as a length.
 222 .It Cm v
 223 Requires one
 224 .Vt int
 225 argument, interpreted as a vertical length in units of
 226 .Dv SCALE_VS .
 227 .It Cm w
 228 Requires one
 229 .Vt char *
 230 argument, interpreted as an
 231 .Xr mdoc 7 Ns -style
 232 width specifier.
 233 If the argument is
 234 .Dv NULL ,
 235 nothing is printed for this pair.
 236 .Pp
 237 The
 238 .Cm w
 239 argument type letter can optionally be followed by one or two
 240 modifier letters.
 241 The modifier
 242 .Cm +
 243 increases the width by 10% to make even bold text fit
 244 and adds two units for padding between columns.
 245 The modifier
 246 .Cm \-
 247 makes the width negative by multiplying it with \-1.
 248 .El
 249 .Pp
 250 Style name letters decide what to do with the preceding argument:
 251 .Bl -tag -width 1n -offset indent
 252 .It Cm b
 253 Set
 254 .Cm margin-bottom
 255 to the given length.
 256 .It Cm h
 257 Set
 258 .Cm height
 259 to the given length.
 260 .It Cm i
 261 Set
 262 .Cm text-indent
 263 to the given length.
 264 .It Cm l
 265 Set
 266 .Cm margin-left
 267 to the given length.
 268 .It Cm t
 269 Set
 270 .Cm margin-top
 271 to the given length.
 272 .It Cm w
 273 Set
 274 .Cm width
 275 to the given length.
 276 .It Cm W
 277 Set
 278 .Cm min-width
 279 to the given length.
 280 .It Cm \&?
 281 The special pair
 282 .Cm s?
 283 requires two
 284 .Vt char *
 285 arguments.
 286 The first is the style name, the second its value.
 287 The style name must not be
 288 .Dv NULL .
 289 .El
 290 .Pp
 291 .Fn print_otag
 292 uses the private function
 293 .Fn print_encode
 294 to take care of HTML encoding.
 295 If required by the element type, it remembers in
 296 .Fa h
 297 that the element is open.
 298 The function
 299 .Fn print_tagq
 300 is used to close out all open elements up to and including
 301 .Fa until ;
 302 .Fn print_stagq
 303 is a variant to close out all open elements up to but excluding
 304 .Fa suntil .
 305 .Pp
 306 The function
 307 .Fn print_text
 308 prints HTML element content.
 309 It uses the private function
 310 .Fn print_encode
 311 to take care of HTML encoding.
 312 If the document has requested a non-standard font, for example using a
 313 .Xr roff 7
 314 .Ic \ef
 315 font escape sequence,
 316 .Fn print_text
 317 wraps
 318 .Fa word
 319 in an HTML font selection element using the
 320 .Fn print_otag
 321 and
 322 .Fn print_tagq
 323 functions.
 324 .Pp
 325 The function
 326 .Fn html_make_id
 327 takes a node containing one or more text children
 328 and returns a newly allocated string containing the concatenation
 329 of the child strings, with blanks replaced by underscores.
 330 If the node
 331 .Fa n
 332 contains any non-text child node,
 333 .Fn html_make_id
 334 returns
 335 .Dv NULL
 336 instead.
 337 The caller is responsible for freeing the returned string.
 338 .Pp
 339 The function
 340 .Fn html_strlen
 341 counts the number of characters in
 342 .Fa cp .
 343 It is used as a crude estimate of the width needed to display a string.
 344 .Pp
 345 The functions
 346 .Fn print_eqn ,
 347 .Fn print_tbl ,
 348 and
 349 .Fn print_tblclose
 350 are not yet documented.
 351 .Sh FILES
 352 .Bl -tag -width mandoc_aux.c -compact
 353 .It Pa main.h
 354 declarations of public functions for use by the main program,
 355 not yet documented
 356 .It Pa html.h
 357 declarations of data types and private functions
 358 for use by language-specific HTML formatters
 359 .It Pa html.c
 360 main HTML formatting engine and utility functions
 361 .It Pa mdoc_html.c
 362 .Xr mdoc 7
 363 HTML formatter
 364 .It Pa man_html.c
 365 .Xr man 7
 366 HTML formatter
 367 .It Pa tbl_html.c
 368 .Xr tbl 7
 369 HTML formatter
 370 .It Pa eqn_html.c
 371 .Xr eqn 7
 372 HTML formatter
 373 .It Pa out.h
 374 declarations of data types and private functions
 375 for shared use by all mandoc formatters,
 376 not yet documented
 377 .It Pa out.c
 378 private functions for shared use by all mandoc formatters
 379 .It Pa mandoc_aux.h
 380 declarations of common mandoc utility functions, see
 381 .Xr mandoc 3
 382 .It Pa mandoc_aux.c
 383 implementation of common mandoc utility functions
 384 .El
 385 .Sh SEE ALSO
 386 .Xr mandoc 1 ,
 387 .Xr mandoc 3 ,
 388 .Xr man.cgi 8
 389 .Sh AUTHORS
 390 .An -nosplit
 391 The mandoc HTML formatter was written by
 392 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
 393 It is maintained by
 394 .An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
 395 who also wrote this manual.