groff_markup - groff macros for authoring web pages
groff -markup [ options ] file ...
This manual page describes the GNU -markup macros, which
is part of the groff document formatting system. The manual
page is very a basic guide, and the html device driver
(grohtml) is still very alpha. It has been included into
the distribution 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.
.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.
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 HTMLINDEX
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.
BODYCOLOR [Toc] [Back]
takes five parameters: foreground, background,
active hypertext link, hypertext link not yet visited,
and visited hypertext link colour.
BACKGROUND [Toc] [Back]
the only parameter to this macro is the background
image file.
URL generates a URL using either two or three arguments.
$1 is the name of the link, $2 is the
actual URL, and $3 is optional stuff to be printed
immediately after $2. Here is how to encode
.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 by:
.URL "Eric Raymond's pic guide" pic.html
MAILTO generates an email html reference. The first argument
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 argument.
For example, the groff maintainers are and
This is achieved by the following macros:
.MAILTO [email protected] "Werner Lemberg"
.MAILTO [email protected] \
"Ted Harding" .
Note that all the urls actually are treated as consuming
no textual space in groff. This could be
considered as a bug since it causes some problems.
To circumvent this, tmac.arkup inserts a zero-width
character which expands to a harmless space (only
if in HTML mode)
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 immediately
after the second argument. The second and
the third parameter are optional. As an example,
here the location of the The macro example above
was specified by:
.FTP "current groff development distribution" \
ftp://ftp.ffii.org/pub/groff/devel/groff-cur-
rent.tar.gz .
IMAGE allows the document to include pictures. The first
argument is the image file. The next two arguments
are optional: Argument two is the width in pixels
(default is 400 pixels if absent). The third 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 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
etc.
LINE generates a full width horizontal rule. Example:
.LINE
SECTION HEADING LINKS [Toc] [Back] By default grohtml generates links to all section headings
and places these at the top of the html document. Grohtml
has to guess what a section heading looks like -- remember
that all grohtml actually sees is a device independent
language telling it where to place text, draw lines,
change font sizes and faces etc. It believes a section
heading to be a line of bold text which starts at the left
most margin. Consequently it may misinterpret. Users can
turn off all heading and title guessing by giving invoking
groff with groff -P-g.
LIMITATIONS OF GROHTML [Toc] [Back] Although basic text can be translated in a straightforward
fashion there are some areas where grohtml has to try and
guess text relationship. In particular, whenever grohtml
encounters text tables and indented paragraphs or two column
mode it will try and utilize the html table construct
to preserve columns. Grohtml also attempts to work out
which lines should be automatically formatted by the
browser. Ultimately in trying to make reasonable guesses
most of the time it will make mistakes. Hopefully these
mistakes will happen less and less as we get bug reports
and patches :-).
Tbl, pic, eqn's are also generated using images which may
be considered a limitation.
/usr/share/tmac/tmac.arkup
groff(1), troff(1) grohtml(1),
Grohtml is written by
Report bugs to the 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.16.1 April 8, 2001 GROFF_MARKUP(7)
[ Back ] | 