If messages are shown and output is printed without a pager, display

[mandoc.git] / mandoc_html.3

diff --git a/mandoc_html.3 b/mandoc_html.3
index a274fd03751f7f677e3ccf8e0702b4ea49c2b534..32407574a814a501bcad1f70d0d59d1c9c47193c 100644 (file)
--- a/mandoc_html.3
+++ b/mandoc_html.3
@@ -1,6 +1,6 @@
-.\"    $Id: mandoc_html.3,v 1.6 2017/03/13 19:01:38 schwarze Exp $
+.\"    $Id: mandoc_html.3,v 1.19 2019/01/11 12:56:43 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
@@ -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: March 13 2017 $
+.Dd $Mdocdate: January 11 2019 $
 .Dt MANDOC_HTML 3
 .Os
 .Sh NAME
@@ -25,6 +25,8 @@
 .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
@@ -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
@@ -101,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
@@ -145,11 +167,6 @@ the respective attribute is not written.
 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
@@ -190,86 +207,18 @@ 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 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.
-If the argument is
-.Dv NULL ,
-nothing is printed for this pair.
-.It Cm W
-Similar to
-.Cm w ,
-but makes the width negative by multiplying it with \(mi1.
-.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 style name, the second its value.
-The style name must not be
+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
 .Pp
 .Fn print_otag
@@ -306,8 +255,27 @@ and
 .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