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.2 and 1.9

version 1.2, 2017/01/17 01:47:51

version 1.9, 2017/07/14 16:06:44

Line 1

.\" $Id$

.\"

.\" Permission to use, copy, modify, and distribute this software for any

.\" purpose with or without fee is hereby granted, provided that the above

Line 48

.Fa "struct html *h"

.Fa "const char *word"

.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

The mandoc HTML formatter is not a formal library.

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

Line 137 Most attributes require one

Line 145 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

Line 155 Print an arbitrary attribute.

Line 191 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 require an argument.

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:

Argument type letters each require one argument as follows:

.Bl -tag -width 1n -offset indent

.It Cm h

Requires one

Line 181 argument, used as a style value.

Line 219 argument, used as a style value.

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.

.Pp

The

.Cm w

argument type letter can optionally be followed by one or two

modifier letters.

The modifier

.Cm +

increases the width by 10% to make even bold text fit

and adds two 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 b

Set

.Cm margin-bottom

to the given length.

.It Cm h

Set

.Cm height

Line 212 to the given length.

Line 256 to the given length.

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

Line 231 requires two

Line 271 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_attr

which in turn uses the private function

.Fn print_encode

to take care of HTML encoding.

If required by the element type, it remembers in

Line 269 and

Line 309 and

.Fn print_tagq

functions.

.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

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

.Fn html_strlen ,

.Fn print_eqn ,

.Fn print_tbl ,

and

Line 340 implementation of common mandoc utility functions

Line 377 implementation of common mandoc utility functions

.An -nosplit

The mandoc HTML formatter was written by

.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.

CVSweb