Annotation of mandoc/mandoc_html.3, Revision 1.11
1.11 ! schwarze 1: .\" $Id: mandoc_html.3,v 1.10 2017/07/15 17:57:51 schwarze Exp $
1.1 schwarze 2: .\"
1.11 ! schwarze 3: .\" Copyright (c) 2014, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
1.1 schwarze 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.11 ! schwarze 17: .Dd $Mdocdate: July 15 2017 $
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
1.11 ! schwarze 28: .Fn print_gen_comment "struct html *h" "struct roff_node *n"
! 29: .Ft void
1.1 schwarze 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"
1.2 schwarze 35: .Fa "const char *fmt"
36: .Fa ...
1.1 schwarze 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
1.7 schwarze 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
1.1 schwarze 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.
1.11 ! schwarze 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 .
1.1 schwarze 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 ,
1.2 schwarze 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.
1.5 schwarze 162: If an argument is
163: .Dv NULL ,
164: the respective attribute is not written.
1.2 schwarze 165: .Bl -tag -width 1n -offset indent
166: .It Cm c
167: Print a
168: .Cm class
169: attribute.
1.6 schwarze 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.
1.2 schwarze 175: .It Cm h
176: Print a
177: .Cm href
178: attribute.
1.3 schwarze 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.
1.2 schwarze 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.
1.5 schwarze 208: The name must not be
209: .Dv NULL .
1.2 schwarze 210: .It Cm s
211: Print a
212: .Cm style
213: attribute.
214: If present, it must be the last format letter.
215: In contrast to the other format letters, this one does not yet
1.5 schwarze 216: print the value and does not take an argument.
1.2 schwarze 217: Instead, the rest of the format string consists of pairs of
218: argument type letters and style name letters.
219: .El
220: .Pp
1.8 schwarze 221: Argument type letters each require one argument as follows:
1.2 schwarze 222: .Bl -tag -width 1n -offset indent
223: .It Cm h
224: Requires one
225: .Vt int
226: argument, interpreted as a horizontal length in units of
227: .Dv SCALE_EN .
228: .It Cm s
229: Requires one
230: .Vt char *
231: argument, used as a style value.
232: .It Cm u
233: Requires one
234: .Vt struct roffsu *
235: argument, used as a length.
236: .It Cm w
237: Requires one
238: .Vt char *
239: argument, interpreted as an
240: .Xr mdoc 7 Ns -style
241: width specifier.
1.5 schwarze 242: If the argument is
243: .Dv NULL ,
244: nothing is printed for this pair.
1.8 schwarze 245: .Pp
246: The
247: .Cm w
1.10 schwarze 248: argument type letter can optionally be followed by one, two, or three
1.8 schwarze 249: modifier letters.
250: The modifier
1.10 schwarze 251: .Cm *
252: suppresses printing of the pair if the argument matches 6n.
253: The modifier
1.8 schwarze 254: .Cm +
1.10 schwarze 255: increases the width by 20% to make even bold text fit
256: and adds three units for padding between columns.
1.8 schwarze 257: The modifier
258: .Cm \-
259: makes the width negative by multiplying it with \-1.
1.2 schwarze 260: .El
261: .Pp
262: Style name letters decide what to do with the preceding argument:
263: .Bl -tag -width 1n -offset indent
264: .It Cm h
265: Set
266: .Cm height
267: to the given length.
268: .It Cm i
269: Set
270: .Cm text-indent
271: to the given length.
272: .It Cm l
273: Set
274: .Cm margin-left
275: to the given length.
276: .It Cm w
277: Set
278: .Cm width
279: to the given length.
280: .It Cm W
281: Set
282: .Cm min-width
283: to the given length.
284: .It Cm \&?
285: The special pair
286: .Cm s?
287: requires two
288: .Vt char *
289: arguments.
290: The first is the style name, the second its value.
1.5 schwarze 291: The style name must not be
292: .Dv NULL .
1.2 schwarze 293: .El
294: .Pp
295: .Fn print_otag
296: uses the private function
1.1 schwarze 297: .Fn print_encode
298: to take care of HTML encoding.
299: If required by the element type, it remembers in
300: .Fa h
301: that the element is open.
302: The function
303: .Fn print_tagq
304: is used to close out all open elements up to and including
305: .Fa until ;
306: .Fn print_stagq
307: is a variant to close out all open elements up to but excluding
308: .Fa suntil .
309: .Pp
310: The function
311: .Fn print_text
312: prints HTML element content.
313: It uses the private function
314: .Fn print_encode
315: to take care of HTML encoding.
316: If the document has requested a non-standard font, for example using a
317: .Xr roff 7
318: .Ic \ef
319: font escape sequence,
320: .Fn print_text
321: wraps
322: .Fa word
323: in an HTML font selection element using the
324: .Fn print_otag
325: and
326: .Fn print_tagq
327: functions.
328: .Pp
1.7 schwarze 329: The function
330: .Fn html_make_id
331: takes a node containing one or more text children
332: and returns a newly allocated string containing the concatenation
333: of the child strings, with blanks replaced by underscores.
334: If the node
335: .Fa n
336: contains any non-text child node,
337: .Fn html_make_id
338: returns
339: .Dv NULL
340: instead.
341: The caller is responsible for freeing the returned string.
342: .Pp
343: The function
344: .Fn html_strlen
345: counts the number of characters in
346: .Fa cp .
347: It is used as a crude estimate of the width needed to display a string.
348: .Pp
1.1 schwarze 349: The functions
350: .Fn print_eqn ,
351: .Fn print_tbl ,
352: and
353: .Fn print_tblclose
354: are not yet documented.
355: .Sh FILES
356: .Bl -tag -width mandoc_aux.c -compact
357: .It Pa main.h
358: declarations of public functions for use by the main program,
359: not yet documented
360: .It Pa html.h
361: declarations of data types and private functions
362: for use by language-specific HTML formatters
363: .It Pa html.c
364: main HTML formatting engine and utility functions
365: .It Pa mdoc_html.c
366: .Xr mdoc 7
367: HTML formatter
368: .It Pa man_html.c
369: .Xr man 7
370: HTML formatter
371: .It Pa tbl_html.c
372: .Xr tbl 7
373: HTML formatter
374: .It Pa eqn_html.c
375: .Xr eqn 7
376: HTML formatter
377: .It Pa out.h
378: declarations of data types and private functions
379: for shared use by all mandoc formatters,
380: not yet documented
381: .It Pa out.c
382: private functions for shared use by all mandoc formatters
383: .It Pa mandoc_aux.h
384: declarations of common mandoc utility functions, see
385: .Xr mandoc 3
386: .It Pa mandoc_aux.c
387: implementation of common mandoc utility functions
388: .El
389: .Sh SEE ALSO
390: .Xr mandoc 1 ,
391: .Xr mandoc 3 ,
392: .Xr man.cgi 8
393: .Sh AUTHORS
394: .An -nosplit
395: The mandoc HTML formatter was written by
396: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.5 schwarze 397: It is maintained by
398: .An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
399: who also wrote this manual.
CVSweb