-.\" $Id: mandoc_html.3,v 1.20 2020/03/13 15:32:28 schwarze Exp $
+.\" $Id: mandoc_html.3,v 1.23 2020/04/24 13:13:06 schwarze Exp $
.\"
.\" Copyright (c) 2014, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: March 13 2020 $
+.Dd $Mdocdate: April 24 2020 $
.Dt MANDOC_HTML 3
.Os
.Sh NAME
.Nm mandoc_html
.Nd internals of the mandoc HTML formatter
.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
.Fn print_gen_decls "struct html *h"
.Ft void
.Fa "const struct tag *suntil"
.Fc
.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
.Fa "struct html *h"
.Fa "const char *word"
.Fc
+.Ft void
+.Fo print_tagged_text
+.Fa "struct html *h"
+.Fa "const char *word"
+.Fa "struct roff_node *n"
+.Fc
.Ft char *
.Fo html_make_id
.Fa "const struct roff_node *n"
.Fa "const char *cattr"
.Fa "struct roff_node *n"
.Fc
+.Ft void
+.Fn print_endline "struct html *h"
.Sh DESCRIPTION
The mandoc HTML formatter is not a formal library.
However, as it is compiled into more than one program, in particular
Internal state of the HTML formatter.
.It Vt struct tag
One entry for the LIFO stack of HTML elements.
-Members are
+Members include
.Fa "enum htmltag tag"
and
.Fa "struct tag *next" .
The function
.Fn print_gen_decls
prints the opening
-.Ao Pf \&? Ic xml ? Ac
-and
.Aq Pf \&! Ic DOCTYPE
-declarations required for the current document type.
+declaration.
.Pp
The function
.Fn print_gen_comment
.Fn print_stagq
is a variant to close out all open elements up to but excluding
.Fa suntil .
+The function
+.Fn html_close_paragraph
+closes all open elements that establish phrasing context,
+thus returning to the innermost flow context.
+.Pp
+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
functions.
.Pp
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
allocates a string to be used for the
.Cm id
If
.Fa n
contains a
-.Fa string
+.Fa tag
attribute, it is used; otherwise, child nodes are used.
If
.Fa n
.Fa unique
argument is non-zero, deduplication is performed by appending an
underscore and a decimal integer, if necessary.
+If the
+.Fa unique
+argument is 1, this is assumed to be the first call for this tag
+at this location, typically for use by
+.Dv NODE_ID ,
+so the integer is incremented before use.
+If the
+.Fa unique
+argument is 2, this is ssumed to be the second call for this tag
+at this location, typically for use by
+.Dv NODE_HREF ,
+so the existing integer, if any, is used without incrementing it.
.Pp
The function
.Fn print_otag_id
.Cm id
attribute with
.Fn html_make_id .
-If an
-.Cm id
-attribute is written,
-.Fn print_otag_id
-also adds an
+If the flag
+.Dv NODE_HREF
+is set in
+.Fa n ,
+an
.Aq Ic A
element of class
-.Qq permalink :
+.Qq permalink
+is added:
outside if
.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
.Fn html_make_id
and
.Fn print_otag ,
-fixing the
+automatically chosing the
.Fa unique
-argument to 1 and the
+argument appropriately and setting the
.Fa fmt
arguments to
.Qq chR
.Qq ci ,
respectively.
.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
.Fn print_eqn ,
.Fn print_tbl ,
is called on a parent element.
.Pp
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
returns a newly allocated string or
.Dv NULL
if
.Fa n
lacks text data to create the attribute from.
-If the
-.Fa unique
-argument is 0, the caller is responsible for
+The caller is responsible for
.Xr free 3 Ns ing
the returned string after using it.
-If the
-.Fa unique
-argument is non-zero, the
-.Va id_unique
-ohash table is used for de-duplication and owns the returned string.
-In this case, it will be freed automatically by
-.Fn html_reset
-or
-.Fn html_free .
.Pp
In case of
.Xr malloc 3
.It Pa eqn_html.c
.Xr eqn 7
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
declarations of data types and private functions
for shared use by all mandoc formatters,
git.ckatri.com / mandoc.git / blobdiff