322 lines
9.2 KiB
Groff
322 lines
9.2 KiB
Groff
.\" $NetBSD: groff_markup.7,v 1.2 2003/01/03 04:02:10 jschauma Exp $
|
|
.\"
|
|
.TH GROFF_MARKUP 7 "April 8, 2001" "Groff Version 1.16.1"
|
|
.\" Copyright (C) 2000 Free Software Foundation, Inc.
|
|
.\" Written by Gaius Mulley (gaius@glam.ac.uk)
|
|
.\"
|
|
.\" This file is part of groff.
|
|
.\"
|
|
.\" groff is free software; you can redistribute it and/or modify it under
|
|
.\" the terms of the GNU General Public License as published by the Free
|
|
.\" Software Foundation; either version 2, or (at your option) any later
|
|
.\" version.
|
|
.\"
|
|
.\" groff is distributed in the hope that it will be useful, but WITHOUT ANY
|
|
.\" WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
.\" for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public License along
|
|
.\" with groff; see the file COPYING. If not, write to the Free Software
|
|
.\" Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
|
|
.\"
|
|
.\" user level guide to using the -markup macroset
|
|
.\"
|
|
.do mso tmac.arkup
|
|
.LINE
|
|
.SH NAME
|
|
groff_markup \- groff macros for authoring web pages
|
|
.LINE
|
|
.SH SYNOPSIS
|
|
.B "groff \-markup"
|
|
[ options ]
|
|
file ...
|
|
.SH DESCRIPTION
|
|
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
|
|
.RB ( 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
|
|
\fCtroffrc\fP file) if you use \fC-Thtml\fP.
|
|
.PP
|
|
To see the hyperlinks in action, please format this man page with the
|
|
.B grohtml
|
|
device.
|
|
.PP
|
|
Here is a summary of the functions found in this macro set.
|
|
.SH SYNOPSIS
|
|
.ta 2iL
|
|
\&.HTMLINDEX determine automatic link cut off
|
|
.br
|
|
point for sections/headers
|
|
.br
|
|
\&.BODYCOLOR specify colours on a web page
|
|
.br
|
|
\&.BACKGROUND specify background image
|
|
.br
|
|
\&.URL create a url using two parameters
|
|
.br
|
|
\&.MAILTO create a html email address
|
|
.br
|
|
\&.FTP create an ftp reference
|
|
.br
|
|
\&.IMAGE include an image file
|
|
.br
|
|
\&.HTML pass an html raw request to the
|
|
.br
|
|
device driver
|
|
.br
|
|
\&.TAG generate an html name tag from $1
|
|
.br
|
|
.\"\&.CDFTP optionally create two different links
|
|
.\".br
|
|
.\" depending on hostname
|
|
.\".br
|
|
\&.LINE create a full width horizontal rule
|
|
.br
|
|
.PP
|
|
Output of the
|
|
.IR pic ,
|
|
.IR eqn ,
|
|
.IR refer ,
|
|
and
|
|
.I tbl
|
|
preprocessors is acceptable as input.
|
|
.SH REQUESTS
|
|
.TP
|
|
.B 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:
|
|
.sp
|
|
.nf
|
|
\fC\&.HTMLINDEX 0\fP
|
|
.fi
|
|
.sp
|
|
will tell
|
|
.B grohtml
|
|
not to generate links.
|
|
An \fCHTMLINDEX\fP of 2 will mean that a heading
|
|
.sp
|
|
.B "1.1.1 Some Title"
|
|
.sp
|
|
will not be included in the links either as it is said to have a heading
|
|
level of three.
|
|
.TP
|
|
.B BODYCOLOR
|
|
takes five parameters: foreground, background, active hypertext link,
|
|
hypertext link not yet visited, and visited hypertext link colour.
|
|
.TP
|
|
.B BACKGROUND
|
|
the only parameter to this macro is the background image file.
|
|
.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, and $3 is optional stuff
|
|
to be printed immediately after $2.
|
|
Here is how to encode
|
|
.URL "homepage for groff" http://groff.ffii.org/ :
|
|
.sp
|
|
.nf
|
|
\s-2\fC\&.URL "homepage for groff" http://groff.ffii.org/ :\fP\s+2
|
|
.fi
|
|
.sp
|
|
If this is processed by a device other than \fC-Thtml\fP
|
|
it appears as:
|
|
homepage for groff \(lahttp://groff.ffii.org\(ra.
|
|
The URL macro can be of any type; for example we can reference
|
|
.URL "Eric Raymond's pic guide" pic.html
|
|
by:
|
|
.sp
|
|
.nf
|
|
\s-2\fC\&.URL "Eric Raymond's pic guide" pic.html\fP\s+2
|
|
.fi
|
|
.sp
|
|
.TP
|
|
.B 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
|
|
.MAILTO wl@gnu.org "Werner Lemberg"
|
|
and
|
|
.MAILTO Ted.Harding@nessie.mcc.ac.uk "Ted Harding" .
|
|
This is achieved by the following macros:
|
|
.sp
|
|
.nf
|
|
\s-2\fC\&.MAILTO wl@gnu.org "Werner Lemberg"\fP
|
|
.sp
|
|
\fC\&.MAILTO Ted.Harding@nessie.mcc.ac.uk \\
|
|
.br
|
|
"Ted Harding" .\s+2\fP
|
|
.fi
|
|
.sp
|
|
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, \fCtmac.arkup\fP inserts a zero-width character which
|
|
expands to a harmless space (only if in HTML mode)
|
|
.TP
|
|
.B 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
|
|
.FTP "current groff development distribution" \
|
|
ftp://ftp.ffii.org/pub/groff/devel/groff-current.tar.gz .
|
|
The macro example above was specified by:
|
|
.sp
|
|
\s-2\fC\&.FTP "current groff development distribution" \\
|
|
.br
|
|
ftp://ftp.ffii.org/pub/groff/devel/groff-current.tar.gz .\fP\s+2
|
|
.sp
|
|
.TP
|
|
.B 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).
|
|
.sp
|
|
.TP
|
|
.B HTML
|
|
all text after this macro is treated as raw html.
|
|
If the document is processed \fIwithout\fP \fC-Thtml\fP then
|
|
the macro is ignored.
|
|
This macro is a building block for other higher level macros.
|
|
.sp
|
|
For example, the \fCBACKGROUND\fP macro is defined as:
|
|
.nf
|
|
\fC\&.de BACKGROUND
|
|
\&. HTML <body background=\\$1>
|
|
\&..
|
|
\fP
|
|
.fi
|
|
.TP
|
|
.B TAG
|
|
generates an html name tag from its argument.
|
|
This can then be referenced using the
|
|
.URL URL #URL
|
|
macro.
|
|
As you can see, you must precede the tag name with `\fC#\fP' since it is
|
|
a local reference.
|
|
This link was achieved via placing a TAG in the URL description above;
|
|
the source looks like this:
|
|
.sp
|
|
\s-2\fC\&.TP
|
|
.br
|
|
\&.B URL
|
|
.br
|
|
generates
|
|
.br
|
|
\&.TAG URL
|
|
.br
|
|
a URL using either two or three
|
|
.br
|
|
arguments.
|
|
.br
|
|
$1 is the name of the link, $2 is the actual URL
|
|
.br
|
|
\fP\s+2etc.
|
|
.sp
|
|
.\".TP
|
|
.\".B CDFTP
|
|
.\"takes four arguments.
|
|
.\"Basically it is the FTP macro with optional local reference.
|
|
.\"It was designed to allow the same groff source to be built on two different
|
|
.\"machines and access the ftp data differently.
|
|
.\"For example, on a web server you might wish for the web page to reference
|
|
.\"a web site.
|
|
.\"However, if you were producing a CDROM of your information you might wish
|
|
.\"for the ftp data to be also stored on your CDROM and referenced as a file.
|
|
.\"An example to get the current groff development distribution
|
|
.\".CDFTP merlin "click here." \
|
|
.\"ftp://ftp.ffii.org/pub/groff/devel/groff-current.tar.gz \
|
|
.\"../../groff.tar.gz
|
|
.\"The source for this CDFTP invocation is
|
|
.\".sp
|
|
.\"\fC\s-2\&.CDFTP merlin "click here." \
|
|
.\"ftp://ftp.ffii.org/pub/groff/devel/groff-current.tar.gz \
|
|
.\"../../groff.tar.gz\fP\s+2
|
|
.\".sp
|
|
.\"which means if the html is generated on machine \fCmerlin\fP
|
|
.\"then generate a URL to \fC../../groff.tar.gz\fP.
|
|
.\"Otherwise construct an FTP URL to
|
|
.\"\fCftp://ftp.ffii.org/pub/groff/devel/groff-current.tar.gz\fP.
|
|
.TP
|
|
.B LINE
|
|
generates a full width horizontal rule.
|
|
Example:
|
|
.sp
|
|
\fC\s-2\&.LINE\fP\s+2
|
|
.sp
|
|
.SH
|
|
SECTION HEADING LINKS
|
|
.LP
|
|
By default
|
|
.B grohtml
|
|
generates links to all section headings and places these at the top of the
|
|
html document.
|
|
.B Grohtml
|
|
has to guess what a section heading looks like \(em remember that all
|
|
.B 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 \fCgroff -P-g\fP.
|
|
.SH
|
|
LIMITATIONS OF GROHTML
|
|
.LP
|
|
Although basic text can be translated in a straightforward fashion there are
|
|
some areas where
|
|
.B grohtml
|
|
has to try and guess text relationship.
|
|
In particular, whenever
|
|
.B grohtml
|
|
encounters text tables and indented paragraphs or two column mode it will
|
|
try and utilize the html table construct to preserve columns.
|
|
.B 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 :-).
|
|
.PP
|
|
Tbl, pic, eqn's are also generated using images which may be
|
|
considered a limitation.
|
|
.SH FILES
|
|
/usr/share/tmac/tmac.arkup
|
|
.SH "SEE ALSO"
|
|
.BR groff (1),
|
|
.BR troff (1)
|
|
.BR grohtml (1),
|
|
.LP
|
|
.SH AUTHOR
|
|
.B Grohtml
|
|
is written by
|
|
.MAILTO gaius@glam.ac.uk "Gaius Mulley"
|
|
.LINE
|
|
.SH BUGS
|
|
Report bugs to the
|
|
.MAILTO bug-groff@gnu.org "Groff Bug Mailing List" .
|
|
Include a complete, self-contained example that will allow the bug to be
|
|
reproduced, and say which version of groff you are using.
|
|
.LINE
|