version 1.1, 2014/07/23 18:13:09 |
version 1.11, 2018/04/13 16:28:07 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" 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 |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.Ft void |
.Ft void |
.Fn print_gen_decls "struct html *h" |
.Fn print_gen_decls "struct html *h" |
.Ft void |
.Ft void |
|
.Fn print_gen_comment "struct html *h" "struct roff_node *n" |
|
.Ft void |
.Fn print_gen_head "struct html *h" |
.Fn print_gen_head "struct html *h" |
.Ft struct tag * |
.Ft struct tag * |
.Fo print_otag |
.Fo print_otag |
.Fa "struct html *h" |
.Fa "struct html *h" |
.Fa "enum htmltag tag" |
.Fa "enum htmltag tag" |
.Fa "int sz" |
.Fa "const char *fmt" |
.Fa "const struct htmlpair *p" |
.Fa ... |
.Fc |
.Fc |
.Ft void |
.Ft void |
.Fo print_tagq |
.Fo print_tagq |
|
|
.Fa "struct html *h" |
.Fa "struct html *h" |
.Fa "const char *word" |
.Fa "const char *word" |
.Fc |
.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 |
.Sh DESCRIPTION |
The mandoc HTML formatter is not a formal library. |
The mandoc HTML formatter is not a formal library. |
However, as it is compiled into more than one program, in particular |
However, as it is compiled into more than one program, in particular |
Line 84 These structures are declared in |
|
Line 94 These structures are declared in |
|
.Bl -tag -width Ds |
.Bl -tag -width Ds |
.It Vt struct html |
.It Vt struct html |
Internal state of the HTML formatter. |
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 |
.It Vt struct tag |
One entry for the LIFO stack of HTML elements. |
One entry for the LIFO stack of HTML elements. |
Members are |
Members are |
|
|
declarations required for the current document type. |
declarations required for the current document type. |
.Pp |
.Pp |
The function |
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 |
.Fn print_gen_head |
prints the opening |
prints the opening |
.Aq Ic META |
.Aq Ic META |
|
|
.Fn print_otag |
.Fn print_otag |
prints the start tag of an HTML element with the name |
prints the start tag of an HTML element with the name |
.Fa tag , |
.Fa tag , |
including the |
optionally including the attributes specified by |
.Fa sz |
.Fa fmt . |
attributes that can optionally be provided in the |
If |
.Fa p |
.Fa fmt |
array. |
is the empty string, no attributes are written. |
It uses the private function |
Each letter of |
.Fn print_attr |
.Fa fmt |
which in turn uses the private function |
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. |
|
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 one, two, or three |
|
modifier letters. |
|
The modifier |
|
.Cm * |
|
suppresses printing of the pair if the argument matches 6n. |
|
The modifier |
|
.Cm + |
|
increases the width by 20% to make even bold text fit |
|
and adds three units for padding between columns. |
|
The modifier |
|
.Cm \- |
|
makes the width negative by multiplying it with \-1. |
|
.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. |
|
The first is the style name, the second its value. |
|
The style name must not be |
|
.Dv NULL . |
|
.El |
|
.Pp |
|
.Fn print_otag |
|
uses the private function |
.Fn print_encode |
.Fn print_encode |
to take care of HTML encoding. |
to take care of HTML encoding. |
If required by the element type, it remembers in |
If required by the element type, it remembers in |
|
|
.Fn print_tagq |
.Fn print_tagq |
functions. |
functions. |
.Pp |
.Pp |
The functions |
The function |
.Fn bufinit , |
.Fn html_make_id |
.Fn bufcat* , |
takes a node containing one or more text children |
and |
and returns a newly allocated string containing the concatenation |
.Fn buffmt* |
of the child strings, with blanks replaced by underscores. |
do not directly produce output but buffer text in the |
If the node |
.Fa buf |
.Fa n |
member of |
contains any non-text child node, |
.Fa h . |
.Fn html_make_id |
They are not used internally by |
returns |
.Pa html.c |
.Dv NULL |
but intended for use by the language-specific formatters |
instead. |
to ease preparation of strings for the |
The caller is responsible for freeing the returned string. |
.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. |
|
.Pp |
.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 |
The functions |
.Fn html_strlen , |
|
.Fn print_eqn , |
.Fn print_eqn , |
.Fn print_tbl , |
.Fn print_tbl , |
and |
and |
Line 245 implementation of common mandoc utility functions |
|
Line 394 implementation of common mandoc utility functions |
|
.An -nosplit |
.An -nosplit |
The mandoc HTML formatter was written by |
The mandoc HTML formatter was written by |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . |
This manual was written by |
It is maintained by |
.An Ingo Schwarze Aq Mt schwarze@openbsd.org . |
.An Ingo Schwarze Aq Mt schwarze@openbsd.org , |
|
who also wrote this manual. |