1 .TH GROFF_WWW @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
2 .\" Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
3 .\" Written by Gaius Mulley (gaius@glam.ac.uk)
5 .\" This file is part of groff.
7 .\" groff is free software; you can redistribute it and/or modify it under
8 .\" the terms of the GNU General Public License as published by the Free
9 .\" Software Foundation; either version 2, or (at your option) any later
12 .\" groff is distributed in the hope that it will be useful, but WITHOUT ANY
13 .\" WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
17 .\" You should have received a copy of the GNU General Public License along
18 .\" with groff; see the file COPYING. If not, write to the Free Software
19 .\" Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
21 .\" user level guide to using the -mwww macroset
24 .\" we need the .LINKS here as we use it in the middle as an example
25 .\" once the user requests .LINKS then the automatic generation of links
26 .\" at the top of the document is suppresed.
29 groff_www \- groff macros for authoring web pages
36 This manual page describes the GNU \-mwww macros, which is part of the
37 groff document formatting system.
38 The manual page is very a basic guide, and the html device driver
40 has been completely rewritten but still remains as in an alpha state.
41 It has been included into the distribution so that a lot of people have a
43 Note that this macro file will be automatically called (via the
44 \fCtroffrc\fP file) if you use \fC-Thtml\fP.
46 To see the hyperlinks in action, please format this man page with the
50 Here is a summary of the functions found in this macro set.
53 \&.HTMLINDEX determine automatic link cut off
55 point for sections/headers
57 \&.BODYCOLOR specify colours on a web page
59 \&.BACKGROUND specify background image
61 \&.URL create a url using two parameters
63 \&.MAILTO create a html email address
65 \&.FTP create an ftp reference
67 \&.IMAGE include an image file
69 \&.HTML pass an html raw request to the
73 \&.TAG generate an html name tag from $1
75 .\"\&.CDFTP optionally create two different links
77 .\" depending on hostname
79 \&.LINE create a full width horizontal rule
88 preprocessors is acceptable as input.
92 determines the cut off point for automatic link generation to headings.
93 By default all headings found in a troff document have links created to them
94 at the top of the html web page.
95 It maybe that many of the lower heading levels do not require links.
96 Alternatively some web pages may not need any heading links at all, in which
105 not to generate links.
106 An \fCHTMLINDEX\fP of 2 will mean that a heading
108 .B "1.1.1 Some Title"
110 will not be included in the links either as it is said to have a heading
112 Another method for switching automatic headings is via the command line
116 takes five parameters: foreground, background, active hypertext link,
117 hypertext link not yet visited, and visited hypertext link colour.
120 the only parameter to this macro is the background image file.
125 a URL using either two or three arguments.
126 $1 is the name of the link, $2 is the actual URL, and $3 is optional stuff
127 to be printed immediately after $2.
128 Hyphenation is disabled while printing the actual URL; explicit breakpoints
129 should be inserted with the
132 Here is how to encode
133 .URL "homepage for groff" http://\:groff.\:ffii.\:org/ :
136 \s-2\fC\&.URL "homepage for groff" http://\e:groff.\e:ffii.\e:org/ :\fP\s+2
139 If this is processed by a device other than \fC-Thtml\fP
141 homepage for groff \(lahttp://groff.\:ffii.\:org\(ra.
142 The URL macro can be of any type; for example we can reference
143 .URL "Eric Raymond's pic guide" pic.html
147 \s-2\fC\&.URL "Eric Raymond's pic guide" pic.html\fP\s+2
152 generates an email html reference.
153 The first argument is mandatory as the email address.
154 The optional second argument is the text you see in your browser, and
155 an optional third argument is stuff printed immediately after the
157 Hyphenation is disabled while printing the actual email address.
158 For example, the groff maintainers are
159 .MAILTO wl@gnu.org "Werner Lemberg"
161 .MAILTO Ted.Harding@nessie.mcc.ac.uk "Ted Harding" .
162 This is achieved by the following macros:
165 \s-2\fC\&.MAILTO wl@gnu.org "Werner Lemberg"
166 \&.MAILTO Ted.Harding@nessie.mcc.ac.uk "Ted Harding" .\s+2\fP
169 Note that all the urls actually are treated as consuming no textual space
171 This could be considered as a bug since it causes some problems.
172 To circumvent this, \fCwww.tmac\fP inserts a zero-width character which
173 expands to a harmless space (only if run with -Thtml).
176 indicates that data can be obtained via ftp.
177 The first argument is the browser text and the second is the url.
178 A third argument, similar to the macros above, is intended for stuff printed
179 immediately after the second argument.
180 The second and the third parameter are optional.
181 Hyphenation is disabled while printing the actual URL.
182 As an example, here the location of the
183 .FTP "current groff development distribution" \
184 ftp://ftp.ffii.org/\:pub/\:groff/\:devel/\:groff-current.tar.gz .
185 The macro example above was specified by:
188 \s-2\fC\&.FTP "current groff development distribution" \\
189 ftp://ftp.ffii.org/\e:pub/\e:groff/\e:devel/\e:groff-current.tar.gz .\fP\s+2
194 allows the document to include pictures.
195 The first argument is the image file.
196 The second optional argument gives the horizontal location;
198 puts the image to the left border,
201 Any other value centers the image.
202 The next two arguments are optional also:
203 Argument three is the width in pixels (default is 400 pixels if absent).
204 The fourth argument is the height in pixels (default is the width value if
209 suppresses generation of the top and bottom rules which grohtml emits
214 all text after this macro is treated as raw html.
215 If the document is processed \fIwithout\fP \fC-Thtml\fP then
216 the macro is ignored.
217 This macro is a building block for other higher level macros.
219 For example, the \fCBACKGROUND\fP macro is defined as:
222 \&. HTML <body background=\\$1>
228 generates an html name tag from its argument.
229 This can then be referenced using the
232 As you can see, you must precede the tag name with `\fC#\fP' since it is
234 This link was achieved via placing a TAG in the URL description above;
235 the source looks like this:
242 a URL using either two or three
244 $1 is the name of the link, $2 is the actual URL.\fP\s+2
249 generates a full width horizontal rule.
253 \fC\s-2\&.LINE\fP\s+2
259 requests that grohtml place the automatically generated links at this position.
263 SECTION HEADING LINKS
267 generates links to all section headings and places these at the top of the
270 for details of how to switch this off or alter the position.
272 LIMITATIONS OF GROHTML
274 Tbl information is currently rendered as a png image.
278 .BR groff (@MAN1EXT@),
279 .BR @g@troff (@MAN1EXT@)
280 .BR grohtml (@MAN1EXT@),
285 .MAILTO gaius@glam.ac.uk "Gaius Mulley"
288 .MAILTO bug-groff@gnu.org "Groff Bug Mailing List" .
289 Include a complete, self-contained example that will allow the bug to be
290 reproduced, and say which version of groff you are using.