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 .do mso www.tmac
  24 .\" we need the .LINKS here as we use it in the middle as an example
  25 .\" once the user requests .LINKS then the automatic generation of links
  26 .\" at the top of the document is suppresed.
  27 .LINKS
  28 .SH NAME
  29 groff_www \- groff macros for authoring web pages
  30 .LINE
  31 .SH SYNOPSIS
  32 .B "groff \-mwww"
  33 [ options ]
  34 file ...
  35 .SH DESCRIPTION
  36 This manual page describes the GNU \-mwww macros, which is part of the
  37 groff document formatting system.
  38 The manual page is very a basic guide, and the html device driver
  39 .RB ( grohtml )
  40 has been completely rewritten but still remains as in an alpha state.
  41 It has been included into the distribution so that a lot of people have a
  42 chance to test it.
  43 Note that this macro file will be automatically called (via the
  44 \fCtroffrc\fP file) if you use \fC-Thtml\fP.
  45 .PP
  46 To see the hyperlinks in action, please format this man page with the
  47 .B grohtml
  48 device.
  49 .PP
  50 Here is a summary of the functions found in this macro set.
  51 .SH SYNPOSIS
  52 .ta 2iL
  53 \&.HTMLINDEX    determine automatic link cut off
  54 .br
  55         point for sections/headers
  56 .br
  57 \&.BODYCOLOR    specify colours on a web page
  58 .br
  59 \&.BACKGROUND   specify background image
  60 .br
  61 \&.URL  create a url using two parameters
  62 .br
  63 \&.MAILTO       create a html email address
  64 .br
  65 \&.FTP  create an ftp reference
  66 .br
  67 \&.IMAGE        include an image file
  68 .br
  69 \&.HTML pass an html raw request to the
  70 .br
  71         device driver
  72 .br
  73 \&.TAG  generate an html name tag from $1
  74 .br
  75 .\"\&.CDFTP     optionally create two different links
  76 .\".br
  77 .\"     depending on hostname
  78 .\".br
  79 \&.LINE create a full width horizontal rule
  80 .br
  81 .PP
  82 Output of the
  83 .IR pic ,
  84 .IR eqn ,
  85 .IR refer ,
  86 and
  87 .I tbl
  88 preprocessors is acceptable as input.
  89 .SH REQUESTS
  90 .TP
  91 .B HTMLINDEX
  92 determines the cut off point for automatic link generation to headings.
  93 By default all headings found in a troff document have links created to them
  94 at the top of the html web page.
  95 It maybe that many of the lower heading levels do not require links.
  96 Alternatively some web pages may not need any heading links at all, in which
  97 case:
  98 .sp
  99 .nf
 100 \fC\&.HTMLINDEX 0\fP
 101 .fi
 102 .sp
 103 will tell
 104 .B grohtml
 105 not to generate links.
 106 An \fCHTMLINDEX\fP of 2 will mean that a heading
 107 .sp
 108 .B "1.1.1 Some Title"
 109 .sp
 110 will not be included in the links either as it is said to have a heading
 111 level of three.
 112 Another method for switching automatic headings is via the command line
 113 switch \fC-P-l\fP.
 114 .TP
 115 .B BODYCOLOR
 116 takes five parameters: foreground, background, active hypertext link,
 117 hypertext link not yet visited, and visited hypertext link colour.
 118 .TP
 119 .B BACKGROUND
 120 the only parameter to this macro is the background image file.
 121 .TP
 122 .B URL
 123 generates
 124 .TAG URL
 125 a URL using either two or three arguments.
 126 $1 is the name of the link, $2 is the actual URL, and $3 is optional stuff
 127 to be printed immediately after $2.
 128 Hyphenation is disabled while printing the actual URL; explicit breakpoints
 129 should be inserted with the
 130 .B \e:
 131 escape.
 132 Here is how to encode
 133 .URL "homepage for groff" http://\:groff.\:ffii.\:org/ :
 134 .sp
 135 .nf
 136 \s-2\fC\&.URL "homepage for groff" http://\e:groff.\e:ffii.\e:org/ :\fP\s+2
 137 .fi
 138 .sp
 139 If this is processed by a device other than \fC-Thtml\fP
 140 it appears as:
 141 homepage for groff \(lahttp://groff.\:ffii.\:org\(ra.
 142 The URL macro can be of any type; for example we can reference
 143 .URL "Eric Raymond's pic guide" pic.html
 144 by:
 145 .sp
 146 .nf
 147 \s-2\fC\&.URL "Eric Raymond's pic guide" pic.html\fP\s+2
 148 .fi
 149 .sp
 150 .TP
 151 .B MAILTO
 152 generates an email html reference.
 153 The first argument is mandatory as the email address.
 154 The optional second argument is the text you see in your browser, and
 155 an optional third argument is stuff printed immediately after the
 156 second argument.
 157 Hyphenation is disabled while printing the actual email address.
 158 For example, the groff maintainers are
 159 .MAILTO wl@gnu.org "Werner Lemberg"
 160 and
 161 .MAILTO Ted.Harding@nessie.mcc.ac.uk "Ted Harding" .
 162 This is achieved by the following macros:
 163 .sp
 164 .nf
 165 \s-2\fC\&.MAILTO wl@gnu.org "Werner Lemberg"
 166 \&.MAILTO Ted.Harding@nessie.mcc.ac.uk "Ted Harding" .\s+2\fP
 167 .fi
 168 .sp
 169 Note that all the urls actually are treated as consuming no textual space
 170 in groff.
 171 This could be considered as a bug since it causes some problems.
 172 To circumvent this, \fCwww.tmac\fP inserts a zero-width character which
 173 expands to a harmless space (only if run with -Thtml).
 174 .TP
 175 .B FTP
 176 indicates that data can be obtained via ftp.
 177 The first argument is the browser text and the second is the url.
 178 A third argument, similar to the macros above, is intended for stuff printed
 179 immediately after the second argument.
 180 The second and the third parameter are optional.
 181 Hyphenation is disabled while printing the actual URL.
 182 As an example, here the location of the
 183 .FTP "current groff development distribution" \
 184 ftp://ftp.ffii.org/\:pub/\:groff/\:devel/\:groff-current.tar.gz .
 185 The macro example above was specified by:
 186 .sp
 187 .nf
 188 \s-2\fC\&.FTP "current groff development distribution" \\
 189 ftp://ftp.ffii.org/\e:pub/\e:groff/\e:devel/\e:groff-current.tar.gz .\fP\s+2
 190 .fi
 191 .sp
 192 .TP
 193 .B IMAGE
 194 allows the document to include pictures.
 195 The first argument is the image file.
 196 The second optional argument gives the horizontal location;
 197 .B l
 198 puts the image to the left border,
 199 .B r
 200 to the right.
 201 Any other value centers the image.
 202 The next two arguments are optional also:
 203 Argument three is the width in pixels (default is 400 pixels if absent).
 204 The fourth argument is the height in pixels (default is the width value if
 205 absent).
 206 .sp
 207 .TP
 208 .B NO-AUTO-RULE
 209 suppresses generation of the top and bottom rules which grohtml emits
 210 by default.
 211 .sp
 212 .TP
 213 .B HTML
 214 all text after this macro is treated as raw html.
 215 If the document is processed \fIwithout\fP \fC-Thtml\fP then
 216 the macro is ignored.
 217 This macro is a building block for other higher level macros.
 218 .sp
 219 For example, the \fCBACKGROUND\fP macro is defined as:
 220 .nf
 221 \fC\&.de BACKGROUND
 222 \&.   HTML <body background=\\$1>
 223 \&..
 224 \fP
 225 .fi
 226 .TP
 227 .B TAG
 228 generates an html name tag from its argument.
 229 This can then be referenced using the
 230 .URL URL #URL
 231 macro.
 232 As you can see, you must precede the tag name with `\fC#\fP' since it is
 233 a local reference.
 234 This link was achieved via placing a TAG in the URL description above;
 235 the source looks like this:
 236 .sp
 237 .nf
 238 \s-2\fC\&.TP
 239 \&.B URL
 240 generates
 241 \&.TAG URL
 242 a URL using either two or three
 243 arguments.
 244 $1 is the name of the link, $2 is the actual URL.\fP\s+2
 245 .fi
 246 .sp
 247 .TP
 248 .B LINE
 249 generates a full width horizontal rule.
 250 Example:
 251 .sp
 252 .nf
 253 \fC\s-2\&.LINE\fP\s+2
 254 .fi
 255 .sp
 256 .TP
 257 .B LINKS
 258 .TAG LINK
 259 requests that grohtml place the automatically generated links at this position.
 260 For example:
 261 .LINKS
 262 .SH
 263 SECTION HEADING LINKS
 264 .LP
 265 By default
 266 .B grohtml
 267 generates links to all section headings and places these at the top of the
 268 html document. (See
 269 .URL LINKS #LINK
 270 for details of how to switch this off or alter the position.
 271 .SH
 272 LIMITATIONS OF GROHTML
 273 .LP
 274 Tbl information is currently rendered as a png image.
 275 .SH FILES
 276 @MACRODIR@/www.tmac
 277 .SH "SEE ALSO"
 278 .BR groff (@MAN1EXT@),
 279 .BR @g@troff (@MAN1EXT@)
 280 .BR grohtml (@MAN1EXT@),
 281 .LP
 282 .SH AUTHOR
 283 .B Grohtml
 284 was written by
 285 .MAILTO gaius@glam.ac.uk "Gaius Mulley"
 286 .SH BUGS
 287 Report bugs to the
 288 .MAILTO bug-groff@gnu.org "Groff Bug Mailing List" .
 289 Include a complete, self-contained example that will allow the bug to be
 290 reproduced, and say which version of groff you are using.
 291 .
 292 .\" Local Variables:
 293 .\" mode: nroff
 294 .\" End: