Annotation of mandoc/mandoc_html.3, Revision 1.6
1.6 ! schwarze 1: .\" $Id: mandoc_html.3,v 1.5 2017/01/28 22:36:38 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.6 ! schwarze 17: .Dd $Mdocdate: January 28 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
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.
1.5 schwarze 140: If an argument is
141: .Dv NULL ,
142: the respective attribute is not written.
1.2 schwarze 143: .Bl -tag -width 1n -offset indent
144: .It Cm c
145: Print a
146: .Cm class
147: attribute.
1.6 ! schwarze 148: This attribute letter can optionally be followed by the modifier letter
! 149: .Cm T .
! 150: In that case, a
! 151: .Cm title
! 152: attribute with the same value is also printed.
1.2 schwarze 153: .It Cm h
154: Print a
155: .Cm href
156: attribute.
1.3 schwarze 157: This attribute letter can optionally be followed by a modifier letter.
158: If followed by
159: .Cm R ,
160: it formats the link as a local one by prefixing a
161: .Sq #
162: character.
163: If followed by
164: .Cm I ,
165: it interpretes the argument as a header file name
166: and generates a link using the
167: .Xr mandoc 1
168: .Fl O Cm includes
169: option.
170: If followed by
171: .Cm M ,
172: it takes two arguments instead of one, a manual page name and
173: section, and formats them as a link to a manual page using the
174: .Xr mandoc 1
175: .Fl O Cm man
176: option.
1.2 schwarze 177: .It Cm i
178: Print an
179: .Cm id
180: attribute.
181: .It Cm \&?
182: Print an arbitrary attribute.
183: This format letter requires two
184: .Vt char *
185: arguments, the attribute name and the value.
1.5 schwarze 186: The name must not be
187: .Dv NULL .
1.2 schwarze 188: .It Cm s
189: Print a
190: .Cm style
191: attribute.
192: If present, it must be the last format letter.
193: In contrast to the other format letters, this one does not yet
1.5 schwarze 194: print the value and does not take an argument.
1.2 schwarze 195: Instead, the rest of the format string consists of pairs of
196: argument type letters and style name letters.
197: .El
198: .Pp
199: Argument type letters each require on argument as follows:
200: .Bl -tag -width 1n -offset indent
201: .It Cm h
202: Requires one
203: .Vt int
204: argument, interpreted as a horizontal length in units of
205: .Dv SCALE_EN .
206: .It Cm s
207: Requires one
208: .Vt char *
209: argument, used as a style value.
210: .It Cm u
211: Requires one
212: .Vt struct roffsu *
213: argument, used as a length.
214: .It Cm v
215: Requires one
216: .Vt int
217: argument, interpreted as a vertical length in units of
218: .Dv SCALE_VS .
219: .It Cm w
220: Requires one
221: .Vt char *
222: argument, interpreted as an
223: .Xr mdoc 7 Ns -style
224: width specifier.
1.5 schwarze 225: If the argument is
226: .Dv NULL ,
227: nothing is printed for this pair.
1.4 schwarze 228: .It Cm W
229: Similar to
230: .Cm w ,
231: but makes the width negative by multiplying it with \(mi1.
1.2 schwarze 232: .El
233: .Pp
234: Style name letters decide what to do with the preceding argument:
235: .Bl -tag -width 1n -offset indent
236: .It Cm b
237: Set
238: .Cm margin-bottom
239: to the given length.
240: .It Cm h
241: Set
242: .Cm height
243: to the given length.
244: .It Cm i
245: Set
246: .Cm text-indent
247: to the given length.
248: .It Cm l
249: Set
250: .Cm margin-left
251: to the given length.
252: .It Cm t
253: Set
254: .Cm margin-top
255: to the given length.
256: .It Cm w
257: Set
258: .Cm width
259: to the given length.
260: .It Cm W
261: Set
262: .Cm min-width
263: to the given length.
264: .It Cm \&?
265: The special pair
266: .Cm s?
267: requires two
268: .Vt char *
269: arguments.
270: The first is the style name, the second its value.
1.5 schwarze 271: The style name must not be
272: .Dv NULL .
1.2 schwarze 273: .El
274: .Pp
275: .Fn print_otag
276: uses the private function
1.1 schwarze 277: .Fn print_encode
278: to take care of HTML encoding.
279: If required by the element type, it remembers in
280: .Fa h
281: that the element is open.
282: The function
283: .Fn print_tagq
284: is used to close out all open elements up to and including
285: .Fa until ;
286: .Fn print_stagq
287: is a variant to close out all open elements up to but excluding
288: .Fa suntil .
289: .Pp
290: The function
291: .Fn print_text
292: prints HTML element content.
293: It uses the private function
294: .Fn print_encode
295: to take care of HTML encoding.
296: If the document has requested a non-standard font, for example using a
297: .Xr roff 7
298: .Ic \ef
299: font escape sequence,
300: .Fn print_text
301: wraps
302: .Fa word
303: in an HTML font selection element using the
304: .Fn print_otag
305: and
306: .Fn print_tagq
307: functions.
308: .Pp
309: The functions
310: .Fn html_strlen ,
311: .Fn print_eqn ,
312: .Fn print_tbl ,
313: and
314: .Fn print_tblclose
315: are not yet documented.
316: .Sh FILES
317: .Bl -tag -width mandoc_aux.c -compact
318: .It Pa main.h
319: declarations of public functions for use by the main program,
320: not yet documented
321: .It Pa html.h
322: declarations of data types and private functions
323: for use by language-specific HTML formatters
324: .It Pa html.c
325: main HTML formatting engine and utility functions
326: .It Pa mdoc_html.c
327: .Xr mdoc 7
328: HTML formatter
329: .It Pa man_html.c
330: .Xr man 7
331: HTML formatter
332: .It Pa tbl_html.c
333: .Xr tbl 7
334: HTML formatter
335: .It Pa eqn_html.c
336: .Xr eqn 7
337: HTML formatter
338: .It Pa out.h
339: declarations of data types and private functions
340: for shared use by all mandoc formatters,
341: not yet documented
342: .It Pa out.c
343: private functions for shared use by all mandoc formatters
344: .It Pa mandoc_aux.h
345: declarations of common mandoc utility functions, see
346: .Xr mandoc 3
347: .It Pa mandoc_aux.c
348: implementation of common mandoc utility functions
349: .El
350: .Sh SEE ALSO
351: .Xr mandoc 1 ,
352: .Xr mandoc 3 ,
353: .Xr man.cgi 8
354: .Sh AUTHORS
355: .An -nosplit
356: The mandoc HTML formatter was written by
357: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.5 schwarze 358: It is maintained by
359: .An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
360: 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