mandoc_html.3

   1 .\"     $Id: mandoc_html.3,v 1.18 2018/11/26 01:38:23 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2014, 2017, 2018 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: November 26 2018 $
  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_comment "struct html *h" "struct roff_node *n"
  29 .Ft void
  30 .Fn print_gen_head "struct html *h"
  31 .Ft struct tag *
  32 .Fo print_otag
  33 .Fa "struct html *h"
  34 .Fa "enum htmltag tag"
  35 .Fa "const char *fmt"
  36 .Fa ...
  37 .Fc
  38 .Ft void
  39 .Fo print_tagq
  40 .Fa "struct html *h"
  41 .Fa "const struct tag *until"
  42 .Fc
  43 .Ft void
  44 .Fo print_stagq
  45 .Fa "struct html *h"
  46 .Fa "const struct tag *suntil"
  47 .Fc
  48 .Ft void
  49 .Fo print_text
  50 .Fa "struct html *h"
  51 .Fa "const char *word"
  52 .Fc
  53 .Ft char *
  54 .Fo html_make_id
  55 .Fa "const struct roff_node *n"
  56 .Fc
  57 .Ft int
  58 .Fo html_strlen
  59 .Fa "const char *cp"
  60 .Fc
  61 .Sh DESCRIPTION
  62 The mandoc HTML formatter is not a formal library.
  63 However, as it is compiled into more than one program, in particular
  64 .Xr mandoc 1
  65 and
  66 .Xr man.cgi 8 ,
  67 and because it may be security-critical in some contexts,
  68 some documentation is useful to help to use it correctly and
  69 to prevent XSS vulnerabilities.
  70 .Pp
  71 The formatter produces HTML output on the standard output.
  72 Since proper escaping is usually required and best taken care of
  73 at one central place, the language-specific formatters
  74 .Po
  75 .Pa *_html.c ,
  76 see
  77 .Sx FILES
  78 .Pc
  79 are not supposed to print directly to
  80 .Dv stdout
  81 using functions like
  82 .Xr printf 3 ,
  83 .Xr putc 3 ,
  84 .Xr puts 3 ,
  85 or
  86 .Xr write 2 .
  87 Instead, they are expected to use the output functions declared in
  88 .Pa html.h
  89 and implemented as part of the main HTML formatting engine in
  90 .Pa html.c .
  91 .Ss Data structures
  92 These structures are declared in
  93 .Pa html.h .
  94 .Bl -tag -width Ds
  95 .It Vt struct html
  96 Internal state of the HTML formatter.
  97 .It Vt struct tag
  98 One entry for the LIFO stack of HTML elements.
  99 Members are
 100 .Fa "enum htmltag tag"
 101 and
 102 .Fa "struct tag *next" .
 103 .El
 104 .Ss Private interface functions
 105 The function
 106 .Fn print_gen_decls
 107 prints the opening
 108 .Ao Pf \&? Ic xml ? Ac
 109 and
 110 .Aq Pf \&! Ic DOCTYPE
 111 declarations required for the current document type.
 112 .Pp
 113 The function
 114 .Fn print_gen_comment
 115 prints the leading comments, usually containing a Copyright notice
 116 and license, as an HTML comment.
 117 It is intended to be called right after opening the
 118 .Aq Ic HTML
 119 element.
 120 Pass the first
 121 .Dv ROFFT_COMMENT
 122 node in
 123 .Fa n .
 124 .Pp
 125 The function
 126 .Fn print_gen_head
 127 prints the opening
 128 .Aq Ic META
 129 and
 130 .Aq Ic LINK
 131 elements for the document
 132 .Aq Ic HEAD ,
 133 using the
 134 .Fa style
 135 member of
 136 .Fa h
 137 unless that is
 138 .Dv NULL .
 139 It uses
 140 .Fn print_otag
 141 which takes care of properly encoding attributes,
 142 which is relevant for the
 143 .Fa style
 144 link in particular.
 145 .Pp
 146 The function
 147 .Fn print_otag
 148 prints the start tag of an HTML element with the name
 149 .Fa tag ,
 150 optionally including the attributes specified by
 151 .Fa fmt .
 152 If
 153 .Fa fmt
 154 is the empty string, no attributes are written.
 155 Each letter of
 156 .Fa fmt
 157 specifies one attribute to write.
 158 Most attributes require one
 159 .Va char *
 160 argument which becomes the value of the attribute.
 161 The arguments have to be given in the same order as the attribute letters.
 162 If an argument is
 163 .Dv NULL ,
 164 the respective attribute is not written.
 165 .Bl -tag -width 1n -offset indent
 166 .It Cm c
 167 Print a
 168 .Cm class
 169 attribute.
 170 This attribute letter can optionally be followed by the modifier letter
 171 .Cm T .
 172 In that case, a
 173 .Cm title
 174 attribute with the same value is also printed.
 175 .It Cm h
 176 Print a
 177 .Cm href
 178 attribute.
 179 This attribute letter can optionally be followed by a modifier letter.
 180 If followed by
 181 .Cm R ,
 182 it formats the link as a local one by prefixing a
 183 .Sq #
 184 character.
 185 If followed by
 186 .Cm I ,
 187 it interpretes the argument as a header file name
 188 and generates a link using the
 189 .Xr mandoc 1
 190 .Fl O Cm includes
 191 option.
 192 If followed by
 193 .Cm M ,
 194 it takes two arguments instead of one, a manual page name and
 195 section, and formats them as a link to a manual page using the
 196 .Xr mandoc 1
 197 .Fl O Cm man
 198 option.
 199 .It Cm i
 200 Print an
 201 .Cm id
 202 attribute.
 203 .It Cm \&?
 204 Print an arbitrary attribute.
 205 This format letter requires two
 206 .Vt char *
 207 arguments, the attribute name and the value.
 208 The name must not be
 209 .Dv NULL .
 210 .It Cm s
 211 Print a
 212 .Cm style
 213 attribute.
 214 If present, it must be the last format letter.
 215 It requires two
 216 .Va char *
 217 arguments.
 218 The first is the name of the style property, the second its value.
 219 The name must not be
 220 .Dv NULL .
 221 The
 222 .Cm s
 223 .Ar fmt
 224 letter can be repeated, each repetition requiring an additional pair of
 225 .Va char *
 226 arguments.
 227 .El
 228 .Pp
 229 .Fn print_otag
 230 uses the private function
 231 .Fn print_encode
 232 to take care of HTML encoding.
 233 If required by the element type, it remembers in
 234 .Fa h
 235 that the element is open.
 236 The function
 237 .Fn print_tagq
 238 is used to close out all open elements up to and including
 239 .Fa until ;
 240 .Fn print_stagq
 241 is a variant to close out all open elements up to but excluding
 242 .Fa suntil .
 243 .Pp
 244 The function
 245 .Fn print_text
 246 prints HTML element content.
 247 It uses the private function
 248 .Fn print_encode
 249 to take care of HTML encoding.
 250 If the document has requested a non-standard font, for example using a
 251 .Xr roff 7
 252 .Ic \ef
 253 font escape sequence,
 254 .Fn print_text
 255 wraps
 256 .Fa word
 257 in an HTML font selection element using the
 258 .Fn print_otag
 259 and
 260 .Fn print_tagq
 261 functions.
 262 .Pp
 263 The function
 264 .Fn html_make_id
 265 takes a node containing one or more text children
 266 and returns a newly allocated string containing the concatenation
 267 of the child strings, with blanks replaced by underscores.
 268 If the node
 269 .Fa n
 270 contains any non-text child node,
 271 .Fn html_make_id
 272 returns
 273 .Dv NULL
 274 instead.
 275 The caller is responsible for freeing the returned string.
 276 .Pp
 277 The function
 278 .Fn html_strlen
 279 counts the number of characters in
 280 .Fa cp .
 281 It is used as a crude estimate of the width needed to display a string.
 282 .Pp
 283 The functions
 284 .Fn print_eqn ,
 285 .Fn print_tbl ,
 286 and
 287 .Fn print_tblclose
 288 are not yet documented.
 289 .Sh FILES
 290 .Bl -tag -width mandoc_aux.c -compact
 291 .It Pa main.h
 292 declarations of public functions for use by the main program,
 293 not yet documented
 294 .It Pa html.h
 295 declarations of data types and private functions
 296 for use by language-specific HTML formatters
 297 .It Pa html.c
 298 main HTML formatting engine and utility functions
 299 .It Pa mdoc_html.c
 300 .Xr mdoc 7
 301 HTML formatter
 302 .It Pa man_html.c
 303 .Xr man 7
 304 HTML formatter
 305 .It Pa tbl_html.c
 306 .Xr tbl 7
 307 HTML formatter
 308 .It Pa eqn_html.c
 309 .Xr eqn 7
 310 HTML formatter
 311 .It Pa out.h
 312 declarations of data types and private functions
 313 for shared use by all mandoc formatters,
 314 not yet documented
 315 .It Pa out.c
 316 private functions for shared use by all mandoc formatters
 317 .It Pa mandoc_aux.h
 318 declarations of common mandoc utility functions, see
 319 .Xr mandoc 3
 320 .It Pa mandoc_aux.c
 321 implementation of common mandoc utility functions
 322 .El
 323 .Sh SEE ALSO
 324 .Xr mandoc 1 ,
 325 .Xr mandoc 3 ,
 326 .Xr man.cgi 8
 327 .Sh AUTHORS
 328 .An -nosplit
 329 The mandoc HTML formatter was written by
 330 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
 331 It is maintained by
 332 .An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
 333 who also wrote this manual.