Deleted Added
full compact
mandoc_html.3 (316420) mandoc_html.3 (322249)
1.\" $Id: mandoc_html.3,v 1.3 2017/01/17 15:32:44 schwarze Exp $
1.\" $Id: mandoc_html.3,v 1.10 2017/07/15 17:57:51 schwarze Exp $
2.\"
3.\" Copyright (c) 2014, 2017 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
2.\"
3.\" Copyright (c) 2014, 2017 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: January 17 2017 $
17.Dd $Mdocdate: July 15 2017 $
18.Dt MANDOC_HTML 3
19.Os
20.Sh NAME
21.Nm mandoc_html
22.Nd internals of the mandoc HTML formatter
23.Sh SYNOPSIS
24.In "html.h"
25.Ft void

--- 17 unchanged lines hidden (view full) ---

43.Fa "struct html *h"
44.Fa "const struct tag *suntil"
45.Fc
46.Ft void
47.Fo print_text
48.Fa "struct html *h"
49.Fa "const char *word"
50.Fc
18.Dt MANDOC_HTML 3
19.Os
20.Sh NAME
21.Nm mandoc_html
22.Nd internals of the mandoc HTML formatter
23.Sh SYNOPSIS
24.In "html.h"
25.Ft void

--- 17 unchanged lines hidden (view full) ---

43.Fa "struct html *h"
44.Fa "const struct tag *suntil"
45.Fc
46.Ft void
47.Fo print_text
48.Fa "struct html *h"
49.Fa "const char *word"
50.Fc
51.Ft char *
52.Fo html_make_id
53.Fa "const struct roff_node *n"
54.Fc
55.Ft int
56.Fo html_strlen
57.Fa "const char *cp"
58.Fc
51.Sh DESCRIPTION
52The mandoc HTML formatter is not a formal library.
53However, as it is compiled into more than one program, in particular
54.Xr mandoc 1
55and
56.Xr man.cgi 8 ,
57and because it may be security-critical in some contexts,
58some documentation is useful to help to use it correctly and

--- 73 unchanged lines hidden (view full) ---

132is the empty string, no attributes are written.
133Each letter of
134.Fa fmt
135specifies one attribute to write.
136Most attributes require one
137.Va char *
138argument which becomes the value of the attribute.
139The arguments have to be given in the same order as the attribute letters.
59.Sh DESCRIPTION
60The mandoc HTML formatter is not a formal library.
61However, as it is compiled into more than one program, in particular
62.Xr mandoc 1
63and
64.Xr man.cgi 8 ,
65and because it may be security-critical in some contexts,
66some documentation is useful to help to use it correctly and

--- 73 unchanged lines hidden (view full) ---

140is the empty string, no attributes are written.
141Each letter of
142.Fa fmt
143specifies one attribute to write.
144Most attributes require one
145.Va char *
146argument which becomes the value of the attribute.
147The arguments have to be given in the same order as the attribute letters.
148If an argument is
149.Dv NULL ,
150the respective attribute is not written.
140.Bl -tag -width 1n -offset indent
141.It Cm c
142Print a
143.Cm class
144attribute.
151.Bl -tag -width 1n -offset indent
152.It Cm c
153Print a
154.Cm class
155attribute.
156This attribute letter can optionally be followed by the modifier letter
157.Cm T .
158In that case, a
159.Cm title
160attribute with the same value is also printed.
145.It Cm h
146Print a
147.Cm href
148attribute.
149This attribute letter can optionally be followed by a modifier letter.
150If followed by
151.Cm R ,
152it formats the link as a local one by prefixing a

--- 17 unchanged lines hidden (view full) ---

170Print an
171.Cm id
172attribute.
173.It Cm \&?
174Print an arbitrary attribute.
175This format letter requires two
176.Vt char *
177arguments, the attribute name and the value.
161.It Cm h
162Print a
163.Cm href
164attribute.
165This attribute letter can optionally be followed by a modifier letter.
166If followed by
167.Cm R ,
168it formats the link as a local one by prefixing a

--- 17 unchanged lines hidden (view full) ---

186Print an
187.Cm id
188attribute.
189.It Cm \&?
190Print an arbitrary attribute.
191This format letter requires two
192.Vt char *
193arguments, the attribute name and the value.
194The name must not be
195.Dv NULL .
178.It Cm s
179Print a
180.Cm style
181attribute.
182If present, it must be the last format letter.
183In contrast to the other format letters, this one does not yet
196.It Cm s
197Print a
198.Cm style
199attribute.
200If present, it must be the last format letter.
201In contrast to the other format letters, this one does not yet
184print the value and does not require an argument.
202print the value and does not take an argument.
185Instead, the rest of the format string consists of pairs of
186argument type letters and style name letters.
187.El
188.Pp
203Instead, the rest of the format string consists of pairs of
204argument type letters and style name letters.
205.El
206.Pp
189Argument type letters each require on argument as follows:
207Argument type letters each require one argument as follows:
190.Bl -tag -width 1n -offset indent
191.It Cm h
192Requires one
193.Vt int
194argument, interpreted as a horizontal length in units of
195.Dv SCALE_EN .
196.It Cm s
197Requires one
198.Vt char *
199argument, used as a style value.
200.It Cm u
201Requires one
202.Vt struct roffsu *
203argument, used as a length.
208.Bl -tag -width 1n -offset indent
209.It Cm h
210Requires one
211.Vt int
212argument, interpreted as a horizontal length in units of
213.Dv SCALE_EN .
214.It Cm s
215Requires one
216.Vt char *
217argument, used as a style value.
218.It Cm u
219Requires one
220.Vt struct roffsu *
221argument, used as a length.
204.It Cm v
205Requires one
206.Vt int
207argument, interpreted as a vertical length in units of
208.Dv SCALE_VS .
209.It Cm w
210Requires one
211.Vt char *
212argument, interpreted as an
213.Xr mdoc 7 Ns -style
214width specifier.
222.It Cm w
223Requires one
224.Vt char *
225argument, interpreted as an
226.Xr mdoc 7 Ns -style
227width specifier.
228If the argument is
229.Dv NULL ,
230nothing is printed for this pair.
231.Pp
232The
233.Cm w
234argument type letter can optionally be followed by one, two, or three
235modifier letters.
236The modifier
237.Cm *
238suppresses printing of the pair if the argument matches 6n.
239The modifier
240.Cm +
241increases the width by 20% to make even bold text fit
242and adds three units for padding between columns.
243The modifier
244.Cm \-
245makes the width negative by multiplying it with \-1.
215.El
216.Pp
217Style name letters decide what to do with the preceding argument:
218.Bl -tag -width 1n -offset indent
246.El
247.Pp
248Style name letters decide what to do with the preceding argument:
249.Bl -tag -width 1n -offset indent
219.It Cm b
220Set
221.Cm margin-bottom
222to the given length.
223.It Cm h
224Set
225.Cm height
226to the given length.
227.It Cm i
228Set
229.Cm text-indent
230to the given length.
231.It Cm l
232Set
233.Cm margin-left
234to the given length.
250.It Cm h
251Set
252.Cm height
253to the given length.
254.It Cm i
255Set
256.Cm text-indent
257to the given length.
258.It Cm l
259Set
260.Cm margin-left
261to the given length.
235.It Cm t
236Set
237.Cm margin-top
238to the given length.
239.It Cm w
240Set
241.Cm width
242to the given length.
243.It Cm W
244Set
245.Cm min-width
246to the given length.
247.It Cm \&?
248The special pair
249.Cm s?
250requires two
251.Vt char *
252arguments.
253The first is the style name, the second its value.
262.It Cm w
263Set
264.Cm width
265to the given length.
266.It Cm W
267Set
268.Cm min-width
269to the given length.
270.It Cm \&?
271The special pair
272.Cm s?
273requires two
274.Vt char *
275arguments.
276The first is the style name, the second its value.
277The style name must not be
278.Dv NULL .
254.El
255.Pp
256.Fn print_otag
257uses the private function
258.Fn print_encode
259to take care of HTML encoding.
260If required by the element type, it remembers in
261.Fa h

--- 20 unchanged lines hidden (view full) ---

282wraps
283.Fa word
284in an HTML font selection element using the
285.Fn print_otag
286and
287.Fn print_tagq
288functions.
289.Pp
279.El
280.Pp
281.Fn print_otag
282uses the private function
283.Fn print_encode
284to take care of HTML encoding.
285If required by the element type, it remembers in
286.Fa h

--- 20 unchanged lines hidden (view full) ---

307wraps
308.Fa word
309in an HTML font selection element using the
310.Fn print_otag
311and
312.Fn print_tagq
313functions.
314.Pp
315The function
316.Fn html_make_id
317takes a node containing one or more text children
318and returns a newly allocated string containing the concatenation
319of the child strings, with blanks replaced by underscores.
320If the node
321.Fa n
322contains any non-text child node,
323.Fn html_make_id
324returns
325.Dv NULL
326instead.
327The caller is responsible for freeing the returned string.
328.Pp
329The function
330.Fn html_strlen
331counts the number of characters in
332.Fa cp .
333It is used as a crude estimate of the width needed to display a string.
334.Pp
290The functions
335The functions
291.Fn html_strlen ,
292.Fn print_eqn ,
293.Fn print_tbl ,
294and
295.Fn print_tblclose
296are not yet documented.
297.Sh FILES
298.Bl -tag -width mandoc_aux.c -compact
299.It Pa main.h

--- 31 unchanged lines hidden (view full) ---

331.Sh SEE ALSO
332.Xr mandoc 1 ,
333.Xr mandoc 3 ,
334.Xr man.cgi 8
335.Sh AUTHORS
336.An -nosplit
337The mandoc HTML formatter was written by
338.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
336.Fn print_eqn ,
337.Fn print_tbl ,
338and
339.Fn print_tblclose
340are not yet documented.
341.Sh FILES
342.Bl -tag -width mandoc_aux.c -compact
343.It Pa main.h

--- 31 unchanged lines hidden (view full) ---

375.Sh SEE ALSO
376.Xr mandoc 1 ,
377.Xr mandoc 3 ,
378.Xr man.cgi 8
379.Sh AUTHORS
380.An -nosplit
381The mandoc HTML formatter was written by
382.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
339This manual was written by
340.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
383It is maintained by
384.An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
385who also wrote this manual.