=================================================================== RCS file: /cvs/mandoc/mandoc_html.3,v retrieving revision 1.14 retrieving revision 1.20 diff -u -p -r1.14 -r1.20 --- mandoc/mandoc_html.3 2018/06/25 13:26:57 1.14 +++ mandoc/mandoc_html.3 2020/03/13 15:32:28 1.20 @@ -1,4 +1,4 @@ -.\" $Id: mandoc_html.3,v 1.14 2018/06/25 13:26:57 schwarze Exp $ +.\" $Id: mandoc_html.3,v 1.20 2020/03/13 15:32:28 schwarze Exp $ .\" .\" Copyright (c) 2014, 2017, 2018 Ingo Schwarze .\" @@ -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: June 25 2018 $ +.Dd $Mdocdate: March 13 2020 $ .Dt MANDOC_HTML 3 .Os .Sh NAME @@ -53,10 +53,14 @@ .Ft char * .Fo html_make_id .Fa "const struct roff_node *n" +.Fa "int unique" .Fc -.Ft int -.Fo html_strlen -.Fa "const char *cp" +.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. @@ -167,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 @@ -212,68 +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 one 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 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. -.Pp -The -.Cm w -argument type letter can optionally be followed by the modifier -.Cm + -which increases the width by 20% to make even bold text fit -and adds three units for padding between columns. -.El -.Pp -Style name letters decide what to do with the preceding argument: -.Bl -tag -width 1n -offset indent -.It Cm l -Set -.Cm margin-left -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 @@ -312,23 +261,77 @@ 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 +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 any non-text child node, -.Fn html_make_id -returns +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 -instead. -The caller is responsible for freeing the returned string. +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 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. +.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 print_eqn , @@ -336,6 +339,49 @@ The functions 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