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