|MANDOC_HTML(3)||Library Functions Manual||MANDOC_HTML(3)|
internals of the mandoc HTML formatter
html *h, struct roff_node
struct tag *
print_otag(struct html *h,
enum htmltag tag, const char
print_tagq(struct html *h,
const struct tag *until);
print_stagq(struct html *h,
const struct tag *suntil);
html_fillmode(struct html *h,
enum roff_tok tok);
html_setfont(struct html *h,
enum mandoc_esc font);
print_text(struct html *h,
const char *word);
*h, const char *word, struct
html_make_id(const struct roff_node
*n, int unique);
struct tag *
print_otag_id(struct html *h,
enum htmltag tag, const char
*cattr, struct roff_node *n);
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
stdout using functions like
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.
These structures are declared in html.h.
prints the opening ⟨!
prints the leading comments, usually containing a Copyright notice and
license, as an HTML comment. It is intended to be called right after opening
HTML⟩ element. Pass the first
ROFFT_COMMENT node in n.
prints the opening ⟨
LINK⟩ elements for the document
HEAD⟩, using the
style member of h unless that is
NULL. It uses
which takes care of properly encoding attributes, which is relevant for the
style link in particular.
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.
hrefattribute. 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)
includesoption. 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)
styleattribute. If present, it must be the last format letter. It requires two char * arguments. The first is the name of the style property, the second its value. The name must not be
sfmt letter can be repeated, each repetition requiring an additional pair of char * arguments.
uses the private function
to take care of HTML encoding. If required by the element type, it remembers
in h that the element is open. The function
is used to close out all open elements up to and including
is a variant to close out all open elements up to but excluding
suntil. The function
closes all open elements that establish phrasing context, thus returning to
the innermost flow context.
switches to fill mode if want is
ROFF_fi or to no-fill mode if
from fill mode to no-fill mode closes the current paragraph and opens a
PRE⟩ element. Switching in the
opposite direction closes the ⟨
element, but does not open a new paragraph. If want
matches the mode that is already active, no elements are closed nor opened.
If want is
mode remains as it is.
selects the font, which can be
ESCAPE_FONTCW, for future text output and internally
remembers the font that was active before the change. If the
font argument is
ESCAPE_FONTPREV, the current and the previous font
are exchanged. This function only changes the internal state of the
h object; no HTML elements are written yet. Subsequent
text output will write font elements when needed.
prints HTML element content. It uses the private function
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
is a variant of
print_text() that wraps
word in an ⟨
element of class "permalink" if n is not
NULL and yields a segment identifier when passed to
allocates a string to be used for the
of an HTML element and/or as a segment identifier for a URI in an
A⟩ element. If
n contains a tag attribute, it
is used; otherwise, child nodes are used. If n is an
SS node, the resulting string is the concatenation
of the child strings; for other node types, only the first child is used.
Bytes not permitted in URI-fragment strings are replaced by underscores. If
any of the children to be used is not a text node, no string is generated
NULL is returned instead. If the
unique argument is non-zero, deduplication is
performed by appending an underscore and a decimal integer, if necessary. If
the unique argument is 1, this is assumed to be the
first call for this tag at this location, typically for use by
NODE_ID, so the integer is incremented before use.
If the unique argument is 2, this is ssumed to be the
second call for this tag at this location, typically for use by
NODE_HREF, so the existing integer, if any, is used
without incrementing it.
opens a tag element of class
cattr for the node n. If the
NODE_ID is set in n, it
attempts to generate an
id attribute with
html_make_id(). If the flag
NODE_HREF is set in n, an
A⟩ element of class
"permalink" is added: outside if n generates
an element that can only occur in phrasing context, or inside otherwise.
This function is a wrapper around
print_otag(), automatically chosing the
unique argument appropriately and setting the
fmt arguments to "chR" and "ci",
makes sure subsequent output starts on a new HTML output line. If nothing
was printed on the current output line yet, it has no effect. Otherwise, it
appends any buffered text to the current output line, ends the line, and
updates the internal state of the h object.
print_otag_id() return a pointer to a new element on
the stack of HTML elements. When
opens two elements, a pointer to the outer one is returned. The memory
pointed to is owned by the library and is automatically
print_tagq() is called on it or when
print_stagq() is called on a parent element.
ROFF_fi if fill mode was active before the call or
html_make_id() returns a
newly allocated string or
n lacks text data to create the attribute from. The
caller is responsible for
returned string after using it.
|April 24, 2020||OpenBSD 6.7|