Annotation of mandoc/mandoc_html.3, Revision 1.20
1.20 ! schwarze 1: .\" $Id: mandoc_html.3,v 1.19 2019/01/11 12:56:43 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.20 ! schwarze 17: .Dd $Mdocdate: January 11 2019 $
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"
1.20 ! schwarze 56: .Fa "int unique"
1.7 schwarze 57: .Fc
1.20 ! schwarze 58: .Ft struct tag *
! 59: .Fo print_otag_id
! 60: .Fa "struct html *h"
! 61: .Fa "enum htmltag tag"
! 62: .Fa "const char *cattr"
! 63: .Fa "struct roff_node *n"
1.7 schwarze 64: .Fc
1.1 schwarze 65: .Sh DESCRIPTION
66: The mandoc HTML formatter is not a formal library.
67: However, as it is compiled into more than one program, in particular
68: .Xr mandoc 1
69: and
70: .Xr man.cgi 8 ,
71: and because it may be security-critical in some contexts,
72: some documentation is useful to help to use it correctly and
73: to prevent XSS vulnerabilities.
74: .Pp
75: The formatter produces HTML output on the standard output.
76: Since proper escaping is usually required and best taken care of
77: at one central place, the language-specific formatters
78: .Po
79: .Pa *_html.c ,
80: see
81: .Sx FILES
82: .Pc
83: are not supposed to print directly to
84: .Dv stdout
85: using functions like
86: .Xr printf 3 ,
87: .Xr putc 3 ,
88: .Xr puts 3 ,
89: or
90: .Xr write 2 .
91: Instead, they are expected to use the output functions declared in
92: .Pa html.h
93: and implemented as part of the main HTML formatting engine in
94: .Pa html.c .
95: .Ss Data structures
96: These structures are declared in
97: .Pa html.h .
98: .Bl -tag -width Ds
99: .It Vt struct html
100: Internal state of the HTML formatter.
101: .It Vt struct tag
102: One entry for the LIFO stack of HTML elements.
103: Members are
104: .Fa "enum htmltag tag"
105: and
106: .Fa "struct tag *next" .
107: .El
108: .Ss Private interface functions
109: The function
110: .Fn print_gen_decls
111: prints the opening
112: .Ao Pf \&? Ic xml ? Ac
113: and
114: .Aq Pf \&! Ic DOCTYPE
115: declarations required for the current document type.
1.11 schwarze 116: .Pp
117: The function
118: .Fn print_gen_comment
119: prints the leading comments, usually containing a Copyright notice
120: and license, as an HTML comment.
121: It is intended to be called right after opening the
122: .Aq Ic HTML
123: element.
124: Pass the first
125: .Dv ROFFT_COMMENT
126: node in
127: .Fa n .
1.1 schwarze 128: .Pp
129: The function
130: .Fn print_gen_head
131: prints the opening
132: .Aq Ic META
133: and
134: .Aq Ic LINK
135: elements for the document
136: .Aq Ic HEAD ,
137: using the
138: .Fa style
139: member of
140: .Fa h
141: unless that is
142: .Dv NULL .
143: It uses
144: .Fn print_otag
145: which takes care of properly encoding attributes,
146: which is relevant for the
147: .Fa style
148: link in particular.
149: .Pp
150: The function
151: .Fn print_otag
152: prints the start tag of an HTML element with the name
153: .Fa tag ,
1.2 schwarze 154: optionally including the attributes specified by
155: .Fa fmt .
156: If
157: .Fa fmt
158: is the empty string, no attributes are written.
159: Each letter of
160: .Fa fmt
161: specifies one attribute to write.
162: Most attributes require one
163: .Va char *
164: argument which becomes the value of the attribute.
165: The arguments have to be given in the same order as the attribute letters.
1.5 schwarze 166: If an argument is
167: .Dv NULL ,
168: the respective attribute is not written.
1.2 schwarze 169: .Bl -tag -width 1n -offset indent
170: .It Cm c
171: Print a
172: .Cm class
173: attribute.
174: .It Cm h
175: Print a
176: .Cm href
177: attribute.
1.3 schwarze 178: This attribute letter can optionally be followed by a modifier letter.
179: If followed by
180: .Cm R ,
181: it formats the link as a local one by prefixing a
182: .Sq #
183: character.
184: If followed by
185: .Cm I ,
186: it interpretes the argument as a header file name
187: and generates a link using the
188: .Xr mandoc 1
189: .Fl O Cm includes
190: option.
191: If followed by
192: .Cm M ,
193: it takes two arguments instead of one, a manual page name and
194: section, and formats them as a link to a manual page using the
195: .Xr mandoc 1
196: .Fl O Cm man
197: option.
1.2 schwarze 198: .It Cm i
199: Print an
200: .Cm id
201: attribute.
202: .It Cm \&?
203: Print an arbitrary attribute.
204: This format letter requires two
205: .Vt char *
206: arguments, the attribute name and the value.
1.5 schwarze 207: The name must not be
208: .Dv NULL .
1.2 schwarze 209: .It Cm s
210: Print a
211: .Cm style
212: attribute.
213: If present, it must be the last format letter.
1.17 schwarze 214: It requires two
215: .Va char *
1.2 schwarze 216: arguments.
1.17 schwarze 217: The first is the name of the style property, the second its value.
1.18 schwarze 218: The name must not be
219: .Dv NULL .
220: The
221: .Cm s
222: .Ar fmt
223: letter can be repeated, each repetition requiring an additional pair of
224: .Va char *
225: arguments.
1.2 schwarze 226: .El
227: .Pp
228: .Fn print_otag
229: uses the private function
1.1 schwarze 230: .Fn print_encode
231: to take care of HTML encoding.
232: If required by the element type, it remembers in
233: .Fa h
234: that the element is open.
235: The function
236: .Fn print_tagq
237: is used to close out all open elements up to and including
238: .Fa until ;
239: .Fn print_stagq
240: is a variant to close out all open elements up to but excluding
241: .Fa suntil .
242: .Pp
243: The function
244: .Fn print_text
245: prints HTML element content.
246: It uses the private function
247: .Fn print_encode
248: to take care of HTML encoding.
249: If the document has requested a non-standard font, for example using a
250: .Xr roff 7
251: .Ic \ef
252: font escape sequence,
253: .Fn print_text
254: wraps
255: .Fa word
256: in an HTML font selection element using the
257: .Fn print_otag
258: and
259: .Fn print_tagq
260: functions.
261: .Pp
1.7 schwarze 262: The function
263: .Fn html_make_id
1.20 ! schwarze 264: allocates a string to be used for the
! 265: .Cm id
! 266: attribute of an HTML element and/or as a segment identifier for a URI in an
! 267: .Aq Ic A
! 268: element.
! 269: If
! 270: .Fa n
! 271: contains a
! 272: .Fa string
! 273: attribute, it is used; otherwise, child nodes are used.
! 274: If
1.7 schwarze 275: .Fa n
1.20 ! schwarze 276: is an
! 277: .Ic \&Sh ,
! 278: .Ic \&Ss ,
! 279: .Ic \&Sx ,
! 280: .Ic SH ,
! 281: or
! 282: .Ic SS
! 283: node, the resulting string is the concatenation of the child strings;
! 284: for other node types, only the first child is used.
! 285: Bytes not permitted in URI-fragment strings are replaced by underscores.
! 286: If any of the children to be used is not a text node,
! 287: no string is generated and
1.7 schwarze 288: .Dv NULL
1.20 ! schwarze 289: is returned instead.
! 290: If the
! 291: .Fa unique
! 292: argument is non-zero, deduplication is performed by appending an
! 293: underscore and a decimal integer, if necessary.
1.7 schwarze 294: .Pp
295: The function
1.20 ! schwarze 296: .Fn print_otag_id
! 297: opens a
! 298: .Fa tag
! 299: element of class
! 300: .Fa cattr
! 301: for the node
! 302: .Fa n .
! 303: If the flag
! 304: .Dv NODE_ID
! 305: is set in
! 306: .Fa n ,
! 307: it attempts to generate an
! 308: .Cm id
! 309: attribute with
! 310: .Fn html_make_id .
! 311: If an
! 312: .Cm id
! 313: attribute is written,
! 314: .Fn print_otag_id
! 315: also adds an
! 316: .Aq Ic A
! 317: element of class
! 318: .Qq permalink :
! 319: outside if
! 320: .Fa n
! 321: generates a phrasing element, or inside otherwise.
! 322: This function is a wrapper around
! 323: .Fn html_make_id
! 324: and
! 325: .Fn print_otag ,
! 326: fixing the
! 327: .Fa unique
! 328: argument to 1 and the
! 329: .Fa fmt
! 330: arguments to
! 331: .Qq chR
! 332: and
! 333: .Qq ci ,
! 334: respectively.
1.7 schwarze 335: .Pp
1.1 schwarze 336: The functions
337: .Fn print_eqn ,
338: .Fn print_tbl ,
339: and
340: .Fn print_tblclose
341: are not yet documented.
1.20 ! schwarze 342: .Sh RETURN VALUES
! 343: The functions
! 344: .Fn print_otag
! 345: and
! 346: .Fn print_otag_id
! 347: return a pointer to a new element on the stack of HTML elements.
! 348: When
! 349: .Fn print_otag_id
! 350: opens two elements, a pointer to the outer one is returned.
! 351: The memory pointed to is owned by the library and is automatically
! 352: .Xr free 3 Ns d
! 353: when
! 354: .Fn print_tagq
! 355: is called on it or when
! 356: .Fn print_stagq
! 357: is called on a parent element.
! 358: .Pp
! 359: The function
! 360: .Fn html_make_id
! 361: returns a newly allocated string or
! 362: .Dv NULL
! 363: if
! 364: .Fa n
! 365: lacks text data to create the attribute from.
! 366: If the
! 367: .Fa unique
! 368: argument is 0, the caller is responsible for
! 369: .Xr free 3 Ns ing
! 370: the returned string after using it.
! 371: If the
! 372: .Fa unique
! 373: argument is non-zero, the
! 374: .Va id_unique
! 375: ohash table is used for de-duplication and owns the returned string.
! 376: In this case, it will be freed automatically by
! 377: .Fn html_reset
! 378: or
! 379: .Fn html_free .
! 380: .Pp
! 381: In case of
! 382: .Xr malloc 3
! 383: failure, these functions do not return but call
! 384: .Xr err 3 .
1.1 schwarze 385: .Sh FILES
386: .Bl -tag -width mandoc_aux.c -compact
387: .It Pa main.h
388: declarations of public functions for use by the main program,
389: not yet documented
390: .It Pa html.h
391: declarations of data types and private functions
392: for use by language-specific HTML formatters
393: .It Pa html.c
394: main HTML formatting engine and utility functions
395: .It Pa mdoc_html.c
396: .Xr mdoc 7
397: HTML formatter
398: .It Pa man_html.c
399: .Xr man 7
400: HTML formatter
401: .It Pa tbl_html.c
402: .Xr tbl 7
403: HTML formatter
404: .It Pa eqn_html.c
405: .Xr eqn 7
406: HTML formatter
407: .It Pa out.h
408: declarations of data types and private functions
409: for shared use by all mandoc formatters,
410: not yet documented
411: .It Pa out.c
412: private functions for shared use by all mandoc formatters
413: .It Pa mandoc_aux.h
414: declarations of common mandoc utility functions, see
415: .Xr mandoc 3
416: .It Pa mandoc_aux.c
417: implementation of common mandoc utility functions
418: .El
419: .Sh SEE ALSO
420: .Xr mandoc 1 ,
421: .Xr mandoc 3 ,
422: .Xr man.cgi 8
423: .Sh AUTHORS
424: .An -nosplit
425: The mandoc HTML formatter was written by
426: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.5 schwarze 427: It is maintained by
428: .An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
429: 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