version 1.20, 2020/03/13 15:32:28 |
version 1.21, 2020/04/18 20:44:09 |
|
|
.Nm mandoc_html |
.Nm mandoc_html |
.Nd internals of the mandoc HTML formatter |
.Nd internals of the mandoc HTML formatter |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.In "html.h" |
.In sys/types.h |
|
.Fd #include """mandoc.h""" |
|
.Fd #include """roff.h""" |
|
.Fd #include """out.h""" |
|
.Fd #include """html.h""" |
.Ft void |
.Ft void |
.Fn print_gen_decls "struct html *h" |
.Fn print_gen_decls "struct html *h" |
.Ft void |
.Ft void |
|
|
.Fa "const struct tag *suntil" |
.Fa "const struct tag *suntil" |
.Fc |
.Fc |
.Ft void |
.Ft void |
|
.Fn html_close_paragraph "struct html *h" |
|
.Ft enum roff_tok |
|
.Fo html_fillmode |
|
.Fa "struct html *h" |
|
.Fa "enum roff_tok tok" |
|
.Fc |
|
.Ft int |
|
.Fo html_setfont |
|
.Fa "struct html *h" |
|
.Fa "enum mandoc_esc font" |
|
.Fc |
|
.Ft void |
.Fo print_text |
.Fo print_text |
.Fa "struct html *h" |
.Fa "struct html *h" |
.Fa "const char *word" |
.Fa "const char *word" |
.Fc |
.Fc |
|
.Ft void |
|
.Fo print_tagged_text |
|
.Fa "struct html *h" |
|
.Fa "const char *word" |
|
.Fa "struct roff_node *n" |
|
.Fc |
.Ft char * |
.Ft char * |
.Fo html_make_id |
.Fo html_make_id |
.Fa "const struct roff_node *n" |
.Fa "const struct roff_node *n" |
|
|
.Fa "const char *cattr" |
.Fa "const char *cattr" |
.Fa "struct roff_node *n" |
.Fa "struct roff_node *n" |
.Fc |
.Fc |
|
.Ft void |
|
.Fn print_endline "struct html *h" |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The mandoc HTML formatter is not a formal library. |
The mandoc HTML formatter is not a formal library. |
However, as it is compiled into more than one program, in particular |
However, as it is compiled into more than one program, in particular |
Line 100 These structures are declared in |
|
Line 124 These structures are declared in |
|
Internal state of the HTML formatter. |
Internal state of the HTML formatter. |
.It Vt struct tag |
.It Vt struct tag |
One entry for the LIFO stack of HTML elements. |
One entry for the LIFO stack of HTML elements. |
Members are |
Members include |
.Fa "enum htmltag tag" |
.Fa "enum htmltag tag" |
and |
and |
.Fa "struct tag *next" . |
.Fa "struct tag *next" . |
|
|
The function |
The function |
.Fn print_gen_decls |
.Fn print_gen_decls |
prints the opening |
prints the opening |
.Ao Pf \&? Ic xml ? Ac |
|
and |
|
.Aq Pf \&! Ic DOCTYPE |
.Aq Pf \&! Ic DOCTYPE |
declarations required for the current document type. |
declaration. |
.Pp |
.Pp |
The function |
The function |
.Fn print_gen_comment |
.Fn print_gen_comment |
Line 206 This format letter requires two |
|
Line 228 This format letter requires two |
|
arguments, the attribute name and the value. |
arguments, the attribute name and the value. |
The name must not be |
The name must not be |
.Dv NULL . |
.Dv NULL . |
.It Cm s |
|
Print a |
|
.Cm style |
|
attribute. |
|
If present, it must be the last format letter. |
|
It requires two |
|
.Va char * |
|
arguments. |
|
The first is the name of the style property, the second its value. |
|
The name must not be |
|
.Dv NULL . |
|
The |
|
.Cm s |
|
.Ar fmt |
|
letter can be repeated, each repetition requiring an additional pair of |
|
.Va char * |
|
arguments. |
|
.El |
.El |
.Pp |
.Pp |
.Fn print_otag |
.Fn print_otag |
Line 239 is used to close out all open elements up to and inclu |
|
Line 244 is used to close out all open elements up to and inclu |
|
.Fn print_stagq |
.Fn print_stagq |
is a variant to close out all open elements up to but excluding |
is a variant to close out all open elements up to but excluding |
.Fa suntil . |
.Fa suntil . |
|
The function |
|
.Fn html_close_paragraph |
|
closes all open elements that establish phrasing context, |
|
thus returning to the innermost flow context. |
.Pp |
.Pp |
The function |
The function |
|
.Fn html_fillmode |
|
switches to fill mode if |
|
.Fa want |
|
is |
|
.Dv ROFF_fi |
|
or to no-fill mode if |
|
.Fa want |
|
is |
|
.Dv ROFF_nf . |
|
Switching from fill mode to no-fill mode closes the current paragraph |
|
and opens a |
|
.Aq Ic PRE |
|
element. |
|
Switching in the opposite direction closes the |
|
.Aq Ic PRE |
|
element, but does not open a new paragraph. |
|
If |
|
.Fa want |
|
matches the mode that is already active, no elements are closed nor opened. |
|
If |
|
.Fa want |
|
is |
|
.Dv TOKEN_NONE , |
|
the mode remains as it is. |
|
.Pp |
|
The function |
|
.Fn html_setfont |
|
selects the |
|
.Fa font , |
|
which can be |
|
.Dv ESCAPE_FONTROMAN , |
|
.Dv ESCAPE_FONTBOLD , |
|
.Dv ESCAPE_FONTITALIC , |
|
.Dv ESCAPE_FONTBI , |
|
or |
|
.Dv ESCAPE_FONTCW , |
|
for future text output and internally remembers |
|
the font that was active before the change. |
|
If the |
|
.Fa font |
|
argument is |
|
.Dv ESCAPE_FONTPREV , |
|
the current and the previous font are exchanged. |
|
This function only changes the internal state of the |
|
.Fa h |
|
object; no HTML elements are written yet. |
|
Subsequent text output will write font elements when needed. |
|
.Pp |
|
The function |
.Fn print_text |
.Fn print_text |
prints HTML element content. |
prints HTML element content. |
It uses the private function |
It uses the private function |
|
|
functions. |
functions. |
.Pp |
.Pp |
The function |
The function |
|
.Fn print_tagged_text |
|
is a variant of |
|
.Fn print_text |
|
that wraps |
|
.Fa word |
|
in an |
|
.Aq Ic A |
|
element of class |
|
.Qq permalink |
|
if |
|
.Fa n |
|
is not |
|
.Dv NULL |
|
and yields a segment identifier when passed to |
|
.Fn html_make_id . |
|
.Pp |
|
The function |
.Fn html_make_id |
.Fn html_make_id |
allocates a string to be used for the |
allocates a string to be used for the |
.Cm id |
.Cm id |
|
|
If |
If |
.Fa n |
.Fa n |
contains a |
contains a |
.Fa string |
.Fa tag |
attribute, it is used; otherwise, child nodes are used. |
attribute, it is used; otherwise, child nodes are used. |
If |
If |
.Fa n |
.Fa n |
Line 308 it attempts to generate an |
|
Line 383 it attempts to generate an |
|
.Cm id |
.Cm id |
attribute with |
attribute with |
.Fn html_make_id . |
.Fn html_make_id . |
If an |
If the flag |
.Cm id |
.Dv NODE_HREF |
attribute is written, |
is set in |
.Fn print_otag_id |
.Fa n , |
also adds an |
an |
.Aq Ic A |
.Aq Ic A |
element of class |
element of class |
.Qq permalink : |
.Qq permalink |
|
is added: |
outside if |
outside if |
.Fa n |
.Fa n |
generates a phrasing element, or inside otherwise. |
generates an element that can only occur in phrasing context, |
|
or inside otherwise. |
This function is a wrapper around |
This function is a wrapper around |
.Fn html_make_id |
.Fn html_make_id |
and |
and |
|
|
.Qq ci , |
.Qq ci , |
respectively. |
respectively. |
.Pp |
.Pp |
|
The function |
|
.Fn print_endline |
|
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 |
|
.Fa h |
|
object. |
|
.Pp |
The functions |
The functions |
.Fn print_eqn , |
.Fn print_eqn , |
.Fn print_tbl , |
.Fn print_tbl , |
Line 357 is called on it or when |
|
Line 443 is called on it or when |
|
is called on a parent element. |
is called on a parent element. |
.Pp |
.Pp |
The function |
The function |
|
.Fn html_fillmode |
|
returns |
|
.Dv ROFF_fi |
|
if fill mode was active before the call or |
|
.Dv ROFF_nf |
|
otherwise. |
|
.Pp |
|
The function |
.Fn html_make_id |
.Fn html_make_id |
returns a newly allocated string or |
returns a newly allocated string or |
.Dv NULL |
.Dv NULL |
|
|
.It Pa eqn_html.c |
.It Pa eqn_html.c |
.Xr eqn 7 |
.Xr eqn 7 |
HTML formatter |
HTML formatter |
|
.It Pa roff_html.c |
|
.Xr roff 7 |
|
HTML formatter, handling requests like |
|
.Ic br , |
|
.Ic ce , |
|
.Ic fi , |
|
.Ic ft , |
|
.Ic nf , |
|
.Ic rj , |
|
and |
|
.Ic sp . |
.It Pa out.h |
.It Pa out.h |
declarations of data types and private functions |
declarations of data types and private functions |
for shared use by all mandoc formatters, |
for shared use by all mandoc formatters, |