2 www.tmac - macro package for adding HTML elements to roff documents.
4 File position: <groff_source_top>/tmac/www.tmac
5 Installed position: groff's main macro directory.
7 ------------------------------------------------------------------------
9 ------------------------------------------------------------------------
11 This file is part of groff, the GNU roff type-setting system.
13 Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc.
14 written by Gaius Mulley <gaius@glam.ac.uk>, with additions by
15 Werner Lemberg <wl@gnu.org> and Bernd Warken <bwarken@mayn.de>.
17 groff is free software; you can redistribute it and/or modify it under
18 the terms of the GNU General Public License as published by the Free
19 Software Foundation; either version 2, or (at your option) any later
22 groff is distributed in the hope that it will be useful, but WITHOUT
23 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
24 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
27 You should have received a copy of the GNU General Public License
28 along with groff; see the file COPYING. If not, write to the Free
29 Software Foundation, 59 Temple Place - Suite 330, Boston, MA
33 ------------------------------------------------------------------------
35 ------------------------------------------------------------------------
37 A simple set of macros to provide HTML documents with basic
38 www functionality. It should work with any macro set.
41 .\" --------------------------------------------------------------------
43 .\" --------------------------------------------------------------------
49 .if '\*[.T]'html' .nr www-html 1
51 .\" set up www-image-template
53 .if !d www-image-template \
54 . ds www-image-template
57 . \" remove the title command when we are generating images for html
58 . \" (stops a title accidentally appearing inside an image)
68 .\" --------------------------------------------------------------------
69 .\" Test for `.substring'; result in register `www.substring_ok'.
70 .\" The automated break points in .URL addresses are only added if
71 .\" this register is non-zero.
73 .nr www:substring_ok 0
74 .de www:@test_substring
78 . substring \\$0:s 1 1
79 . if !'\\*[\\$0:s]'b' \{\
84 . substring \\$0:s 0 0
85 . if !'\\*[\\$0:s]'a' \{\
90 . substring \\$0:s 1 -1
91 . if !'\\*[\\$0:s]'bcdefg' \{\
95 . nr www:substring_ok 1
99 .rm www:@test_substring
102 .\" --------------------------------------------------------------------
104 .\" --------------------------------------------------------------------
106 .\" --------------------------------------------------------------------
107 .\" www:error (<test>...)
109 .\" Print error message
112 . tm \\n[.F]:\\n[.c]: macro error: \\$*
114 .als www:error www-error
116 .\" --------------------------------------------------------------------
117 .\" www:lenstr (<register_name> <string_name>)
119 .\" Store length of string named <string_name> into register named
123 . if !(\\n[.$] == 2) \{\
124 . tm .\\$0 expects 2 arguments.
127 . length \\$0:n x\\*[\\$2]
128 . nr \\$1 (\\n[\\$0:n]-1)
131 .\" --------------------------------------------------------------------
132 .\" www:splitstr (<name>)
134 .\" Add a space character between any two adjacent characters in string
135 .\" <name> and restore result into the string variable <name>; space
136 .\" characters are first replaced by the word `space'.
139 . if !(\\n[.$] == 1) \
140 . www:error .\\$0 expects 1 argument.
143 . ds \\$0:r "\\*[\\$1]\""
146 . ds \\$0:c "\\*[\\$0:r]\""
147 . substring \\$0:c 0 0\"
148 . ie '\\*[\\$0:c]' ' \
149 . as \\$0:s " space\""
151 . as \\$0:s " \\*[\\$0:c]\""
152 . www:lenstr \\$0:n \\$0:r
153 . if (\\n[\\$0:n] <= 1) \{\
156 . substring \\$0:r 1 -1\"
158 . if !'\\*[\\$0:s]'' \
159 . substring \\$0:s 1 -1
160 . ds \\$1 \\*[\\$0:s]
166 .\" --------------------------------------------------------------------
167 .\" www:url_breaks (<string_name>)
169 .\" Add `\:' (possible break point) within URL strings after `/'.
171 .\" Smart about multiple `/', existing `\:', and space characters;
172 .\" does not set a break point if less than 5 characters would go to
176 . if !(\\n[.$] == 1) \
177 . www:error .\\$0 expects 1 argument.
178 . if !\n[www:substring_ok] \
180 . ds \\$0:s "\\*[\\$1]\""
181 . www:splitstr \\$0:s
182 . www:url_breaks_splitted \\$0:s \\*[\\$0:s]
183 . ds \\$1 "\\*[\\$0:s]\""
186 .\" --------------------------------------------------------------------
187 .\" www:url_breaks_splitted (<result> <char> [<char>...])
189 .\" Add `\:' within URL strings, but arguments are a splitted string.
191 .\" Arguments: >=2: <result> <char> [<char>...]
193 .de www:url_breaks_splitted
194 . nr \\$0:min 5 \" minimal number of characters for next line
196 . www:error .\\$0 expects at least 2 arguments.
201 . while !\\n[\\$0:done] \{\
202 . if (\\n[.$] <= 0) \{\
206 . if '\\$1'space' \{\
211 . if (\\n[.$] < \\n[\\$0:min]) \{\
221 . \" we are at a `/' character
224 . if (\\n[.$] == 0) \{\
230 . if \\n[\\$0:done] \
232 . if (\\n[.$] < \\n[\\$0:min]) \
238 . ds \\*[\\$0:res] \\*[\\$0:s]\"
242 .\" --------------------------------------------------------------------
244 .\" --------------------------------------------------------------------
246 .\" --------------------------------------------------------------------
247 .\" HTML (<address> <description> [<punctuation>])
249 .\" the main auxiliary macro for the HTML interface
252 . if \\n[www-html] \{\
253 . \" the following line makes the vertical mode leave, so to say
259 .\" an auxiliary macro for HTML (without following space)
263 . nop \X^html:\\$*^\c
265 .\" --------------------------------------------------------------------
268 .\" Automatic heading level cut off.
270 .\" N is the depth limit of automatically linked headings. So a depth
271 .\" of 2 would cause grohtml to generate a list of links for `.NH 1'
272 .\" and `.NH 2' but not for `.NH 3'.
278 .\" --------------------------------------------------------------------
279 .\" BCL foreground background active not-visited visited
282 . HTML <body text=\\$1 bgcolor=\\$2 link=\\$3 alink=\\$4 vlink=\\$5>
284 .\" --------------------------------------------------------------------
288 . HTML <body background=\\$1>
290 .\" --------------------------------------------------------------------
291 .\" URL url [description] [after]
292 .\" if description is absent then the url becomes the anchor text
296 . www:url_breaks \\$0:adr
297 . ie \\n[www-html] \{\
299 . HTML <a href="\\$1">\\$1</a>\\$3
301 . HTML <a href="\\$1">\\$2</a>\\$3
304 . if !r ps4html .ad l
306 . nop \%\[la]\m[blue]\f[C]\\*[\\$0:adr]\f[]\m[]\[ra]\\$3
308 . nop \m[blue]\\$2\m[] \%\[la]\f[C]\\*[\\$0:adr]\f[]\[ra]\\$3
313 .\" --------------------------------------------------------------------
314 .\" FTP url description [after]
319 .\" --------------------------------------------------------------------
320 .\" MTO address description [after]
322 .\" ADDRESS is the email address (without the `mailto:' prefix).
324 .\" DESCRIPTION is the optional name. If an empty argument is given,
325 .\" ADDRESS is used instead.
327 .\" AFTER is optional stuff printed immediately after ADDRESS
328 .\" (resp. DESCRIPTION).
332 .\" Foobar has been written by
333 .\" .MTO fred@foo.bar "Fredrick Bloggs" .
336 . ie \\n[www-html] \{\
338 . URL mailto:\\$1 \\$1 "\\$3"
340 . URL mailto:\\$1 "\\$2" "\\$3"
344 . nop \%\m[blue]\f[C]\\$1\f[]\m[]\\$3
346 . nop \m[blue]\\$2\m[] \%\[la]\f[C]\\$1\f[]\[ra]\\$3
349 .\" --------------------------------------------------------------------
352 .\" Generate an html name NAME.
355 . HTML <a name="\\$1"></a>
357 .\" --------------------------------------------------------------------
358 .\" IMG [-R|-L|-C] filename [width] [height]
360 .\" Include an image of any type (will only work for -Thtml).
362 .\" Alignment is centered by default (-C).
363 .\" Default value for WIDTH is 1i.
364 .\" If HEIGHT is not given, WIDTH is used as the height.
367 . ie \\n[www-html] \{\
369 . HTML-TAG ".right-image"
372 . HTML-TAG ".left-image"
374 . HTML-TAG ".centered-image"
379 . nr www-height \\n[www-width]
382 . HTML <img src="\\$1" width=\\n[www-width] height=\\n[www-height]>
385 . nop \[la]\f[C]\\$1\f[]\[ra]
387 .\" --------------------------------------------------------------------
390 .\" Emit a tag for grohtml. This is an internal macro.
393 . if \\n[www-html] \{\
394 . \" the following line makes the vertical mode leave, so to say
396 . nop \X^html-tag:\\$*^
399 .\" --------------------------------------------------------------------
402 .\" Emit a tag for grohtml (without a space). This is an internal macro.
406 . nop \X^html-tag:\\$*^\c
408 .\" --------------------------------------------------------------------
409 .\" PIMG [-R|-L|-C] filename [width] [height]
411 .\" Include a png image. It will work for -Tps and -Thtml.
412 .\" The default value for WIDTH and HEIGHT is zero; the default
413 .\" alignment is centering (-C).
415 .\" Note: This macro can only be used with the `-U' option of groff,
416 .\" activating unsafe mode, if not used with -Thtml; the PNG image
417 .\" is then converted to the EPS format using netpbm utilities.
420 . ie \\n[www-html] \{\
422 . HTML-TAG ".right-image"
425 . HTML-TAG ".left-image"
427 . HTML-TAG ".centered-image"
432 . nr www-width (\\$3 * 100 / 240)
434 . nr www-height (\\$4 * 100 / 240)
435 . ie (\\n[www-width] == 0) \{\
436 . ie (\\n[www-height] == 0) \
437 . HTML <img src="\\$2">
439 . HTML <img src="\\$1" height=\\n[www-height]>
442 . ie (\\n[www-height] == 0) \
443 . HTML <img src="\\$2" width=\\n[www-width]>
445 . HTML <img src="\\$2" width=\\n[www-width] height=\\n[www-height]>
450 . www-make-unique-name
451 . sy pngtopnm \\$2 | pnmcrop -white | @PNMTOPS_NOSETPAGE@ -noturn > \\*[www-unique-name].eps
453 . PSPIC \\*[www-unique-name].eps \\$3 \\$4
455 . PSPIC \\$1 \\*[www-unique-name].eps \\$3 \\$4
460 .\" --------------------------------------------------------------------
461 .\" auxiliary definitions for MPIMG
463 .nr www-left-ll-trap 0
464 .nr www-left-po-trap 0
465 .nr www-right-ll-trap 0
467 .de www-finish-left-po
468 . po -\\n[www-left-indent]u
469 . wh \\n[www-left-po-trap]u
470 . nr www-left-indent 0
473 .de www-finish-right-ll
474 . ll +\\n[www-right-indent]u
475 . \" now see whether we need to inline www-finish-left-ll
476 . if (\\n[www-left-ll-trap]u > 0) \
477 . if ((\\n[www-right-ll-trap]u + 1v) >= \\n[www-left-ll-trap]u) \{\
478 . mk www-left-po-trap
479 . nr www-left-po-trap +1v
480 . wh \\n[www-left-po-trap]u www-finish-left-po
481 . ll +\\n[www-left-indent]u
482 . wh \\n[www-left-ll-trap]u
483 . nr www-left-ll-trap 0
485 . \" and see whether we need to inline www-finish-left-po
486 . if (\\n[www-left-po-trap]u > 0) \
487 . if ((\\n[www-right-ll-trap]u + 1v) >= \\n[www-left-po-trap]u) \{\
488 . po -\\n[www-left-indent]u
489 . wh \\n[www-left-po-trap]u
490 . nr www-left-indent 0
492 . wh \\n[www-right-ll-trap]u
493 . nr www-right-ll-trap 0
496 .de www-finish-left-ll
497 . if (\\n[www-right-ll-trap] > 0) \
498 . if ((\\n[www-left-ll-trap] + 1v) >= \\n[www-right-ll-trap]) \{\
499 . ll +\\n[www-right-indent]u
500 . nr www-right-ll-trap 0
502 . mk www-left-po-trap
503 . nr www-left-po-trap +1v
504 . wh \\n[www-left-po-trap]u www-finish-left-po
505 . ll +\\n[www-left-indent]u
506 . wh \\n[www-left-ll-trap]u
507 . nr www-left-ll-trap 0
509 .\" --------------------------------------------------------------------
510 .\" MPIMG [-R|-L] filename [width] [height]
512 .\" Include a png image and wrap text around it. It will work for
513 .\" -Tps and -Thtml. The default value for WIDTH is 1i; default value
514 .\" for HEIGHT is WIDTH; the default alignment is left (-L).
516 .\" Note: This macro can only be used with the `-U' option of groff,
517 .\" activating unsafe mode, if not used with -Thtml; the PNG image
518 .\" is then converted to the EPS format using netpbm utilities.
524 . nr www-height \\n[www-width]
527 . nr www-width (\\n[www-width] * 100 / 240)
528 . nr www-height (\\n[www-height] * 100 / 240)
529 . ie \\n[www-html] \{\
531 . HTML <img src="\\$2" align=right width=\\n[www-width] height=\\n[www-height]>
533 . HTML <img src="\\$2" align=left width=\\n[www-width] height=\\n[www-height]>
537 . www-make-unique-name
538 . sy pngtopnm \\$2 | pnmcrop -white | @PNMTOPS_NOSETPAGE@ -noturn > \\*[www-unique-name].eps
540 . \" we must now disable a possible left image trap
542 . if (\\n[www-left-ll-trap] > 0) \
543 . wh \\n[www-left-ll-trap]u
544 . if (\\n[www-left-po-trap] > 0) \
545 . wh \\n[www-left-po-trap]u
546 . PSPIC -R \\*[www-unique-name].eps \\$3 \\$4
548 . nr www-right-indent \\n[ps-deswid]u
549 . ll -\\n[www-right-indent]u
550 . mk www-right-ll-trap
551 . nr www-right-ll-trap +(\\n[ps-desht]u - 1v)
552 . wh \\n[www-right-ll-trap]u www-finish-right-ll
553 . \" now restore possible left trap
554 . if (\\n[www-left-ll-trap] > 0) \
555 . wh \\n[www-left-ll-trap]u www-finish-left-ll
556 . if (\\n[www-left-po-trap] > 0) \
557 . wh \\n[www-left-po-trap]u
560 . \" we must now disable a possible right image trap
561 . if (\\n[www-right-ll-trap] > 0) \
562 . wh \\n[www-right-ll-trap]u
563 . PSPIC -L \\*[www-unique-name].eps \\$3 \\$4
565 . nr www-left-indent \\n[ps-deswid]u
566 . po +\\n[www-left-indent]u
567 . ll -\\n[www-left-indent]u
568 . mk www-left-ll-trap
569 . nr www-left-ll-trap +(\\n[ps-desht]u - 1v)
570 . wh \\n[www-left-ll-trap]u www-finish-left-ll
571 . \" now restore possible right trap
572 . if (\\n[www-right-ll-trap] > 0) \
573 . wh \\n[www-right-ll-trap]u www-finish-right-ll
578 .\" --------------------------------------------------------------------
581 .\" Begin heading. Heading level is N.
587 .\" If your heading contains URL, FTP, MTO macros you might wish to
588 .\" disable automatic links to headings. This can be done via `-P-l'
589 .\" from the command line or by using a cakk to `.HX 0'.
591 .nr www-heading-no -1
595 . nr www-heading-no 1
597 . nr www-heading-no \\$1
598 . HTML-TAG ".NH \\n[www-heading-no]"
602 . if (\\n[www-heading-no] == -1) \
603 . www-error "HnE found without a corresponding HnS"
606 .\" --------------------------------------------------------------------
609 .\" Emit the automatically collected links derived from
610 .\" section/numbered headings at this position.
615 .\" --------------------------------------------------------------------
618 .\" Produce a horizontal line
621 . ie \\n[www-html] \{\
628 .\" --------------------------------------------------------------------
631 .\" Suppresses the generation of the top and bottom rules which grohtml
632 .\" emits by default.
635 . HTML-TAG ".no-auto-rule"
638 .\" www-end-nowhere - end of input trap called to finish diversion.
643 .\" --------------------------------------------------------------------
646 .\" Generate an HTML title only. This differs from the -ms .TL macro
647 .\" which generates both an HTML title and a H1 heading.
649 .\" This is useful when an author wishes to use a HTML title as search
650 .\" engine fodder but a graphic title in the document.
652 .\" The macro terminates when a space or break is seen (.sp, .br).
655 . HTML-TAG ".html-tl"
656 . if !\\n[www-html] \{\
658 . it 2 www-end-nowhere
662 .\" --------------------------------------------------------------------
663 .\" auxiliary definitions for ULS / ULE
665 .ds www-level1 \[bu]\ \ \"
666 .ds www-level2 \[sq]\ \ \"
667 .ds www-level3 \[ci]\ \ \"
672 .\" Auxiliary macro for ULS.
676 . if (\\n[www-level] > 3) \
677 . www-error "too many levels of indentation (\\n[www-level])"
680 .\" Auxiliary macro for ULE.
683 . if !\\n[www-level] \
684 . www-error "trying to terminate a list which does not exist"
687 .\" --------------------------------------------------------------------
690 .\" Start an unordered list.
697 . if (\\n[www-level] == 1) \
698 . nr www-depth \\n[.i]
699 . nr www-depth +\w'\\*[www-level\\n[www-level]]'u
702 .\" --------------------------------------------------------------------
705 .\" End an unordered list.
711 . nr www-depth -\w'\\*[www-level\\n[www-level]]'u
716 .\" --------------------------------------------------------------------
719 .\" Insert a list item.
726 . ti -\w'\\*[www-level\\n[www-level]]'u
727 . nop \\*[www-level\\n[www-level]]\c
730 .\" --------------------------------------------------------------------
731 .\" DC l text [color]
733 .\" L is the letter to be dropped and enlarged.
735 .\" TEXT is the following text whose height the first letter should not
738 .\" COLOR is the optional color of the dropped letter (default black).
741 . ds www-dropcolor black
743 . ds www-dropcolor \\$3
744 . ie '\*(.T'html' \{\
745 . www-make-unique-name
746 . MPIMG -L \\*[www-unique-name].png "(\\n[.v] * 2u)"
750 . www-make-unique-name
751 . \" To avoid interferences with another DC macro call which is located
752 . \" very near to the current one, we draw the glyph on a separate page.
753 . \" Otherwise it could theoretically happen that the dropped capital
758 . nop \O[5i\\*[www-unique-name].png]\O[1]
759 . nop \m[\\*[www-dropcolor]]\s[40]\O[3]\\$1\O[4]
767 . nr dcht ((\\n[.v] + \\n[rst]) * \\n[.ps] / \\n[rst])
768 . char \[dcap] \m[\\*[www-dropcolor]]\s'\\n[dcht]u'\\$1
769 . nop \v'\\n[.v]u'\\[dcap]\v'-\\n[.v]u'\c
775 .\" --------------------------------------------------------------------
776 .\" Setup around HTML-IMAGE and friends
778 .\" now set up TS, TE, EQ, EN default macros
780 .do if !d TS .do ds TS HTML-IMAGE
781 .do if !d TE .do ds TE HTML-IMAGE-END
782 .do if !d EQ .do ds EQ HTML-IMAGE
783 .do if !d EN .do ds EN HTML-IMAGE-END
785 .\" supplementary macros used by other macro sets
787 .\" here are some tags specially for -Tps or -Thtml when invoked by
788 .\" pre-html to generate png images from postscript.
790 .\" --------------------------------------------------------------------
791 .\" HTML-DO-IMAGE - tells troff to issue an image marker which can be
792 .\" read back by pre-html
796 . nop \O[5\\$2\\$1.png]\O[1]\O[3]
798 . nop \O[5\\$2\\$1.png]\O[0]\O[3]
800 .\" --------------------------------------------------------------------
801 .\" HTML-IMAGE-END - terminates an image for html
805 . nop \O[4]\O[2]\O[0]
807 . nop \O[4]\O[2]\O[1]
812 .\" --------------------------------------------------------------------
813 .\" www-make-unique-name - generates another unique name in string
814 .\" `www-unique-name'
816 .de www-make-unique-name
818 . ds www-unique-name \\*[www-image-template]\\n[www-png-no]
820 .\" --------------------------------------------------------------------
821 .\" HTML-IMAGE and friends tell grohtml that this region of text needs
822 .\" to be rendered as an image.
825 . \" generates a centered image
826 . www-make-unique-name
827 . HTML-DO-IMAGE \\*[www-unique-name] c
831 . www-make-unique-name
832 . HTML-DO-IMAGE \\*[www-unique-name] r
836 . www-make-unique-name
837 . HTML-DO-IMAGE \\*[www-unique-name] l
840 .de HTML-IMAGE-INLINE
841 . www-make-unique-name
842 . HTML-DO-IMAGE \\*[www-unique-name] i
845 .\" --------------------------------------------------------------------
847 .\" --------------------------------------------------------------------
855 .\" start of some code
871 .if r ps4html .nop \O[0]
876 .\" --------------------------------------------------------------------
878 .\" --------------------------------------------------------------------