do not break the line between Bsx/Bx/Fx/Nx/Ox/Dx and its arguments

[mandoc.git] / mandoc_html.3

diff --git a/mandoc_html.3 b/mandoc_html.3
index 80b1fe69f7cff4f0bcc3b7f22c642f8ed3a548a8..bd3f1b585552434a1d36adf37c8beb875a765d78 100644 (file)
--- a/mandoc_html.3
+++ b/mandoc_html.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc_html.3,v 1.3 2017/01/17 15:32:44 schwarze Exp $
+.\"    $Id: mandoc_html.3,v 1.8 2017/05/12 17:58:21 schwarze Exp $

 .\"
 .\" Copyright (c) 2014, 2017 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\"
 .\" Copyright (c) 2014, 2017 Ingo Schwarze <schwarze@openbsd.org>
 .\"


@@ -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.
 .\"
 .\" 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: May 12 2017 $

 .Dt MANDOC_HTML 3
 .Os
 .Sh NAME
 .Dt MANDOC_HTML 3
 .Os
 .Sh NAME


@@ -48,6 +48,14 @@
 .Fa "struct html *h"
 .Fa "const char *word"
 .Fc
 .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
 .Sh DESCRIPTION
 The mandoc HTML formatter is not a formal library.
 However, as it is compiled into more than one program, in particular


@@ -137,11 +145,19 @@ 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.
 .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.
 .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
 .It Cm h
 Print a
 .Cm href


@@ -175,18 +191,20 @@ Print an arbitrary attribute.
 This format letter requires two
 .Vt char *
 arguments, the attribute name and the value.
 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
 .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.
+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
 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:
+Argument type letters each require one argument as follows:

 .Bl -tag -width 1n -offset indent
 .It Cm h
 Requires one
 .Bl -tag -width 1n -offset indent
 .It Cm h
 Requires one


@@ -212,6 +230,21 @@ Requires one
 argument, interpreted as an
 .Xr mdoc 7 Ns -style
 width specifier.
 argument, interpreted as an
 .Xr mdoc 7 Ns -style
 width specifier.

+If the argument is
+.Dv NULL ,
+nothing is printed for this pair.
+.Pp
+The
+.Cm w
+argument type letter can optionally be followed by one or two
+modifier letters.
+The modifier
+.Cm +
+increases the width by 10% to make even bold text fit
+and adds two units for padding between columns.
+The modifier
+.Cm \-
+makes the width negative by multiplying it with \-1.

 .El
 .Pp
 Style name letters decide what to do with the preceding argument:
 .El
 .Pp
 Style name letters decide what to do with the preceding argument:


@@ -251,6 +284,8 @@ requires two
 .Vt char *
 arguments.
 The first is the style name, the second its value.
 .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
 .El
 .Pp
 .Fn print_otag


@@ -287,8 +322,27 @@ and
 .Fn print_tagq
 functions.
 .Pp
 .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
 The functions

-.Fn html_strlen ,

 .Fn print_eqn ,
 .Fn print_tbl ,
 and
 .Fn print_eqn ,
 .Fn print_tbl ,
 and


@@ -336,5 +390,6 @@ implementation of common mandoc utility functions
 .An -nosplit
 The mandoc HTML formatter was written by
 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
 .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.