mandoc/mandoc_html.3 - diff

Return to mandoc_html.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc_html.3 between version 1.20 and 1.21

version 1.20, 2020/03/13 15:32:28

version 1.21, 2020/04/18 20:44:09

Line 21

.Nm mandoc_html

.Nd internals of the mandoc HTML formatter

.Sh SYNOPSIS

.In "html.h"

.In sys/types.h

.Fd #include """mandoc.h"""

.Fd #include """roff.h"""

.Fd #include """out.h"""

.Fd #include """html.h"""

.Ft void

.Fn print_gen_decls "struct html *h"

.Ft void

Line 46

Line 50

.Fa "const struct tag *suntil"

.Fc

.Ft void

.Fn html_close_paragraph "struct html *h"

.Ft enum roff_tok

.Fo html_fillmode

.Fa "struct html *h"

.Fa "enum roff_tok tok"

.Fc

.Ft int

.Fo html_setfont

.Fa "struct html *h"

.Fa "enum mandoc_esc font"

.Fc

.Ft void

.Fo print_text

.Fa "struct html *h"

.Fa "const char *word"

.Fc

.Ft void

.Fo print_tagged_text

.Fa "struct html *h"

.Fa "const char *word"

.Fa "struct roff_node *n"

.Fc

.Ft char *

.Fo html_make_id

.Fa "const struct roff_node *n"

Line 62

Line 84

.Fa "const char *cattr"

.Fa "struct roff_node *n"

.Fc

.Ft void

.Fn print_endline "struct html *h"

.Sh DESCRIPTION

The mandoc HTML formatter is not a formal library.

However, as it is compiled into more than one program, in particular

Line 100 These structures are declared in

Line 124 These structures are declared in

Internal state of the HTML formatter.

.It Vt struct tag

One entry for the LIFO stack of HTML elements.

Members are

Members include

.Fa "enum htmltag tag"

and

.Fa "struct tag *next" .

Line 109 and

Line 133 and

The function

.Fn print_gen_decls

prints the opening

.Ao Pf \&? Ic xml ? Ac

and

.Aq Pf \&! Ic DOCTYPE

declarations required for the current document type.

declaration.

.Pp

The function

.Fn print_gen_comment

Line 206 This format letter requires two

Line 228 This format letter requires two

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.

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

Line 239 is used to close out all open elements up to and inclu

Line 244 is used to close out all open elements up to and inclu

.Fn print_stagq

is a variant to close out all open elements up to but excluding

.Fa suntil .

The function

.Fn html_close_paragraph

closes all open elements that establish phrasing context,

thus returning to the innermost flow context.

.Pp

The function

.Fn html_fillmode

switches to fill mode if

.Fa want

.Dv ROFF_fi

or to no-fill mode if

.Fa want

.Dv ROFF_nf .

Switching from fill mode to no-fill mode closes the current paragraph

and opens a

.Aq Ic PRE

element.

Switching in the opposite direction closes the

.Aq Ic PRE

element, but does not open a new paragraph.

.Fa want

matches the mode that is already active, no elements are closed nor opened.

.Fa want

.Dv TOKEN_NONE ,

the mode remains as it is.

.Pp

The function

.Fn html_setfont

selects the

.Fa font ,

which can be

.Dv ESCAPE_FONTROMAN ,

.Dv ESCAPE_FONTBOLD ,

.Dv ESCAPE_FONTITALIC ,

.Dv ESCAPE_FONTBI ,

.Dv ESCAPE_FONTCW ,

for future text output and internally remembers

the font that was active before the change.

If the

.Fa font

argument is

.Dv ESCAPE_FONTPREV ,

the current and the previous font are exchanged.

This function only changes the internal state of the

.Fa h

object; no HTML elements are written yet.

Subsequent text output will write font elements when needed.

.Pp

The function

.Fn print_text

prints HTML element content.

It uses the private function

Line 260 and

Line 318 and

functions.

.Pp

The function

.Fn print_tagged_text

is a variant of

.Fn print_text

that wraps

.Fa word

in an

.Aq Ic A

element of class

.Qq permalink

.Fa n

is not

.Dv NULL

and yields a segment identifier when passed to

.Fn html_make_id .

.Pp

The function

.Fn html_make_id

allocates a string to be used for the

.Cm id

Line 269 element.

Line 344 element.

.Fa n

contains a

.Fa string

.Fa tag

attribute, it is used; otherwise, child nodes are used.

.Fa n

Line 308 it attempts to generate an

Line 383 it attempts to generate an

.Cm id

attribute with

.Fn html_make_id .

If an

If the flag

.Cm id

.Dv NODE_HREF

attribute is written,

is set in

.Fn print_otag_id

.Fa n ,

also adds an

.Aq Ic A

element of class

.Qq permalink :

.Qq permalink

is added:

outside if

.Fa n

generates a phrasing element, or inside otherwise.

generates an element that can only occur in phrasing context,

or inside otherwise.

This function is a wrapper around

.Fn html_make_id

and

Line 333 and

Line 410 and

.Qq ci ,

respectively.

.Pp

The function

.Fn print_endline

makes sure subsequent output starts on a new HTML output line.

If nothing was printed on the current output line yet, it has no effect.

Otherwise, it appends any buffered text to the current output line,

ends the line, and updates the internal state of the

.Fa h

object.

.Pp

The functions

.Fn print_eqn ,

.Fn print_tbl ,

Line 357 is called on it or when

Line 443 is called on it or when

is called on a parent element.

.Pp

The function

.Fn html_fillmode

returns

.Dv ROFF_fi

if fill mode was active before the call or

.Dv ROFF_nf

otherwise.

.Pp

The function

.Fn html_make_id

returns a newly allocated string or

.Dv NULL

Line 404 HTML formatter

Line 498 HTML formatter

.It Pa eqn_html.c

.Xr eqn 7

HTML formatter

.It Pa roff_html.c

.Xr roff 7

HTML formatter, handling requests like

.Ic br ,

.Ic ce ,

.Ic fi ,

.Ic ft ,

.Ic nf ,

.Ic rj ,

and

.Ic sp .

.It Pa out.h

declarations of data types and private functions

for shared use by all mandoc formatters,

CVSweb