version 1.12, 2018/05/29 02:10:10 |
version 1.20, 2020/03/13 15:32:28 |
|
|
.Ft char * |
.Ft char * |
.Fo html_make_id |
.Fo html_make_id |
.Fa "const struct roff_node *n" |
.Fa "const struct roff_node *n" |
|
.Fa "int unique" |
.Fc |
.Fc |
.Ft int |
.Ft struct tag * |
.Fo html_strlen |
.Fo print_otag_id |
.Fa "const char *cp" |
.Fa "struct html *h" |
|
.Fa "enum htmltag tag" |
|
.Fa "const char *cattr" |
|
.Fa "struct roff_node *n" |
.Fc |
.Fc |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The mandoc HTML formatter is not a formal library. |
The mandoc HTML formatter is not a formal library. |
Line 167 the respective attribute is not written. |
|
Line 171 the respective attribute is not written. |
|
Print a |
Print a |
.Cm class |
.Cm class |
attribute. |
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 |
.It Cm h |
Print a |
Print a |
.Cm href |
.Cm href |
|
|
.Cm style |
.Cm style |
attribute. |
attribute. |
If present, it must be the last format letter. |
If present, it must be the last format letter. |
In contrast to the other format letters, this one does not yet |
It requires two |
print the value and does not take an argument. |
.Va char * |
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 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 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 * |
|
arguments. |
arguments. |
The first is the style name, the second its value. |
The first is the name of the style property, the second its value. |
The style name must not be |
The name must not be |
.Dv NULL . |
.Dv NULL . |
|
The |
|
.Cm s |
|
.Ar fmt |
|
letter can be repeated, each repetition requiring an additional pair of |
|
.Va char * |
|
arguments. |
.El |
.El |
.Pp |
.Pp |
.Fn print_otag |
.Fn print_otag |
|
|
.Pp |
.Pp |
The function |
The function |
.Fn html_make_id |
.Fn html_make_id |
takes a node containing one or more text children |
allocates a string to be used for the |
and returns a newly allocated string containing the concatenation |
.Cm id |
of the child strings, with blanks replaced by underscores. |
attribute of an HTML element and/or as a segment identifier for a URI in an |
If the node |
.Aq Ic A |
|
element. |
|
If |
.Fa n |
.Fa n |
contains any non-text child node, |
contains a |
.Fn html_make_id |
.Fa string |
returns |
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 |
.Dv NULL |
instead. |
is returned instead. |
The caller is responsible for freeing the returned string. |
If the |
|
.Fa unique |
|
argument is non-zero, deduplication is performed by appending an |
|
underscore and a decimal integer, if necessary. |
.Pp |
.Pp |
The function |
The function |
.Fn html_strlen |
.Fn print_otag_id |
counts the number of characters in |
opens a |
.Fa cp . |
.Fa tag |
It is used as a crude estimate of the width needed to display a string. |
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 |
.Pp |
The functions |
The functions |
.Fn print_eqn , |
.Fn print_eqn , |
|
|
and |
and |
.Fn print_tblclose |
.Fn print_tblclose |
are not yet documented. |
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 |
.Sh FILES |
.Bl -tag -width mandoc_aux.c -compact |
.Bl -tag -width mandoc_aux.c -compact |
.It Pa main.h |
.It Pa main.h |