MANDOC_HTML(3) Library Functions Manual MANDOC_HTML(3)

mandoc_htmlinternals of the mandoc HTML formatter

#include <html.h>

void
print_gen_decls(struct html *h);

void
print_gen_comment(struct html *h, struct roff_node *n);

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);

char *
html_make_id(const struct roff_node *n);

int
html_strlen(const char *cp);

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.

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.

The function () prints the opening ⟨?xml?⟩ and ⟨!DOCTYPE⟩ declarations required for the current document type.

Print a class attribute.
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.
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.
Print a style attribute. 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 NULL. The s fmt letter can be repeated, each repetition requiring an additional pair of char * arguments.

The function () takes a node containing one or more text children and returns a newly allocated string containing the concatenation of the child strings, with blanks replaced by underscores. If the node n contains any non-text child node, html_make_id() returns NULL instead. The caller is responsible for freeing the returned string.

The function () counts the number of characters in cp. It is used as a crude estimate of the width needed to display a string.

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

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

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 11, 2019 OpenBSD 6.7