MANDOC_HTML(3) Library Functions Manual MANDOC_HTML(3)

NAME

mandoc_htmlinternals of the mandoc HTML formatter

SYNOPSIS

#include <html.h>
void
print_gen_decls(struct html *h);
void
print_gen_head(struct html *h);
struct tag *
print_otag(struct html *h, enum htmltag tag, const char *fmt, ...);
void
print_tagq(struct html *h, const struct tag *until);
void
print_stagq(struct html *h, const struct tag *suntil);
void
print_text(struct html *h, const char *word);

DESCRIPTION

The mandoc HTML formatter is not a formal library. However, as it is compiled into more than one program, in particular mandoc(1) and man.cgi(8), and because it may be security-critical in some contexts, some documentation is useful to help to use it correctly and to prevent XSS vulnerabilities.
The formatter produces HTML output on the standard output. Since proper escaping is usually required and best taken care of at one central place, the language-specific formatters (*_html.c, see FILES) are not supposed to print directly to stdout using functions like printf(3), putc(3), puts(3), or write(2). Instead, they are expected to use the output functions declared in html.h and implemented as part of the main HTML formatting engine in html.c.

Data structures

These structures are declared in html.h.
 
 
struct html
Internal state of the HTML formatter.
 
 
struct tag
One entry for the LIFO stack of HTML elements. Members are enum htmltag tag and struct tag *next.

Private interface functions

The function print_gen_decls() prints the opening ⟨?xml?⟩ and ⟨!DOCTYPE⟩ declarations required for the current document type.
The function print_gen_head() prints the opening ⟨META⟩ and ⟨LINK⟩ elements for the document ⟨HEAD⟩, using the style member of h unless that is NULL. It uses print_otag() which takes care of properly encoding attributes, which is relevant for the style link in particular.
The function print_otag() prints the start tag of an HTML element with the name tag, optionally including the attributes specified by fmt. If fmt is the empty string, no attributes are written. Each letter of fmt specifies one attribute to write. Most attributes require one char * argument which becomes the value of the attribute. The arguments have to be given in the same order as the attribute letters. If an argument is NULL, the respective attribute is not written.
 
 
c
Print a class attribute.
 
 
h
Print a href attribute. This attribute letter can optionally be followed by a modifier letter. If followed by R, it formats the link as a local one by prefixing a ‘#’ character. If followed by I, it interpretes the argument as a header file name and generates a link using the mandoc(1) -O includes option. If followed by M, it takes two arguments instead of one, a manual page name and section, and formats them as a link to a manual page using the mandoc(1) -O man option.
 
 
i
Print an id attribute.
 
 
?
Print an arbitrary attribute. This format letter requires two char * arguments, the attribute name and the value. The name must not be NULL.
 
 
s
Print a style attribute. If present, it must be the last format letter. In contrast to the other format letters, this one does not yet print the value and does not take an argument. Instead, the rest of the format string consists of pairs of argument type letters and style name letters.
Argument type letters each require on argument as follows:
 
 
h
Requires one int argument, interpreted as a horizontal length in units of SCALE_EN.
 
 
s
Requires one char * argument, used as a style value.
 
 
u
Requires one struct roffsu * argument, used as a length.
 
 
v
Requires one int argument, interpreted as a vertical length in units of SCALE_VS.
 
 
w
Requires one char * argument, interpreted as an mdoc(7)-style width specifier. If the argument is NULL, nothing is printed for this pair.
 
 
W
Similar to w, but makes the width negative by multiplying it with −1.
Style name letters decide what to do with the preceding argument:
 
 
b
Set margin-bottom to the given length.
 
 
h
Set height to the given length.
 
 
i
Set text-indent to the given length.
 
 
l
Set margin-left to the given length.
 
 
t
Set margin-top to the given length.
 
 
w
Set width to the given length.
 
 
W
Set min-width to the given length.
 
 
?
The special pair s? requires two char * arguments. The first is the style name, the second its value. The style name must not be NULL.
print_otag() uses the private function print_encode() to take care of HTML encoding. If required by the element type, it remembers in h that the element is open. The function print_tagq() is used to close out all open elements up to and including until; print_stagq() is a variant to close out all open elements up to but excluding suntil.
The function print_text() prints HTML element content. It uses the private function print_encode() to take care of HTML encoding. If the document has requested a non-standard font, for example using a roff(7) \f font escape sequence, print_text() wraps word in an HTML font selection element using the print_otag() and print_tagq() functions.
The functions html_strlen(), print_eqn(), print_tbl(), and print_tblclose() are not yet documented.

FILES

main.h
declarations of public functions for use by the main program, not yet documented
html.h
declarations of data types and private functions for use by language-specific HTML formatters
html.c
main HTML formatting engine and utility functions
mdoc_html.c
mdoc(7) HTML formatter
man_html.c
man(7) HTML formatter
tbl_html.c
tbl(7) HTML formatter
eqn_html.c
eqn(7) HTML formatter
out.h
declarations of data types and private functions for shared use by all mandoc formatters, not yet documented
out.c
private functions for shared use by all mandoc formatters
mandoc_aux.h
declarations of common mandoc utility functions, see mandoc(3)
mandoc_aux.c
implementation of common mandoc utility functions

SEE ALSO

mandoc(1), mandoc(3), man.cgi(8)

AUTHORS

The mandoc HTML formatter was written by Kristaps Dzonsons <kristaps@bsd.lv>. It is maintained by Ingo Schwarze <schwarze@openbsd.org>, who also wrote this manual.
January 28, 2017 OpenBSD 5.8