=================================================================== RCS file: /cvs/mandoc/mandoc_html.3,v retrieving revision 1.6 retrieving revision 1.20 diff -u -p -r1.6 -r1.20 --- mandoc/mandoc_html.3 2017/03/13 19:01:38 1.6 +++ mandoc/mandoc_html.3 2020/03/13 15:32:28 1.20 @@ -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.20 2020/03/13 15:32:28 schwarze Exp $ .\" -.\" Copyright (c) 2014, 2017 Ingo Schwarze +.\" Copyright (c) 2014, 2017, 2018 Ingo Schwarze .\" .\" 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: March 13 2020 $ .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,18 @@ .Fa "struct html *h" .Fa "const char *word" .Fc +.Ft char * +.Fo html_make_id +.Fa "const struct roff_node *n" +.Fa "int unique" +.Fc +.Ft struct tag * +.Fo print_otag_id +.Fa "struct html *h" +.Fa "enum htmltag tag" +.Fa "const char *cattr" +.Fa "struct roff_node *n" +.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 +115,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 +171,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 +211,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,13 +259,129 @@ and .Fn print_tagq functions. .Pp +The function +.Fn html_make_id +allocates a string to be used for the +.Cm id +attribute of an HTML element and/or as a segment identifier for a URI in an +.Aq Ic A +element. +If +.Fa n +contains a +.Fa string +attribute, it is used; otherwise, child nodes are used. +If +.Fa n +is an +.Ic \&Sh , +.Ic \&Ss , +.Ic \&Sx , +.Ic SH , +or +.Ic SS +node, the resulting string is the concatenation of the child strings; +for other node types, only the first child is used. +Bytes not permitted in URI-fragment strings are replaced by underscores. +If any of the children to be used is not a text node, +no string is generated and +.Dv NULL +is returned instead. +If the +.Fa unique +argument is non-zero, deduplication is performed by appending an +underscore and a decimal integer, if necessary. +.Pp +The function +.Fn print_otag_id +opens a +.Fa tag +element of class +.Fa cattr +for the node +.Fa n . +If the flag +.Dv NODE_ID +is set in +.Fa n , +it attempts to generate an +.Cm id +attribute with +.Fn html_make_id . +If an +.Cm id +attribute is written, +.Fn print_otag_id +also adds an +.Aq Ic A +element of class +.Qq permalink : +outside if +.Fa n +generates a phrasing element, or inside otherwise. +This function is a wrapper around +.Fn html_make_id +and +.Fn print_otag , +fixing the +.Fa unique +argument to 1 and the +.Fa fmt +arguments to +.Qq chR +and +.Qq ci , +respectively. +.Pp The functions -.Fn html_strlen , .Fn print_eqn , .Fn print_tbl , and .Fn print_tblclose are not yet documented. +.Sh RETURN VALUES +The functions +.Fn print_otag +and +.Fn print_otag_id +return a pointer to a new element on the stack of HTML elements. +When +.Fn print_otag_id +opens two elements, a pointer to the outer one is returned. +The memory pointed to is owned by the library and is automatically +.Xr free 3 Ns d +when +.Fn print_tagq +is called on it or when +.Fn print_stagq +is called on a parent element. +.Pp +The function +.Fn html_make_id +returns a newly allocated string or +.Dv NULL +if +.Fa n +lacks text data to create the attribute from. +If the +.Fa unique +argument is 0, the caller is responsible for +.Xr free 3 Ns ing +the returned string after using it. +If the +.Fa unique +argument is non-zero, the +.Va id_unique +ohash table is used for de-duplication and owns the returned string. +In this case, it will be freed automatically by +.Fn html_reset +or +.Fn html_free . +.Pp +In case of +.Xr malloc 3 +failure, these functions do not return but call +.Xr err 3 . .Sh FILES .Bl -tag -width mandoc_aux.c -compact .It Pa main.h