contrib/groff/tmac/groff_www.man

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