diff options
Diffstat (limited to 'tmac/groff_markup.man')
-rwxr-xr-x | tmac/groff_markup.man | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/tmac/groff_markup.man b/tmac/groff_markup.man new file mode 100755 index 00000000..46233cea --- /dev/null +++ b/tmac/groff_markup.man @@ -0,0 +1,319 @@ +.TH GROFF_MARKUP @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 -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 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. +.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 +@MACRODIR@/tmac.arkup +.SH "SEE ALSO" +.BR groff (@MAN1EXT@), +.BR @g@troff (@MAN1EXT@) +.BR grohtml (@MAN1EXT@), +.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 |