GROFF_MWWW(7)GROFF_MWWW(7)NAMEgroff_mwww - groff macros for authoring web pages
SYNOPSIS
groff -mwww [ options ] file ...
DESCRIPTION
This manual page describes the GNU -mwww macros, which is
part of the groff document formatting system. The manual
page is very a basic guide, and the html device driver
(grohtml) has been completely rewritten but still remains
as in an alpha state. It has been included into the dis
tribution so that a lot of people have a chance to test
it. Note that this macro file will be automatically
called (via the troffrc file) if you use -Thtml.
To see the hyperlinks in action, please format this man
page with the grohtml device.
Here is a summary of the functions found in this macro
set.
SYNPOSIS
.HTMLINDEX determine automatic link cut off
point for sections/headers
.BODYCOLOR specify colours on a web page
.BACKGROUND specify background image
.URL create a url using two parameters
.MAILTO create a html email address
.FTP create an ftp reference
.IMAGE include an image file
.HTML pass an html raw request to the
device driver
.TAG generate an html name tag from $1
.LINE create a full width horizontal rule
Output of the pic, eqn, refer, and tbl preprocessors is
acceptable as input.
REQUESTS
HTMLINDEX
determines the cut off point for automatic link
generation to headings. By default all headings
found in a troff document have links created to
them at the top of the html web page. It maybe
that many of the lower heading levels do not
require links. Alternatively some web pages may
not need any heading links at all, in which case:
.HTMLINDEX 0
will tell grohtml not to generate links. An HTM
LINDEX of 2 will mean that a heading
1.1.1 Some Title
will not be included in the links either as it is
said to have a heading level of three. Another
method for switching automatic headings is via the
command line switch -P-l.
BODYCOLOR
takes five parameters: foreground, background,
active hypertext link, hypertext link not yet vis
ited, and visited hypertext link colour.
BACKGROUND
the only parameter to this macro is the background
image file.
URL generates a URL using either two or three argu
ments. $1 is the name of the link, $2 is the
actual URL, and $3 is optional stuff to be printed
immediately after $2. Hyphenation is disabled
while printing the actual URL; explicit breakpoints
should be inserted with the \: escape. Here is how
to encode homepage for groff <http://groff.ffii.
org/>:
.URL "homepage for groff" http://\:groff.\:ffii.\:org/ :
If this is processed by a device other than -Thtml
it appears as: homepage for groff <http://groff.
ffii.org>. The URL macro can be of any type; for
example we can reference Eric Raymond's pic guide
<pic.html> by:
.URL "Eric Raymond's pic guide" pic.html
MAILTO generates an email html reference. The first argu
ment is mandatory as the email address. The
optional second argument is the text you see in
your browser, and an optional third argument is
stuff printed immediately after the second argu
ment. Hyphenation is disabled while printing the
actual email address. For example, the groff main
tainers are Werner Lemberg <wl@gnu.org> and Ted
Harding <Ted.Harding@nessie.mcc.ac.uk>. This is
achieved by the following macros:
.MAILTO wl@gnu.org "Werner Lemberg"
.MAILTO Ted.Harding@nessie.mcc.ac.uk "Ted Harding" .
Note that all the urls actually are treated as con
suming no textual space in groff. This could be
considered as a bug since it causes some problems.
To circumvent this, www.tmac inserts a zero-width
character which expands to a harmless space (only
if run with -Thtml).
FTP indicates that data can be obtained via ftp. The
first argument is the browser text and the second
is the url. A third argument, similar to the
macros above, is intended for stuff printed immedi
ately after the second argument. The second and
the third parameter are optional. Hyphenation is
disabled while printing the actual URL. As an
example, here the location of the current groff
development distribution <ftp://ftp.ffii.org/pub/
groff/devel/groff-current.tar.gz>. The macro exam
ple above was specified by:
.FTP "current groff development distribution" \
ftp://ftp.ffii.org/\:pub/\:groff/\:devel/\:groff-current.tar.gz .
IMAGE allows the document to include pictures. The first
argument is the image file. The second optional
argument gives the horizontal location; l puts the
image to the left border, r to the right. Any
other value centers the image. The next two argu
ments are optional also: Argument three is the
width in pixels (default is 400 pixels if absent).
The fourth argument is the height in pixels
(default is the width value if absent).
HTML all text after this macro is treated as raw html.
If the document is processed without -Thtml then
the macro is ignored. This macro is a building
block for other higher level macros.
For example, the BACKGROUND macro is defined as:
.de BACKGROUND
. HTML <body background=\$1>
..
TAG generates an html name tag from its argument. This
can then be referenced using the URL <#URL> macro.
As you can see, you must precede the tag name with
`#' since it is a local reference. This link was
achieved via placing a TAG in the URL description
above; the source looks like this:
.TP
.B URL
generates
.TAG URL
a URL using either two or three
arguments.
$1 is the name of the link, $2 is the actual URL.
LINE generates a full width horizontal rule. Example:
.LINE
LINKS requests that grohtml place the automatically gen
erated links at this position. For example:
SECTION HEADING LINKS
By default grohtml generates links to all section headings
and places these at the top of the html document. (See
LINKS <#LINK> for details of how to switch this off or
alter the position.
LIMITATIONS OF GROHTML
Tbl information is currently rendered as a png image.
FILES
/usr/freeware/share/groff/1.17.2/tmac/mwww.tmac (a wrapper
for www.tmac)
/usr/freeware/share/groff/1.17.2/tmac/www.tmac
SEE ALSOgroff(1), troff(1)grohtml(1),
AUTHOR
Grohtml was written by Gaius Mulley <gaius@glam.ac.uk>
BUGS
Report bugs to the Groff Bug Mailing List
<bug-groff@gnu.org>. Include a complete, self-contained
example that will allow the bug to be reproduced, and say
which version of groff you are using.
Groff Version 1.17.2 3 July 2001 GROFF_MWWW(7)