libmdoc.h no longer needs mdoc.h

[mandoc.git] / mandoc_html.3

diff --git a/mandoc_html.3 b/mandoc_html.3
index b9fc7f635737ee97fd8653c5d0c41a56f897fa47..9e9229158b3f3c7182595cb1f9914bd9c6c75bc9 100644 (file)
--- a/mandoc_html.3
+++ b/mandoc_html.3
@@ -1,6 +1,6 @@
-.\"    $Id: mandoc_html.3,v 1.2 2017/01/17 01:47:51 schwarze Exp $
+.\"    $Id: mandoc_html.3,v 1.18 2018/11/26 01:38:23 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
 .\"
 .\" 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.
 .\"
 .\" 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
 .Dt MANDOC_HTML 3
 .Os
 .Sh NAME


@@ -25,6 +25,8 @@
 .Ft void
 .Fn print_gen_decls "struct html *h"
 .Ft void
 .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
 .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
 .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


@@ -101,6 +111,18 @@ and
 declarations required for the current document type.
 .Pp
 The function
 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
 .Fn print_gen_head
 prints the opening
 .Aq Ic META


@@ -137,15 +159,43 @@ 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
 attribute.
 .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
 .It Cm i
 Print an
 .Cm id


@@ -155,88 +205,29 @@ 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.
 .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.
 arguments.

-The first is the style name, the second its value.

 .El
 .Pp
 .Fn print_otag
 uses the private function
 .El
 .Pp
 .Fn print_otag
 uses the private function

-.Fn print_attr
-which in turn uses the private function

 .Fn print_encode
 to take care of HTML encoding.
 If required by the element type, it remembers in
 .Fn print_encode
 to take care of HTML encoding.
 If required by the element type, it remembers in


@@ -269,30 +260,27 @@ and
 .Fn print_tagq
 functions.
 .Pp
 .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
 .Pp
 The functions

-.Fn html_strlen ,

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


@@ -340,5 +328,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.