===================================================================
RCS file: /cvs/mandoc/mandoc_html.3,v
retrieving revision 1.1
retrieving revision 1.16
diff -u -p -r1.1 -r1.16
--- mandoc/mandoc_html.3	2014/07/23 18:13:09	1.1
+++ mandoc/mandoc_html.3	2018/06/25 14:13:54	1.16
@@ -1,6 +1,6 @@
-.\"	$Id: mandoc_html.3,v 1.1 2014/07/23 18:13:09 schwarze Exp $
+.\"	$Id: mandoc_html.3,v 1.16 2018/06/25 14:13:54 schwarze Exp $
 .\"
-.\" Copyright (c) 2014 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
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 23 2014 $
+.Dd $Mdocdate: June 25 2018 $
 .Dt MANDOC_HTML 3
 .Os
 .Sh NAME
@@ -25,13 +25,15 @@
 .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 "enum htmltag tag"
-.Fa "int sz"
-.Fa "const struct htmlpair *p"
+.Fa "const char *fmt"
+.Fa ...
 .Fc
 .Ft void
 .Fo print_tagq
@@ -48,6 +50,14 @@
 .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
@@ -84,15 +94,6 @@ These structures are declared in
 .Bl -tag -width Ds
 .It Vt struct html
 Internal state of the HTML formatter.
-.It Vt struct htmlpair
-Holds one HTML attribute.
-Members are
-.Fa "enum htmlattr key"
-and
-.Fa "const char *val" .
-Helper macros
-.Fn PAIR_*
-are provided to support initialization of such structures.
 .It Vt struct tag
 One entry for the LIFO stack of HTML elements.
 Members are
@@ -110,6 +111,18 @@ and
 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
@@ -134,14 +147,104 @@ The function
 .Fn print_otag
 prints the start tag of an HTML element with the name
 .Fa tag ,
-including the
-.Fa sz
-attributes that can optionally be provided in the
-.Fa p
-array.
-It uses the private function
-.Fn print_attr
-which in turn uses the private function
+optionally including the attributes specified by
+.Fa fmt .
+If
+.Fa fmt
+is the empty string, no attributes are written.
+Each letter of
+.Fa fmt
+specifies one attribute to write.
+Most attributes require one
+.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
+attribute.
+This attribute letter can optionally be followed by a modifier letter.
+If followed by
+.Cm R ,
+it formats the link as a local one by prefixing a
+.Sq #
+character.
+If followed by
+.Cm I ,
+it interpretes the argument as a header file name
+and generates a link using the
+.Xr mandoc 1
+.Fl O Cm includes
+option.
+If followed by
+.Cm 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
+.Xr mandoc 1
+.Fl O Cm man
+option.
+.It Cm i
+Print an
+.Cm id
+attribute.
+.It Cm \&?
+Print an arbitrary attribute.
+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 take 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 one argument as follows:
+.Bl -tag -width 1n -offset indent
+.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.
+.El
+.Pp
+Style name letters decide what to do with the preceding argument:
+.Bl -tag -width 1n -offset indent
+.It Cm \&?
+The special pair
+.Cm s?
+requires two
+.Vt char *
+arguments.
+The first is the style name, the second its value.
+The style name must not be
+.Dv NULL .
+.El
+.Pp
+.Fn print_otag
+uses the private function
 .Fn print_encode
 to take care of HTML encoding.
 If required by the element type, it remembers in
@@ -174,30 +277,27 @@ and
 .Fn print_tagq
 functions.
 .Pp
-The functions
-.Fn bufinit ,
-.Fn bufcat* ,
-and
-.Fn buffmt*
-do not directly produce output but buffer text in the
-.Fa buf
-member of
-.Fa h .
-They are not used internally by
-.Pa html.c
-but intended for use by the language-specific formatters
-to ease preparation of strings for the
-.Fa p
-argument of
-.Fn print_otag
-and for the
-.Fa word
-argument of
-.Fn print_text .
-Consequently, these functions do not do any HTML encoding.
+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
@@ -245,5 +345,6 @@ implementation of common mandoc utility functions
 .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.