diff options
Diffstat (limited to 'contrib/groff/tmac/groff_mwww.man')
| -rw-r--r-- | contrib/groff/tmac/groff_mwww.man | 275 |
1 files changed, 275 insertions, 0 deletions
diff --git a/contrib/groff/tmac/groff_mwww.man b/contrib/groff/tmac/groff_mwww.man new file mode 100644 index 000000000000..bec719c30d10 --- /dev/null +++ b/contrib/groff/tmac/groff_mwww.man @@ -0,0 +1,275 @@ +.TH GROFF_MWWW @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" +.\" 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 -mwww macroset +.\" +.do mso www.tmac +.\" we need the .LINKS here as we use it in the middle as an example +.\" once the user requests .LINKS then the automatic generation of links +.\" at the top of the document is suppresed. +.LINKS +.SH NAME +groff_mwww \- groff macros for authoring web pages +.LINE +.SH SYNOPSIS +.B "groff \-mwww" +[ options ] +file ... +.SH 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 +.RB ( grohtml ) +has been completely rewritten but still remains as in an alpha state. +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 SYNPOSIS +.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. +Another method for switching automatic headings is via the command line +switch \fC-P-l\fP. +.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" +\&.MAILTO Ted.Harding@nessie.mcc.ac.uk "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, \fCwww.tmac\fP inserts a zero-width character which +expands to a harmless space (only if run with -Thtml). +.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 +.nf +\s-2\fC\&.FTP "current groff development distribution" \\ +ftp://ftp.ffii.org/pub/groff/devel/groff-current.tar.gz .\fP\s+2 +.fi +.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 +.nf +\s-2\fC\&.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.\fP\s+2 +.fi +.sp +.TP +.B LINE +generates a full width horizontal rule. +Example: +.sp +.nf +\fC\s-2\&.LINE\fP\s+2 +.fi +.sp +.TP +.B LINKS +.TAG LINK +requests that grohtml place the automatically generated links at this position. +For example: +.LINKS +.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. (See +.URL LINKS #LINK +for details of how to switch this off or alter the position. +.SH +LIMITATIONS OF GROHTML +.LP +Tbl information is currently rendered as a png image. +.SH FILES +@MACRODIR@/mwww.tmac (a wrapper for www.tmac) +.br +@MACRODIR@/www.tmac +.SH "SEE ALSO" +.BR groff (@MAN1EXT@), +.BR @g@troff (@MAN1EXT@) +.BR grohtml (@MAN1EXT@), +.LP +.SH AUTHOR +.B Grohtml +was written by +.MAILTO gaius@glam.ac.uk "Gaius Mulley" +.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. |