tmac/groff_www.man

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