-.\" $Id: mandoc_html.3,v 1.3 2017/01/17 15:32:44 schwarze Exp $
+.\" $Id: mandoc_html.3,v 1.18 2018/11/26 01:38:23 schwarze Exp $
.\"
-.\" Copyright (c) 2014, 2017 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2014, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: January 17 2017 $
+.Dd $Mdocdate: November 26 2018 $
.Dt MANDOC_HTML 3
.Os
.Sh NAME
.Ft void
.Fn print_gen_decls "struct html *h"
.Ft void
+.Fn print_gen_comment "struct html *h" "struct roff_node *n"
+.Ft void
.Fn print_gen_head "struct html *h"
.Ft struct tag *
.Fo print_otag
.Fa "struct html *h"
.Fa "const char *word"
.Fc
+.Ft char *
+.Fo html_make_id
+.Fa "const struct roff_node *n"
+.Fc
+.Ft int
+.Fo html_strlen
+.Fa "const char *cp"
+.Fc
.Sh DESCRIPTION
The mandoc HTML formatter is not a formal library.
However, as it is compiled into more than one program, in particular
declarations required for the current document type.
.Pp
The function
+.Fn print_gen_comment
+prints the leading comments, usually containing a Copyright notice
+and license, as an HTML comment.
+It is intended to be called right after opening the
+.Aq Ic HTML
+element.
+Pass the first
+.Dv ROFFT_COMMENT
+node in
+.Fa n .
+.Pp
+The function
.Fn print_gen_head
prints the opening
.Aq Ic META
.Va 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
+.Dv NULL ,
+the respective attribute is not written.
.Bl -tag -width 1n -offset indent
.It Cm c
Print a
.Cm class
attribute.
+This attribute letter can optionally be followed by the modifier letter
+.Cm T .
+In that case, a
+.Cm title
+attribute with the same value is also printed.
.It Cm h
Print a
.Cm href
This format letter requires two
.Vt char *
arguments, the attribute name and the value.
+The name must not be
+.Dv NULL .
.It Cm s
Print a
.Cm 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 require an argument.
-Instead, the rest of the format string consists of pairs of
-argument type letters and style name letters.
-.El
-.Pp
-Argument type letters each require on argument as follows:
-.Bl -tag -width 1n -offset indent
-.It Cm h
-Requires one
-.Vt int
-argument, interpreted as a horizontal length in units of
-.Dv SCALE_EN .
-.It Cm s
-Requires one
-.Vt char *
-argument, used as a style value.
-.It Cm u
-Requires one
-.Vt struct roffsu *
-argument, used as a length.
-.It Cm v
-Requires one
-.Vt int
-argument, interpreted as a vertical length in units of
-.Dv SCALE_VS .
-.It Cm w
-Requires one
-.Vt char *
-argument, interpreted as an
-.Xr mdoc 7 Ns -style
-width specifier.
-.El
-.Pp
-Style name letters decide what to do with the preceding argument:
-.Bl -tag -width 1n -offset indent
-.It Cm b
-Set
-.Cm margin-bottom
-to the given length.
-.It Cm h
-Set
-.Cm height
-to the given length.
-.It Cm i
-Set
-.Cm text-indent
-to the given length.
-.It Cm l
-Set
-.Cm margin-left
-to the given length.
-.It Cm t
-Set
-.Cm margin-top
-to the given length.
-.It Cm w
-Set
-.Cm width
-to the given length.
-.It Cm W
-Set
-.Cm min-width
-to the given length.
-.It Cm \&?
-The special pair
-.Cm s?
-requires two
-.Vt char *
+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.
-The first is the style name, the second its value.
.El
.Pp
.Fn print_otag
.Fn print_tagq
functions.
.Pp
+The function
+.Fn html_make_id
+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
+.Fa n
+contains any non-text child node,
+.Fn html_make_id
+returns
+.Dv NULL
+instead.
+The caller is responsible for freeing the returned string.
+.Pp
+The function
+.Fn html_strlen
+counts the number of characters in
+.Fa cp .
+It is used as a crude estimate of the width needed to display a string.
+.Pp
The functions
-.Fn html_strlen ,
.Fn print_eqn ,
.Fn print_tbl ,
and
.An -nosplit
The mandoc HTML formatter was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
-This manual was written by
-.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
+It is maintained by
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
+who also wrote this manual.
git.ckatri.com / mandoc.git / blobdiff