Annotation of mandoc/mandoc_html.3, Revision 1.8
1.8 ! schwarze 1: .\" $Id: mandoc_html.3,v 1.7 2017/03/15 11:29:53 schwarze Exp $
1.1 schwarze 2: .\"
1.3 schwarze 3: .\" Copyright (c) 2014, 2017 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.8 ! schwarze 17: .Dd $Mdocdate: March 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
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
1.7 schwarze 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
1.1 schwarze 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 ,
1.2 schwarze 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.
1.5 schwarze 148: If an argument is
149: .Dv NULL ,
150: the respective attribute is not written.
1.2 schwarze 151: .Bl -tag -width 1n -offset indent
152: .It Cm c
153: Print a
154: .Cm class
155: attribute.
1.6 schwarze 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.
1.2 schwarze 161: .It Cm h
162: Print a
163: .Cm href
164: attribute.
1.3 schwarze 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.
1.2 schwarze 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.
1.5 schwarze 194: The name must not be
195: .Dv NULL .
1.2 schwarze 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
1.5 schwarze 202: print the value and does not take an argument.
1.2 schwarze 203: Instead, the rest of the format string consists of pairs of
204: argument type letters and style name letters.
205: .El
206: .Pp
1.8 ! schwarze 207: Argument type letters each require one argument as follows:
1.2 schwarze 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.
1.5 schwarze 233: If the argument is
234: .Dv NULL ,
235: nothing is printed for this pair.
1.8 ! schwarze 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.
1.2 schwarze 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.
1.5 schwarze 287: The style name must not be
288: .Dv NULL .
1.2 schwarze 289: .El
290: .Pp
291: .Fn print_otag
292: uses the private function
1.1 schwarze 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
1.7 schwarze 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
1.1 schwarze 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 .
1.5 schwarze 393: It is maintained by
394: .An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
395: who also wrote this manual.
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