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

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

version 1.16, 2018/06/25 14:13:54

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 25

.Ft void

.Fn print_gen_decls "struct html *h"

.Ft void

.Fn print_gen_comment "struct html *h" "struct roff_node *n"

.Ft void

.Fn print_gen_head "struct html *h"

.Ft struct tag *

.Fo print_otag

Line 48

Line 50

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

Line 111 and

declarations required for the current document type.

.Pp

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

prints the opening

.Aq Ic META

Line 137 Most attributes require one

Line 159 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 205 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

.Vt int

argument, interpreted as a horizontal length in units of

.Dv SCALE_EN .

.It Cm s

Requires one

.Vt char *

Line 181 argument, used as a style value.

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

.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

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 t

Set

.Cm margin-top

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?

Line 231 requires two

Line 239 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 277 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 345 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