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