Annotation of mandoc/mandoc_html.3, Revision 1.2
1.2 ! schwarze 1: .\" $Id: mandoc_html.3,v 1.1 2014/07/23 18:13:09 schwarze Exp $
1.1 schwarze 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: .\"
1.2 ! schwarze 17: .Dd $Mdocdate: July 23 2014 $
1.1 schwarze 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"
1.2 ! schwarze 33: .Fa "const char *fmt"
! 34: .Fa ...
1.1 schwarze 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 tag
88: One entry for the LIFO stack of HTML elements.
89: Members are
90: .Fa "enum htmltag tag"
91: and
92: .Fa "struct tag *next" .
93: .El
94: .Ss Private interface functions
95: The function
96: .Fn print_gen_decls
97: prints the opening
98: .Ao Pf \&? Ic xml ? Ac
99: and
100: .Aq Pf \&! Ic DOCTYPE
101: declarations required for the current document type.
102: .Pp
103: The function
104: .Fn print_gen_head
105: prints the opening
106: .Aq Ic META
107: and
108: .Aq Ic LINK
109: elements for the document
110: .Aq Ic HEAD ,
111: using the
112: .Fa style
113: member of
114: .Fa h
115: unless that is
116: .Dv NULL .
117: It uses
118: .Fn print_otag
119: which takes care of properly encoding attributes,
120: which is relevant for the
121: .Fa style
122: link in particular.
123: .Pp
124: The function
125: .Fn print_otag
126: prints the start tag of an HTML element with the name
127: .Fa tag ,
1.2 ! schwarze 128: optionally including the attributes specified by
! 129: .Fa fmt .
! 130: If
! 131: .Fa fmt
! 132: is the empty string, no attributes are written.
! 133: Each letter of
! 134: .Fa fmt
! 135: specifies one attribute to write.
! 136: Most attributes require one
! 137: .Va char *
! 138: argument which becomes the value of the attribute.
! 139: The arguments have to be given in the same order as the attribute letters.
! 140: .Bl -tag -width 1n -offset indent
! 141: .It Cm c
! 142: Print a
! 143: .Cm class
! 144: attribute.
! 145: .It Cm h
! 146: Print a
! 147: .Cm href
! 148: attribute.
! 149: .It Cm i
! 150: Print an
! 151: .Cm id
! 152: attribute.
! 153: .It Cm \&?
! 154: Print an arbitrary attribute.
! 155: This format letter requires two
! 156: .Vt char *
! 157: arguments, the attribute name and the value.
! 158: .It Cm s
! 159: Print a
! 160: .Cm style
! 161: attribute.
! 162: If present, it must be the last format letter.
! 163: In contrast to the other format letters, this one does not yet
! 164: print the value and does not require an argument.
! 165: Instead, the rest of the format string consists of pairs of
! 166: argument type letters and style name letters.
! 167: .El
! 168: .Pp
! 169: Argument type letters each require on argument as follows:
! 170: .Bl -tag -width 1n -offset indent
! 171: .It Cm h
! 172: Requires one
! 173: .Vt int
! 174: argument, interpreted as a horizontal length in units of
! 175: .Dv SCALE_EN .
! 176: .It Cm s
! 177: Requires one
! 178: .Vt char *
! 179: argument, used as a style value.
! 180: .It Cm u
! 181: Requires one
! 182: .Vt struct roffsu *
! 183: argument, used as a length.
! 184: .It Cm v
! 185: Requires one
! 186: .Vt int
! 187: argument, interpreted as a vertical length in units of
! 188: .Dv SCALE_VS .
! 189: .It Cm w
! 190: Requires one
! 191: .Vt char *
! 192: argument, interpreted as an
! 193: .Xr mdoc 7 Ns -style
! 194: width specifier.
! 195: .El
! 196: .Pp
! 197: Style name letters decide what to do with the preceding argument:
! 198: .Bl -tag -width 1n -offset indent
! 199: .It Cm b
! 200: Set
! 201: .Cm margin-bottom
! 202: to the given length.
! 203: .It Cm h
! 204: Set
! 205: .Cm height
! 206: to the given length.
! 207: .It Cm i
! 208: Set
! 209: .Cm text-indent
! 210: to the given length.
! 211: .It Cm l
! 212: Set
! 213: .Cm margin-left
! 214: to the given length.
! 215: .It Cm t
! 216: Set
! 217: .Cm margin-top
! 218: to the given length.
! 219: .It Cm w
! 220: Set
! 221: .Cm width
! 222: to the given length.
! 223: .It Cm W
! 224: Set
! 225: .Cm min-width
! 226: to the given length.
! 227: .It Cm \&?
! 228: The special pair
! 229: .Cm s?
! 230: requires two
! 231: .Vt char *
! 232: arguments.
! 233: The first is the style name, the second its value.
! 234: .El
! 235: .Pp
! 236: .Fn print_otag
! 237: uses the private function
1.1 schwarze 238: .Fn print_attr
239: which in turn uses the private function
240: .Fn print_encode
241: to take care of HTML encoding.
242: If required by the element type, it remembers in
243: .Fa h
244: that the element is open.
245: The function
246: .Fn print_tagq
247: is used to close out all open elements up to and including
248: .Fa until ;
249: .Fn print_stagq
250: is a variant to close out all open elements up to but excluding
251: .Fa suntil .
252: .Pp
253: The function
254: .Fn print_text
255: prints HTML element content.
256: It uses the private function
257: .Fn print_encode
258: to take care of HTML encoding.
259: If the document has requested a non-standard font, for example using a
260: .Xr roff 7
261: .Ic \ef
262: font escape sequence,
263: .Fn print_text
264: wraps
265: .Fa word
266: in an HTML font selection element using the
267: .Fn print_otag
268: and
269: .Fn print_tagq
270: functions.
271: .Pp
272: The functions
273: .Fn bufinit ,
274: .Fn bufcat* ,
275: and
276: .Fn buffmt*
277: do not directly produce output but buffer text in the
278: .Fa buf
279: member of
280: .Fa h .
281: They are not used internally by
282: .Pa html.c
283: but intended for use by the language-specific formatters
284: to ease preparation of strings for the
285: .Fa p
286: argument of
287: .Fn print_otag
288: and for the
289: .Fa word
290: argument of
291: .Fn print_text .
292: Consequently, these functions do not do any HTML encoding.
293: .Pp
294: The functions
295: .Fn html_strlen ,
296: .Fn print_eqn ,
297: .Fn print_tbl ,
298: and
299: .Fn print_tblclose
300: are not yet documented.
301: .Sh FILES
302: .Bl -tag -width mandoc_aux.c -compact
303: .It Pa main.h
304: declarations of public functions for use by the main program,
305: not yet documented
306: .It Pa html.h
307: declarations of data types and private functions
308: for use by language-specific HTML formatters
309: .It Pa html.c
310: main HTML formatting engine and utility functions
311: .It Pa mdoc_html.c
312: .Xr mdoc 7
313: HTML formatter
314: .It Pa man_html.c
315: .Xr man 7
316: HTML formatter
317: .It Pa tbl_html.c
318: .Xr tbl 7
319: HTML formatter
320: .It Pa eqn_html.c
321: .Xr eqn 7
322: HTML formatter
323: .It Pa out.h
324: declarations of data types and private functions
325: for shared use by all mandoc formatters,
326: not yet documented
327: .It Pa out.c
328: private functions for shared use by all mandoc formatters
329: .It Pa mandoc_aux.h
330: declarations of common mandoc utility functions, see
331: .Xr mandoc 3
332: .It Pa mandoc_aux.c
333: implementation of common mandoc utility functions
334: .El
335: .Sh SEE ALSO
336: .Xr mandoc 1 ,
337: .Xr mandoc 3 ,
338: .Xr man.cgi 8
339: .Sh AUTHORS
340: .An -nosplit
341: The mandoc HTML formatter was written by
342: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
343: This manual was written by
344: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mandoc_html.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc