-.\" $Id: mandoc_html.3,v 1.1 2014/07/23 18:13:09 schwarze Exp $
+.\" $Id: mandoc_html.3,v 1.17 2018/06/25 16:54:59 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
.\" 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
.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
.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
.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
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_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.
+It requires two
+.Va char *
+arguments.
+The first is the name of the style property, the second its value.
+.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
.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
.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