Annotation of mandoc/mandoc_html.3, Revision 1.1
1.1 ! schwarze 1: .\" $Id$
! 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: .\"
! 17: .Dd $Mdocdate$
! 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"
! 33: .Fa "int sz"
! 34: .Fa "const struct htmlpair *p"
! 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 htmlpair
! 88: Holds one HTML attribute.
! 89: Members are
! 90: .Fa "enum htmlattr key"
! 91: and
! 92: .Fa "const char *val" .
! 93: Helper macros
! 94: .Fn PAIR_*
! 95: are provided to support initialization of such structures.
! 96: .It Vt struct tag
! 97: One entry for the LIFO stack of HTML elements.
! 98: Members are
! 99: .Fa "enum htmltag tag"
! 100: and
! 101: .Fa "struct tag *next" .
! 102: .El
! 103: .Ss Private interface functions
! 104: The function
! 105: .Fn print_gen_decls
! 106: prints the opening
! 107: .Ao Pf \&? Ic xml ? Ac
! 108: and
! 109: .Aq Pf \&! Ic DOCTYPE
! 110: declarations required for the current document type.
! 111: .Pp
! 112: The function
! 113: .Fn print_gen_head
! 114: prints the opening
! 115: .Aq Ic META
! 116: and
! 117: .Aq Ic LINK
! 118: elements for the document
! 119: .Aq Ic HEAD ,
! 120: using the
! 121: .Fa style
! 122: member of
! 123: .Fa h
! 124: unless that is
! 125: .Dv NULL .
! 126: It uses
! 127: .Fn print_otag
! 128: which takes care of properly encoding attributes,
! 129: which is relevant for the
! 130: .Fa style
! 131: link in particular.
! 132: .Pp
! 133: The function
! 134: .Fn print_otag
! 135: prints the start tag of an HTML element with the name
! 136: .Fa tag ,
! 137: including the
! 138: .Fa sz
! 139: attributes that can optionally be provided in the
! 140: .Fa p
! 141: array.
! 142: It uses the private function
! 143: .Fn print_attr
! 144: which in turn uses the private function
! 145: .Fn print_encode
! 146: to take care of HTML encoding.
! 147: If required by the element type, it remembers in
! 148: .Fa h
! 149: that the element is open.
! 150: The function
! 151: .Fn print_tagq
! 152: is used to close out all open elements up to and including
! 153: .Fa until ;
! 154: .Fn print_stagq
! 155: is a variant to close out all open elements up to but excluding
! 156: .Fa suntil .
! 157: .Pp
! 158: The function
! 159: .Fn print_text
! 160: prints HTML element content.
! 161: It uses the private function
! 162: .Fn print_encode
! 163: to take care of HTML encoding.
! 164: If the document has requested a non-standard font, for example using a
! 165: .Xr roff 7
! 166: .Ic \ef
! 167: font escape sequence,
! 168: .Fn print_text
! 169: wraps
! 170: .Fa word
! 171: in an HTML font selection element using the
! 172: .Fn print_otag
! 173: and
! 174: .Fn print_tagq
! 175: functions.
! 176: .Pp
! 177: The functions
! 178: .Fn bufinit ,
! 179: .Fn bufcat* ,
! 180: and
! 181: .Fn buffmt*
! 182: do not directly produce output but buffer text in the
! 183: .Fa buf
! 184: member of
! 185: .Fa h .
! 186: They are not used internally by
! 187: .Pa html.c
! 188: but intended for use by the language-specific formatters
! 189: to ease preparation of strings for the
! 190: .Fa p
! 191: argument of
! 192: .Fn print_otag
! 193: and for the
! 194: .Fa word
! 195: argument of
! 196: .Fn print_text .
! 197: Consequently, these functions do not do any HTML encoding.
! 198: .Pp
! 199: The functions
! 200: .Fn html_strlen ,
! 201: .Fn print_eqn ,
! 202: .Fn print_tbl ,
! 203: and
! 204: .Fn print_tblclose
! 205: are not yet documented.
! 206: .Sh FILES
! 207: .Bl -tag -width mandoc_aux.c -compact
! 208: .It Pa main.h
! 209: declarations of public functions for use by the main program,
! 210: not yet documented
! 211: .It Pa html.h
! 212: declarations of data types and private functions
! 213: for use by language-specific HTML formatters
! 214: .It Pa html.c
! 215: main HTML formatting engine and utility functions
! 216: .It Pa mdoc_html.c
! 217: .Xr mdoc 7
! 218: HTML formatter
! 219: .It Pa man_html.c
! 220: .Xr man 7
! 221: HTML formatter
! 222: .It Pa tbl_html.c
! 223: .Xr tbl 7
! 224: HTML formatter
! 225: .It Pa eqn_html.c
! 226: .Xr eqn 7
! 227: HTML formatter
! 228: .It Pa out.h
! 229: declarations of data types and private functions
! 230: for shared use by all mandoc formatters,
! 231: not yet documented
! 232: .It Pa out.c
! 233: private functions for shared use by all mandoc formatters
! 234: .It Pa mandoc_aux.h
! 235: declarations of common mandoc utility functions, see
! 236: .Xr mandoc 3
! 237: .It Pa mandoc_aux.c
! 238: implementation of common mandoc utility functions
! 239: .El
! 240: .Sh SEE ALSO
! 241: .Xr mandoc 1 ,
! 242: .Xr mandoc 3 ,
! 243: .Xr man.cgi 8
! 244: .Sh AUTHORS
! 245: .An -nosplit
! 246: The mandoc HTML formatter was written by
! 247: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
! 248: This manual was written by
! 249: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb