| blob | ce20302434eb534978e04e187e310d5d3d7845f7 |
1 .TH GROFF_WWW @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
2 .\" Copyright (C) 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
3 .\" Written by Gaius Mulley (gaius@glam.ac.uk)
4 .\"
5 .\" This file is part of groff.
6 .\"
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
10 .\" version.
11 .\"
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
15 .\" for more details.
16 .\"
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.
20 .\"
21 .\" user level guide to using the -mwww macroset
22 .\"
23 .
24 .do nr groff_www_C \n[.C]
25 .cp 0
26 .
27 .do mso www.tmac
28 .
29 .\" we need the .LK here as we use it in the middle as an example --
30 .\" once the user requests .LK then the automatic generation of links
31 .\" at the top of the document is suppressed.
32 .LK
33 .
34 .
35 .SH NAME
36 groff_www \- groff macros for authoring web pages
37 .HR
38 .
39 .
40 .SH SYNOPSIS
41 .B "groff \-mwww"
42 [ options ]
43 file ...
44 .
45 .
46 .SH DESCRIPTION
47 This manual page describes the GNU \-mwww macro package, which is part of
48 the groff document formatting system.
49 The manual page is very a basic guide, and the html device driver
50 .RB ( \%grohtml )
51 has been completely rewritten but still remains as in an alpha state.
52 It has been included into the distribution so that a lot of people have a
53 chance to test it.
54 Note that this macro file will be automatically called (via the
55 .B troffrc
56 file) if you use
57 .BR \-Thtml .
58 .PP
59 To see the hyperlinks in action, please format this man page with the
60 .B \%grohtml
61 device.
62 .PP
63 Here is a summary of the functions found in this macro set.
64 .ta 2iL
65 .nf
66 \&.JOBNAME split output into multiple files
67 \&.HX automatic heading level cut off;
68 $1 point for sections/headers
69 \&.BCL specify colours on a web page
70 \&.BGIMG specify background image
71 \&.URL create a url using two parameters
72 \&.FTP create an ftp reference
73 \&.MTO create a html email address
74 \&.FTP create an ftp reference
75 \&.TAG generate an html name
76 \&.IMG include an image file
77 \&.PIMG include png image
78 \&.MPIMG place png on the margin and
79 wrap text around it
80 \&.HnS begin heading
81 \&.HnE end heading
82 \&.LK emit automatically collected links.
83 \&.HR produce a horizontal rule
84 \&.NHR suppress automatic generation of rules.
85 \&.HTL only generate HTML title
86 \&.HEAD add data to <head> block
87 \&.ULS unorder list begin
88 \&.ULE unorder list end
89 \&.LI insert a list item
90 \&.DC generate a drop capital
91 \&.HTML pass an html raw request to the
92 device driver
93 \&.CDS code example begin
94 \&.CDE code example end
95 .fi
96 .PP
97 Output of the
98 .BR pic ,
99 .BR eqn ,
100 .BR refer ,
101 and
102 .B tbl
103 preprocessors is acceptable as input.
104 .
105 .
106 .SH REQUESTS
107 .TP
108 .B .JOBNAME filename
109 Split output into multiple HTML files.
110 A file is split whenever a .SH or .NH\ 1 is encountered.
111 Its argument is the file stem name for future output files.
112 This option is equivalent to
113 .BR \%grohtml 's
114 .B \-j
115 option.
116 .TP
117 .B .HX n
118 Specify the cut off depth when generating links from section headings.
119 For example, a parameter of\~2 would cause
120 .B \%grohtml
121 to generate a list of links for
122 .B .NH\ 1
123 and
124 .B .NH\ 2
125 but not for
126 .BR .NH\ 3 .
127 Whereas
128 .RS
129 .IP
130 .nf
131 .B .HX 0
132 .fi
133 .RE
134 .IP
135 will tell
136 .B \%grohtml
137 that no heading links should be created at all.
138 Another method for turning automatic headings off is by issuing the
139 the command line switch
140 .B \-P\-l
141 to
142 .BR groff .
143 .
144 .TP
145 .B .BCL foreground background active not-visited visited
146 This macro takes five parameters: foreground, background, active hypertext
147 link, hypertext link not yet visited, and visited hypertext link colour.
148 .
149 .TP
150 .B .BGIMG imagefile
151 the only parameter to this macro is the background image file.
152 .
153 .TP
154 .B .URL url [description] [after]
155 generates
156 .TAG URL
157 a URL using either one, two or three arguments.
158 The first parameter is the actual URL, the second is the name of the link,
159 and the third is optional stuff to be printed immediately afterwards.
160 If
161 .B description
162 and
163 .B after
164 are absent then the
165 .B url
166 becomes the anchor text.
167 Hyphenation is disabled while printing the actual URL;
168 explicit breakpoints
169 should be inserted with the
170 .B \[rs]:
171 escape.
172 Here is how to encode
173 .URL http://\:foo.\:org/ "foo" :
174 .RS
175 .IP
176 .B .URL http://\[rs]:foo.\[rs]:org/ "foo" :
177 .RE
178 .IP
179 If this is processed by a device other than
180 .B \-Thtml
181 it appears as:
182 .RS
183 .IP
184 \m[blue]foo\m[] \[la]\f[C]http://foo.org\f[]\[ra]:
185 .RE
186 .IP
187 The URL macro can be of any type; for example we can reference
188 .URL pic.html "Eric Raymond's pic guide"
189 by:
190 .RS
191 .IP
192 .B .URL pic.html \[dq]Eric Raymond's pic guide\[dq]
193 .RE
194 .
195 .TP
196 .B .MTO address [description] [after]
197 Generate an email html reference.
198 The first argument is mandatory as the email address.
199 The optional second argument is the text you see in your browser
200 If an empty argument is given,
201 .B address
202 is used instead.
203 An optional third argument is stuff printed immediately afterwards.
204 Hyphenation is disabled while printing the actual email address.
205 For example,
206 .MTO joe@user.org "Joe User"
207 was achieved by the following macro:
208 .RS
209 .IP
210 .B .MTO joe@user.org \[dq]Joe User\[dq]
211 .RE
212 .IP
213 Note that all the URLs actually are treated as consuming no textual space
214 in groff.
215 This could be considered as a bug since it causes some problems.
216 To circumvent this,
217 .B www.tmac
218 inserts a zero-width character which expands to a harmless space (only if
219 run with
220 .BR \-Thtml ).
221 .
222 .TP
223 .B .FTP url [description] [after]
224 indicates that data can be obtained via ftp.
225 The first argument is the url and the second is the browser text.
226 A third argument, similar to the macros above, is intended for stuff printed
227 immediately afterwards.
228 The second and the third parameter are optional.
229 Hyphenation is disabled while printing the actual URL.
230 As an example, here the location of the
231 .FTP ftp://\:ftp.gnu.org/ "GNU ftp server" .
232 The macro example above was specified by:
233 .RS
234 .IP
235 .B .FTP ftp://\[rs]:ftp.gnu.org/ \[dq]GNU ftp server\[dq] .
236 .RE
237 .
238 .TP
239 .B .TAG name
240 Generates an html name tag from its argument.
241 This can then be referenced using the
242 .URL #URL URL
243 macro.
244 As you can see, you must precede the tag name with
245 .B #
246 since it is a local reference.
247 This link was achieved via placing a TAG in the URL description above;
248 the source looks like this:
249 .RS
250 .IP
251 .nf
252 .ft B
253 \&.TP
254 \&.B URL
255 generates
256 \&.TAG URL
257 a URL using either two or three arguments.
258 \&.\|.\|.
259 .fi
260 .ft P
261 .RE
262 .
263 .TP
264 .B .IMG [-R|-L|-C] filename [width] [height]
265 Include a picture into the document.
266 The first argument is the horizontal location: right, left, or center
267 .RB ( \-R ,
268 .BR \-L ,
269 or
270 .BR \-C ).
271 Alignment is centered by default (-C).
272 The second argument is the filename.
273 The optional third and fourth arguments are the width and height.
274 If the width is absent it defaults to 1\~inch.
275 If the height is absent it defaults to the width.
276 This maps onto an html img tag.
277 If you are including a png image then it is advisable to use the
278 .B PIMG
279 macro.
280 .
281 .TP
282 .B .PIMG [-R|-L|-C] filename [width [height]]
283 Include an image in PNG format.
284 This macro takes exactly the same parameters as the
285 .B IMG
286 macro; it has the advantage of working with postscript and html devices
287 also since it can automatically convert the image into the EPS format,
288 using the following programs
289 of the
290 .B netpbm
291 package:
292 .BR pngtopnm ,
293 .BR pnmcrop ,
294 and
295 .BR pnmtops .
296 If the document isn't processed with
297 .B \-Thtml
298 it is necessary to use the
299 .B \-U
300 option of groff.
301 .
302 .TP
303 .B .MPIMG [-R|-L] [-G gap] filename [width [height]]
304 Place a PNG image on the margin and wrap text around it.
305 The first parameters are optional.
306 The alignment: left or right
307 .RB ( \-L
308 or
309 .BR \-R )
310 specifies the margin where the picture is placed at.
311 The default alignment is left
312 .RB ( -L ).
313 Optionally,
314 .BI \-G \~gap
315 can be used to arrange a gap between the picture
316 and the text that wraps around it.
317 The default gap width is zero.
318 .br
319 The first non-optional argument is the filename.
320 The optional following arguments are the width and height.
321 If the width is absent it defaults to 1\~inch.
322 If the height is absent it defaults to the width.
323 Example:
324 .RS
325 .IP
326 .nf
327 .ft B
328 \&.MPIMG -L -G 2c foo.png 3c 1.5c
329 .ft P
330 .fi
331 .RE
332 .
333 .TP
334 .B .HnS n
335 Begin heading.
336 The numeric heading level
337 .I n
338 is specified by the first parameter.
339 Use this macro if your headings contain URL, FTP or MTO macros.
340 Example:
341 .RS
342 .IP
343 .nf
344 .ft B
345 \&.HnS 1
346 \&.HR
347 GNU Troff
348 \&.URL http://groff.ffii.org (Groff)
349 \&\(em a
350 \&.URL http://www.gnu.org/ GNU
351 \&project.
352 \&Hosted by
353 \&.URL http://ffii.org/ FFII .
354 \&.HR
355 \&.HnE
356 .ft P
357 .fi
358 .RE
359 .IP
360 In this case you might wish to
361 disable automatic links to headings.
362 This can be done via
363 .B \-P\-l
364 from the command line.
365 .\" or by using a call to `.HX 0'.
367 .
368 .TP
369 .B .HnE
370 End heading.
371 .
372 .TP
373 .B .LK
374 .TAG LK
375 Force \%grohtml to place the automatically generated links at this position.
376 If this manual page has been processed with
377 .B \-Thtml
378 those links can be seen right here.
379 .
380 .LK
381 .
382 .TP
383 .B .HR
384 Generate a full-width horizontal rule for
385 .BR \-Thtml .
386 No effect for all other devices.
387 .
388 .TP
389 .B .NHR
390 Suppress generation of the top and bottom rules which \%grohtml emits
391 by default.
392 .
393 .TP
394 .B .HTL
395 Generate an HTML title only.
396 This differs from the
397 .B TL
398 macro of the
399 .B ms
400 macro package which generates both an HTML title and an <H1> heading.
401 Use it to provide an HTML title as search engine fodder but a graphic title
402 in the document.
403 The macro terminates when a space or break is seen (.sp, .br).
404 .
405 .TP
406 .B .HEAD
407 Add arbitrary HTML data to the <head> block.
408 Ignored if not processed with
409 .BR \-Thtml .
410 Example:
411 .RS
412 .IP
413 .nf
414 .B ".HEAD" "\[dq]<link \[rs]"
415 .B " rel=\[dq]\[dq]icon\[dq]\[dq] \[rs]"
416 .B " type=\[dq]\[dq]image/png\[dq]\[dq] \[rs]"
417 .B " href=\[dq]\[dq]http://foo.org//bar.png\[dq]\[dq]/>\[dq]"
418 .fi
419 .ft P
420 .RE
421 .
422 .TP
423 .B .HTML
424 All text after this macro is treated as raw html.
425 If the document is processed without
426 .B \-Thtml
427 then the macro is ignored.
428 Internally, this macro is used as a building block for other higher-level
429 macros.
430 .IP
431 For example, the
432 .B BGIMG
433 macro is defined as
434 .RS
435 .IP
436 .nf
437 .ft B
438 \&.de BGIMG
439 \&. HTML <body background=\[rs]$1>
440 \&..
441 .ft P
442 .fi
443 .RE
444 .
445 .TP
446 .B .DC l text [color]
447 Produce a drop capital.
448 The first parameter is the letter to be dropped and enlarged, the second
449 parameter
450 .B text
451 is the ajoining text whose height the first letter should not exceed.
452 The optional third parameter is the color of the dropped letter.
453 It defaults to black.
454 .
455 .TP
456 .B ".CDS"
457 Start displaying a code section in constant width font.
458 .
459 .TP
460 .B ".CDE"
461 End code display
462 .
463 .SH SECTION HEADING LINKS
464 By default
465 .B \%grohtml
466 generates links to all section headings and places these at the top of the
467 html document. (See
468 .URL #LK LINKS
469 for details of how to switch this off or alter the position).
470 .
471 .
472 .SH LIMITATIONS OF GROHTML
473 .LP
474 .B tbl
475 information is currently rendered as a PNG image.
476 .
477 .
478 .SH FILES
479 @MACRODIR@/www.tmac
480 .
481 .
482 .SH "SEE ALSO"
483 .BR groff (@MAN1EXT@),
484 .BR @g@troff (@MAN1EXT@)
485 .BR \%grohtml (@MAN1EXT@),
486 .BR netpbm (1)
487 .
488 .
489 .SH AUTHOR
490 .B \%grohtml
491 was written by
492 .MTO gaius@glam.ac.uk "Gaius Mulley"
493 .
494 .
495 .SH BUGS
496 Report bugs to the
497 .MTO bug-groff@\:gnu.org "Groff Bug Mailing List" .
498 Include a complete, self-contained example that will allow the bug to be
499 reproduced, and say which version of groff you are using.
500 .
501 .cp \n[groff_www_C]
502 .
503 .\" Local Variables:
504 .\" mode: nroff
505 .\" End: