Debian Codegraph @

upstream/debian-unstable/man7/groff_www.7

raw
1 .TH groff_www 7 "2026-04-22" "groff 1.24.1"
2 .SH Name
3 groff_www \- GNU
4 .I roff
5 macros for authoring web pages
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright 2000-2020 Free Software Foundation, Inc.
13 .\"
14 .\" This file is part of groff, the GNU roff typesetting system.
15 .\"
16 .\" groff is free software; you can redistribute it and/or modify it
17 .\" under the terms of the GNU General Public License as published by
18 .\" the Free Software Foundation, either version 3 of the License, or
19 .\" (at your option) any later version.
20 .\"
21 .\" groff is distributed in the hope that it will be useful, but WITHOUT
22 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
23 .\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
24 .\" License for more details.
25 .\"
26 .\" You should have received a copy of the GNU General Public License
27 .\" along with this program. If not, see
28 .\" <http://www.gnu.org/licenses/>.
29 .
30 .
31 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
32 .do nr *groff_groff_www_7_man_C \n[.cp]
33 .cp 0
34 .
35 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
36 .nr do-fallback 0
37 .if !\n(.f .nr do-fallback 1 \" mandoc
38 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
39 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
40 .if \n[do-fallback] \{\
41 . de MR
42 . ie \\n(.$=1 \
43 . I \%\\$1
44 . el \
45 . IR \%\\$1 (\\$2)\\$3
46 . .
47 .\}
48 .rr do-fallback
49 .
50 .
51 .\" ====================================================================
52 .SH Synopsis
53 .\" ====================================================================
54 .
55 .SY "groff \-m www"
56 .RI [ option\~ .\|.\|.\&]
57 .RI [ file\~ .\|.\|.]
58 .YS
59 .
60 .
61 .\" ====================================================================
62 .SH Description
63 .\" ====================================================================
64 .
65 This manual page describes the GNU
66 .I www
67 macro package,
68 which is part of the
69 .MR groff 7
70 document formatting system.
71 .
72 This macro file is automatically loaded by the default
73 .I troffrc
74 file when the formatter
75 (usually
76 .MR groff 1 )
77 is called with either of the options
78 .RB \[lq] \-T\~html \[rq]
79 or
80 .RB \[lq] \-T\~xhtml \[rq].
81 .
82 The HTML output driver
83 .MR grohtml 1
84 is in a beta state;
85 .I groff
86 distributes these macros to encourage its testing.
87 .
88 .
89 .P
90 .TS
91 tab(@);
92 L L
93 Lb L.
94 Macro@Meaning
95 _
96 JOBNAME@split output into multiple files
97 HX@automatic heading level cut-off
98 BCL@specify colours on a web page
99 BGIMG@specify background image
100 URL@create a URL using two parameters
101 MTO@create an HTML email address
102 TAG@generate an HTML name
103 IMG@include an image file
104 PIMG@include PNG image
105 MPIMG@place PNG on the margin and wrap text around it
106 HnS@begin heading
107 HnE@end heading
108 LK@emit automatically collected links
109 HR@produce a horizontal rule
110 NHR@suppress automatic generation of rules
111 HTL@record document title as HTML metadata only
112 HEAD@add data to <head> block
113 ULS@unordered list begin
114 ULE@unordered list end
115 OLS@ordered list begin
116 OLE@ordered list end
117 DLS@definition list begin
118 DLE@definition list end
119 LI@insert a list item
120 DC@generate a drop capital
121 HTML@transmit raw HTML to output driver
122 CDS@code example begin
123 CDE@code example end
124 ALN@place links on left of main text
125 LNS@start two-column table with links on the left
126 LNE@end two-column table started with \fB.LNS\fP
127 LINKSTYLE@initialize default URL attributes
128 .TE
129 .
130 .
131 .\" ====================================================================
132 .SH Macros
133 .\" ====================================================================
134 .
135 .TP 9n \" "HTML" + 2n + hand-tuned for PDF
136 .BI JOBNAME\~ file-name-stem
137 Split output into multiple HTML files.
138 .
139 In
140 .I ms
141 documents,
142 a file is split whenever an
143 .B .SH
144 or
145 .RB \[lq] ".NH\~1" \[rq]
146 call is encountered.
147 .
148 Its argument is the file name stem used for output files.
149 .
150 This option is equivalent to
151 .IR \%grohtml 's
152 .B \-j
153 option.
154 .
155 .
156 .TP
157 .BI HX\~ n
158 Set section heading level above which
159 .I \%grohtml
160 is not to automatically generate links to
161 .I n.
162 .
163 For example,
164 when used with the
165 .MR groff_ms 7
166 package,
167 .RB \[lq] ".HX\~2" \[rq]
168 causes
169 .I \%grohtml
170 to generate a list of links for
171 .I ms
172 macro calls
173 .RB \[lq] ".NH\~1" \[rq]
174 and
175 .RB \[lq] ".NH\~2" \[rq]
176 but not for
177 .RB \[lq] ".NH\~3" \[rq],
178 whereas
179 .RB \[lq] ".HX\~0" \[rq]
180 generates no hyperlinks to section headings.
181 .
182 Giving
183 .I groff
184 the option
185 .RB \[lq] "\-P\~\-l" \[rq]
186 disables automatic heading linkage.
187 .
188 .
189 .TP
190 .BI BCL\~ "foreground background active not-visited visited"
191 Configure colours used for
192 page foreground,
193 page background,
194 active hypertext link,
195 hypertext links not yet visited,
196 and visited hypertext links.
197 .
198 .
199 .TP
200 .BI BGIMG\~ file
201 Set the background image
202 to
203 .I file.
204 .
205 .
206 .TP
207 .BI URL\~ url\~\c
208 .RI [ link-text \~[ post ]]
209 Generate a hyperlink to
210 .I url
211 with optional
212 .I link-text
213 followed immediately by non-linked text
214 .I post.
215 .
216 .
217 .IP
218 If
219 .I link-text
220 is absent,
221 .I url
222 is formatted as the link text.
223 .
224 Hyphenation is disabled while formatting a URL;
225 insert explicit break points with the
226 .B \[rs]:
227 escape sequence.
228 .
229 .
230 .TP
231 .BI MTO\~ address\~\c
232 .RI [ link-text \~[ post ]]
233 Generate an email hyperlink to
234 .I address
235 with optional
236 .I link-text
237 followed immediately by non-linked text
238 .I post.
239 .
240 .
241 .IP
242 If
243 .I link-text
244 is absent,
245 .I address
246 is formatted as the link text.
247 .
248 Hyphenation is disabled while formatting a URL;
249 insert explicit break points with the
250 .B \[rs]:
251 escape sequence.
252 .
253 .
254 .TP
255 .BI TAG\~ name
256 Generate an anchor
257 .I name
258 marking its location in the document as a target for hyperlinks.
259 .
260 .
261 .TP
262 .BI IMG\~ file-name\~\c
263 .RB [ \-C | \-L | \-R ]\~\c
264 .RI [ width \~[ height ]]
265 Insert graphical image
266 .I file-name.
267 .
268 The optional second argument aligns the image to the center
269 .RB ( \-C ;\~default),
270 left
271 .RB ( \-L ),
272 or
273 right
274 .RB ( \-R ).
275 .
276 The optional
277 .I width
278 defaults to 100 units
279 (in the context of the HTML renderer)
280 and the optional
281 .I height
282 to the same measurement as
283 .I width .
284 .
285 .
286 .TP
287 .BR PIMG\~ [ \-C | \-L | \-R ]\~\c
288 .IR file-name\~ [ width \~[ height ]]
289 Insert graphical image
290 .I file-name,
291 assumed to be in PNG format.
292 .
293 Compared to
294 .BR IMG ,
295 this macro has the advantage of working with both PostScript and HTML
296 devices since it converts
297 .I file-name
298 into EPS format using
299 .MR pngtopnm 1 ,
300 .MR pnmcrop 1 ,
301 and
302 .MR pnmtops 1 .
303 .
304 .I height
305 and
306 .I width
307 may be given as percentages
308 (of the line length
309 .B \[rs]n[.l]
310 and page length
311 .BR \[rs]n[.p] ,
312 respectively).
313 .
314 .
315 .IP
316 If the document isn't processed with
317 .RB \[lq] \-T\~html \[rq]
318 or
319 .RB \[lq] \-T\~xhtml \[rq],
320 you must use
321 .MR groff 1 's
322 .B \-U
323 option.
324 .\" XXX: stale? Does this predate the `psbb` request?
325 .
326 .
327 .TP
328 .BR MPIMG\~ [ \-L | \-R ]\~[ \-G\~\c
329 .IR gap ]\~\c
330 .IR file-name\~ [ width \~[ height ]]
331 As
332 .BR PIMG ,
333 but place the image at a margin and wrap text around it.
334 .
335 The image is aligned the to the left
336 .RB ( \-L ,
337 default)
338 or right
339 .RB ( \-R )
340 margin.
341 .
342 .BI \-G \~gap
343 imposes horizontal space of
344 .I gap
345 pixels between the picture and the text that wraps around it.
346 .
347 The default
348 .I gap
349 is zero.
350 .
351 .
352 .TP
353 .BI HnS\~ n
354 Begin heading at level
355 .I n.
356 .
357 .
358 .TP
359 .B HnE
360 End heading text.
361 .
362 .
363 .TP
364 .B LK
365 Direct
366 .I \%grohtml
367 to emit the list of automatically generated hyperlinks at this location.
368 .
369 .
370 .TP
371 .B HR
372 Generate a full-width horizontal rule when used with
373 .RB \[lq] \-T\~html \[rq]
374 or
375 .RB \[lq] \-T\~xhtml \[rq].
376 .
377 .
378 .TP
379 .B NHR
380 Suppress the horizontal rules at the document's top and bottom that
381 .I \%grohtml
382 emits by default.
383 .
384 .
385 .TP
386 .B HTL
387 Generate an HTML title only.
388 .
389 This differs from
390 .MR groff_ms 7 's
391 .B TL
392 macro,
393 which generates both an HTML title and an <H1> heading.
394 .
395 Use it to provide an HTML title as document metadata but not as
396 formatted text.
397 .
398 The title ends when vertical space
399 .RB ( .sp )
400 or a break
401 .RB ( .br )
402 is seen.
403 .
404 .
405 .TP
406 .B HEAD
407 Add arbitrary data to the HTML <head> element.
408 .
409 Ignored if not processed with
410 .RB \[lq] \-T\~html \[rq]
411 or
412 .RB \[lq] \-T\~xhtml \[rq].
413 .
414 .
415 .TP
416 .B HTML
417 All text after this macro is treated as raw HTML.
418 .
419 Ignored if not processed with
420 .RB \[lq] \-T\~html \[rq]
421 or
422 .RB \[lq] \-T\~xhtml \[rq].
423 .
424 .
425 .TP
426 .BI DC\~ "L text"\~\c
427 .RI [ color ]
428 Format a \[lq]drop cap\[rq]\[em]a large character
429 .I L
430 (usually a capital letter)
431 at a larger size and with a lower text baseline
432 than the following
433 .I text,
434 such that the cap-heights of
435 .I L
436 and
437 .I text
438 align,
439 in the specified
440 .I color
441 (default: black).
442 .
443 .
444 .TP
445 .B CDS
446 Begin code display;
447 a monospaced font is selected and filling is disabled.
448 .
449 .
450 .TP
451 .B CDE
452 End code display.
453 .
454 .
455 .TP
456 .BR ALN \~\c
457 .RI [ color\~ [ width-percentage ]]
458 Enable a \[lq]navigation pane\[rq] containing links to section headings,
459 aligned to the left of running text,
460 and configure its rendering parameters.
461 .
462 Columnation is achieved with an HTML table.
463 .
464 .I color
465 indicates an HTML background color to be used in the navigation column;
466 the default is
467 .BR #eeeeee .
468 .
469 .I width-percentage
470 allocates the given percentage of the navigation pane's table column;
471 the default is
472 .BR 30 .
473 .
474 Call this macro at most once,
475 at the beginning of the document.
476 .
477 .
478 .TP
479 .B LNS
480 Begin text indexed by the navigation pane configured by
481 .BR ALN .
482 .
483 .
484 .TP
485 .B LNE
486 End text indexed by navigation pane started by
487 .BR LNS .
488 .
489 .
490 .TP
491 .BI LINKSTYLE\~ color\~\c
492 .RI [ font-style\~ [ "open-glyph close-glyph" ]]
493 Configure rendering of formatted hyperlink targets for devices other
494 than
495 .B html
496 and
497 .BR xhtml ;
498 render
499 targets in
500 .I color
501 (default:
502 blue) \" XXX: whose default? the browser's?
503 using the typeface
504 .I font-style
505 (default:
506 .BR CR )
507 bracketed with
508 .I open-glyph
509 and
510 .I close-glyph
511 (defaults:
512 .B \[rs][la]
513 and
514 .BR \[rs][ra] ,
515 respectively).
516 .
517 .
518 .\" ====================================================================
519 .SH "Section heading links"
520 .\" ====================================================================
521 .
522 By default
523 .I \%grohtml
524 generates links to all section headings and places these at the top of
525 the HTML document.
526 .
527 Configure this behavior with
528 .B HX
529 and/or
530 .BR LK .
531 .
532 .
533 .\" ====================================================================
534 .SH "Limitations of \f[I]grohtml\f[]"
535 .\" ====================================================================
536 .
537 .MR \%tbl 1
538 tables are rendered as PNG images.
539 .\"
540 .\" Paul DuBois's approach with
541 .\" .MR tblcvt 1 ,
542 .\" part of the
543 .\" .UR http://\:www\:.snake\:.net/\:software/\:troffcvt/
544 .\" .I troffcvt
545 .\" distribution
546 .\" .UE ,
547 .\" should be explored.
548 .
549 .
550 .P
551 All URLs currently are treated as consuming no textual
552 space in
553 .IR groff .
554 .
555 This could be considered as a bug since it causes some problems.
556 .
557 To circumvent this,
558 .I www.tmac
559 inserts a zero-width character which expands to a harmless space
560 (only
561 if run with
562 .B \-Thtml
563 or
564 .BR \-Txhtml ).
565 .
566 .
567 .P
568 Some of the macros,
569 like
570 .BR ALN ,
571 .BR LNS ,
572 and
573 .BR LNE ,
574 are integrated only with the
575 .MR groff_ms 7
576 package.
577 .
578 .
579 .\" ====================================================================
580 .SH Files
581 .\" ====================================================================
582 .
583 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:www\:.tmac
584 .
585 .
586 .\" ====================================================================
587 .SH Authors
588 .\" ====================================================================
589 .
590 The
591 .I www
592 macro package
593 was written by
594 .MT gaius@\:glam\:.ac\:.uk
595 Gaius Mulley
596 .ME ,
597 with additions by
598 .MT wl@\:gnu\:.org
599 Werner Lemberg
600 .ME
601 and
602 .MT groff\-bernd\:.warken\-72@\:web\:.de
603 Bernd Warken
604 .ME .
605 .
606 .
607 .\" ====================================================================
608 .SH "See also"
609 .\" ====================================================================
610 .
611 .MR groff 1 ,
612 .MR \%troff 1 ,
613 .MR grohtml 1 ,
614 .MR netpbm 1
615 .
616 .
617 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
618 .cp \n[*groff_groff_www_7_man_C]
619 .do rr *groff_groff_www_7_man_C
620 .
621 .
622 .\" Local Variables:
623 .\" fill-column: 72
624 .\" mode: nroff
625 .\" End:
626 .\" vim: set filetype=groff textwidth=72: