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