[BACK]Return to mandoc_html.3 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mandoc_html.3, Revision 1.9

1.9     ! schwarze    1: .\"    $Id: mandoc_html.3,v 1.8 2017/05/12 17:58:21 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.9     ! schwarze   17: .Dd $Mdocdate: May 12 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 w
                    223: Requires one
                    224: .Vt char *
                    225: argument, interpreted as an
                    226: .Xr mdoc 7 Ns -style
                    227: width specifier.
1.5       schwarze  228: If the argument is
                    229: .Dv NULL ,
                    230: nothing is printed for this pair.
1.8       schwarze  231: .Pp
                    232: The
                    233: .Cm w
                    234: argument type letter can optionally be followed by one or two
                    235: modifier letters.
                    236: The modifier
                    237: .Cm +
                    238: increases the width by 10% to make even bold text fit
                    239: and adds two units for padding between columns.
                    240: The modifier
                    241: .Cm \-
                    242: makes the width negative by multiplying it with \-1.
1.2       schwarze  243: .El
                    244: .Pp
                    245: Style name letters decide what to do with the preceding argument:
                    246: .Bl -tag -width 1n -offset indent
                    247: .It Cm h
                    248: Set
                    249: .Cm height
                    250: to the given length.
                    251: .It Cm i
                    252: Set
                    253: .Cm text-indent
                    254: to the given length.
                    255: .It Cm l
                    256: Set
                    257: .Cm margin-left
                    258: to the given length.
                    259: .It Cm w
                    260: Set
                    261: .Cm width
                    262: to the given length.
                    263: .It Cm W
                    264: Set
                    265: .Cm min-width
                    266: to the given length.
                    267: .It Cm \&?
                    268: The special pair
                    269: .Cm s?
                    270: requires two
                    271: .Vt char *
                    272: arguments.
                    273: The first is the style name, the second its value.
1.5       schwarze  274: The style name must not be
                    275: .Dv NULL .
1.2       schwarze  276: .El
                    277: .Pp
                    278: .Fn print_otag
                    279: uses the private function
1.1       schwarze  280: .Fn print_encode
                    281: to take care of HTML encoding.
                    282: If required by the element type, it remembers in
                    283: .Fa h
                    284: that the element is open.
                    285: The function
                    286: .Fn print_tagq
                    287: is used to close out all open elements up to and including
                    288: .Fa until ;
                    289: .Fn print_stagq
                    290: is a variant to close out all open elements up to but excluding
                    291: .Fa suntil .
                    292: .Pp
                    293: The function
                    294: .Fn print_text
                    295: prints HTML element content.
                    296: It uses the private function
                    297: .Fn print_encode
                    298: to take care of HTML encoding.
                    299: If the document has requested a non-standard font, for example using a
                    300: .Xr roff 7
                    301: .Ic \ef
                    302: font escape sequence,
                    303: .Fn print_text
                    304: wraps
                    305: .Fa word
                    306: in an HTML font selection element using the
                    307: .Fn print_otag
                    308: and
                    309: .Fn print_tagq
                    310: functions.
                    311: .Pp
1.7       schwarze  312: The function
                    313: .Fn html_make_id
                    314: takes a node containing one or more text children
                    315: and returns a newly allocated string containing the concatenation
                    316: of the child strings, with blanks replaced by underscores.
                    317: If the node
                    318: .Fa n
                    319: contains any non-text child node,
                    320: .Fn html_make_id
                    321: returns
                    322: .Dv NULL
                    323: instead.
                    324: The caller is responsible for freeing the returned string.
                    325: .Pp
                    326: The function
                    327: .Fn html_strlen
                    328: counts the number of characters in
                    329: .Fa cp .
                    330: It is used as a crude estimate of the width needed to display a string.
                    331: .Pp
1.1       schwarze  332: The functions
                    333: .Fn print_eqn ,
                    334: .Fn print_tbl ,
                    335: and
                    336: .Fn print_tblclose
                    337: are not yet documented.
                    338: .Sh FILES
                    339: .Bl -tag -width mandoc_aux.c -compact
                    340: .It Pa main.h
                    341: declarations of public functions for use by the main program,
                    342: not yet documented
                    343: .It Pa html.h
                    344: declarations of data types and private functions
                    345: for use by language-specific HTML formatters
                    346: .It Pa html.c
                    347: main HTML formatting engine and utility functions
                    348: .It Pa mdoc_html.c
                    349: .Xr mdoc 7
                    350: HTML formatter
                    351: .It Pa man_html.c
                    352: .Xr man 7
                    353: HTML formatter
                    354: .It Pa tbl_html.c
                    355: .Xr tbl 7
                    356: HTML formatter
                    357: .It Pa eqn_html.c
                    358: .Xr eqn 7
                    359: HTML formatter
                    360: .It Pa out.h
                    361: declarations of data types and private functions
                    362: for shared use by all mandoc formatters,
                    363: not yet documented
                    364: .It Pa out.c
                    365: private functions for shared use by all mandoc formatters
                    366: .It Pa mandoc_aux.h
                    367: declarations of common mandoc utility functions, see
                    368: .Xr mandoc 3
                    369: .It Pa mandoc_aux.c
                    370: implementation of common mandoc utility functions
                    371: .El
                    372: .Sh SEE ALSO
                    373: .Xr mandoc 1 ,
                    374: .Xr mandoc 3 ,
                    375: .Xr man.cgi 8
                    376: .Sh AUTHORS
                    377: .An -nosplit
                    378: The mandoc HTML formatter was written by
                    379: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.5       schwarze  380: It is maintained by
                    381: .An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
                    382: who also wrote this manual.

CVSweb