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

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