[Groff] New html docs

[Gaius Mulley]

Hello Gentlemen,

Many thanks to Eddie for forwarding me some missing emails.
After reading much discussion about missing html documents
I thought I'd make a start on documenting the tmac.arkup
including some examples.

Eddie: I'll make a start at translating the groff homepage into groff.
I'll do from the top to the bottom of the README section - is
that ok?

Here is where I've got to in producing documentation for grohtml.
Werner: I've placed this document into the doc directory any chance
it can be checked into cvs?

Anyone please feel free to improve it - it is only a start and
needs polishing, extending etc. Also I'm sure the macro set could be
improved - so all you macro experts in groff land - go for it..

Hopefully it will allow people to experiment more easily with grohtml.
Have a good new year everyone,

cheers Gaius

The remainder of the email consists of three components:

  (i)   The first file is the new doc/Makefile in the groff source
        release.
  (ii)  The new grohtml documentation file (called doc/html.ms)
  (iii) A patch for the doc/Makefile against the repository GMT 13:30

--------- cut here --------- cut here ------- cut here ------------
#Copyright (C) 1989, 1990, 1991, 1992 Free Software Foundation, Inc.
#     Written by James Clark (address@hidden)
#
#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.

FFLAG=-F..
TROFF=../troff/troff -M../tmac $(FFLAG)
GROPS=../grops/grops $(FFLAG)
DOCS=meref.ps meintro.ps pic.ps html.ps html.html html.ascii pic.html
MEMACROS=../macros/tmac.e
SOELIM=../soelim/soelim

all: $(DOCS)

.SUFFIXES: .tr .me .ms .ps .dit

.dit.ps:
        $(GROPS) $< >$@

.me.dit:
        $(SOELIM) $< \
        | sed -e "s;@VERSION@;`cat ../VERSION`;" \
        | $(TROFF) -Tps $(FFLAG) -me  >$@

.tr.dit:
        $(TROFF) -Tps $< >$@

%.html: %.ms
        export GROFF_TMAC_PATH=../tmac ; \
        sed -e "s;@VERSION@;`cat ../VERSION`;" $< \
        | ../groff/groff -p -e -t -Thtml $(FFLAG) -U -ms -mhtml -markup >$@

%.ascii: %.ms
        sed -e "s;@VERSION@;`cat ../VERSION`;" $< \
        | ../groff/groff -p -e -t -Tascii $(FFLAG) -U -ms -markup >$@

%.ps: %.ms
        sed -e "s;@VERSION@;`cat ../VERSION`;" $< \
        | ../groff/groff -p -e -t -Tps $(FFLAG) -U -ms -markup >$@

meref.ps: meref.dit
meintro.ps: meintro.dit

# This production must use -p -e -t so pic/eqn processing is done
pic.ps: pic.ms
        sed -e "s;@VERSION@;`cat ../VERSION`;" $< \
        | ../groff/groff -p -e -t -Tps $(FFLAG) -ms  >$@

pic.html: pic.ms
        sed -e "s;@VERSION@;`cat ../VERSION`;" $< \
        | ../groff/groff -p -e -t -Thtml $(FFLAG) -ms -mhtml >$@

install:

clean:
        -rm -f *.ps *.html *.png *.gif *.dit core
        -rm -f *.aux *.cp *.cps *.cv *.cn *.dvi *.fn *.fns *.ky *.kys \
               *.log *.op *.pg *.pgs *.ps *.toc *.tp *.tps *.tr *.vr *.vrs

distclean: clean

realclean: distclean

extraclean: clean
        -rm -f core *~ \#* junk temp grot
--------- cut here --------- cut here ------- cut here ------------
.\"
.\" user level html guide
.\"
.\"  build using:
.\"
.\"  make html.html
.\"
.TL
Authoring Web Pages with Groff
.AU
Gaius Mulley
.AI
Address: \c
.MAILTO address@hidden
.AB
As from groff-1.12 there is a html device driver for groff,
namely, grohtml.
This device driver is still in an alpha state and has
been included into the distribution so that a lot of
people have a chance to test it.
This document is a very basic guide to authoring simple web pages
using grohtml and the associated macro set -markup.
.AE
.NH 1
What is grohtml
.LP
Grohtml is a back end for groff which generates html.
The aim of grohtml is to produce respectable html given
fairly typical groff input.
.NH 1
Are there any macro sets for grohtml?
.LP
A simple macro set exists called -markup.
Here is a summary of the functions found in this macro set.
.IP "HTMLINDEX" 1i
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
\s-2\f[CR]\&.HTMLINDEX 0\fP\s+2
.fi
.sp
will tell grohtml not to generate links.
An \fCHTMLINDEX\fP of 2 will mean that a heading
.sp
\fB1.1.1 Some Title\fP
.sp
will not be included in the links either as it is said to have
a heading level of three.
.IP BODYCOLOR 1i
takes five parameters: foreground, background, active hypertext link,
hypertext link not yet visited and visited hypertext link colour.
.IP BACKGROUND 1i
the only parameter to this macro is the background image file.
.IP URL 1i
generate a URL using two arguments.
.TAG "URL"
$1 is the name of the link and
$2 is the actual URL. The way the
.URL "homepage for groff" http://groff.ffii.org/
was encoded is given below:
.sp
.nf
\s-2\f[CR]\&.URL "homepage for groff" http://groff.ffii.org/\fP\s+2
.fi
.sp
When this is processed by a device other than \fC-Thtml\fR
it appears as:
homepage for groff (<url: http://groff.ffii.org>).
The URL macro can be of any type for example we can
reference
.URL "Eric Raymonds pic guide" pic.html
by:
.sp
.nf
\s-2\f[CR]\&.URL "Eric Raymonds pic guide" pic.html\fP\s+2
.fi
.sp
.IP "MAILTO" 1i
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. For example the groff
maintainers are
.MAILTO "address@hidden" "Werner Lemberg"
and
.MAILTO "address@hidden" "Ted Harding."
This is achieved by the following macros:
.sp
\s-2\f[CR]\&.MAILTO "address@hidden" "Werner Lemberg"\fP
.sp
\f[CR]\&.MAILTO "address@hidden" "Ted Harding."\s+2\fR
.sp
Note that all the urls actually are treated as consuming no
textual space in groff. This could be considered as a bug
really and it does cause some problems. For example
at the top of this document I've had to prefix my email
address with \fIAddress:\fR otherwise groff believes
the authors address has zero characters width [1].
.IP "FTP" 1i
indicates that data can be obtained via ftp. The first
argument is the browser text and the second is the url.
The advantage of using this macro rather than the generic
URL macro is that if the document is processed for a different
device then the macro encapsulates the ftp address with (<ftp: address).
For example the
.FTP "current groff development distribution" \
ftp://ftp.ffii.org/pub/groff/devel/groff-current.tar.gz
can be found at ffii.org.
When this document is processed for another device the
last sentence will read, "For example the current groff development distribution
(<ftp: ftp://ftp.ffii.org/pub/groff/devel/groff-current.tar.gz>) can be
found at ffii.org.
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\fR\s+2
.sp
.IP "IMAGE" 1i
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 400 pixels if absent).
The third argument is the height in pixels (default is the width value if 
absent).
.sp
.IP "HTML" 1i
all text after this macro is treated as raw html.
If the document is processed \fIwithout\fR \f[CR]-Thtml\fR then
the macro is ignored. This macro is a building block for
other higher level macros.
.sp
For example the \f[CR]BACKGROUND\fP macro is defined thus:
.nf
\f[CR]\&.de BACKGROUND
\&.   HTML <body background=\\$1>
\&..
\fP
.fi
.IP "TAG" 1i
generate an html name tag from $1. This can then be referenced using
the
.URL "URL" "#URL"
macro. This link was achieved via placing a TAG in the URL description
above and the source looks like this:
.sp
\s-2\fC\&.IP URL 1i
generate a URL using two arguments.
.br
\&.TAG "URL"
.br
$1 is the name of the link and
.br
$2 is the actual URL.\fR\s+2 etc
.sp
note that it is placed after the first sentence as the any raw HTML text
is currently considered to have zero width.[1]
.\"
.\" forced page break to work around a bug in grohtml :-(
.\"
.if '\*(.T'html' .bp
.IP "CDFTP" 1i
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
your 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\fR\s+2
.sp
which means if the html is generated on machine \s-2\fCmerlin\fR\s+2
then generate a URL to \s-2\fC../../groff.tar.gz\fR\s+2. Otherwise
construct an FTP URL to 
\s-2\fCftp://ftp.ffii.org/pub/groff/devel/groff-current.tar.gz\fR\s+2.
.NH 1
Section heading links
.LP
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
\fCgroff -P-g\fR.
.NH 1
Limitations of grohtml
.LP
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 :-).
.PP
Tbl, pic, eqn's are also generated using images which may be
considered a limitation.
.FS
[1] This occurs
currently because the hypertext information is passed
from source to device driver using the special character
sequence \fC\\X^html:\fP. This could be fixed in the \fCtmac.arkup\fR
I believe by telling groff the width of the textual string.
However we then need to ensure that the html font set is accurate to
the browser font set, which may not be so easy.
.FE

------- cut here for the patch ------- cut here ------------
diff -r -c groff-cvs/doc/Makefile groff-html/doc/Makefile
*** groff-cvs/doc/Makefile      Thu Dec  9 09:42:29 1999
--- groff-html/doc/Makefile     Fri Dec 31 14:01:43 1999
***************
*** 20,26 ****
  FFLAG=-F..
  TROFF=../troff/troff -M../tmac $(FFLAG)
  GROPS=../grops/grops $(FFLAG)
! DOCS=meref.ps meintro.ps pic.ps
  MEMACROS=../macros/tmac.e
  SOELIM=../soelim/soelim
  
--- 20,26 ----
  FFLAG=-F..
  TROFF=../troff/troff -M../tmac $(FFLAG)
  GROPS=../grops/grops $(FFLAG)
! DOCS=meref.ps meintro.ps pic.ps html.ps html.html html.ascii pic.html
  MEMACROS=../macros/tmac.e
  SOELIM=../soelim/soelim
  
***************
*** 38,43 ****
--- 38,56 ----
  
  .tr.dit:
        $(TROFF) -Tps $< >$@
+ 
+ %.html: %.ms
+       export GROFF_TMAC_PATH=../tmac ; \
+       sed -e "s;@VERSION@;`cat ../VERSION`;" $< \
+       | ../groff/groff -p -e -t -Thtml $(FFLAG) -U -ms -mhtml -markup >$@
+ 
+ %.ascii: %.ms
+       sed -e "s;@VERSION@;`cat ../VERSION`;" $< \
+       | ../groff/groff -p -e -t -Tascii $(FFLAG) -U -ms -markup >$@
+ 
+ %.ps: %.ms
+       sed -e "s;@VERSION@;`cat ../VERSION`;" $< \
+       | ../groff/groff -p -e -t -Tps $(FFLAG) -U -ms -markup >$@
  
  meref.ps: meref.dit
  meintro.ps: meintro.dit