Re: [Groff] Re: Gaius docs.

[Werner LEMBERG]

> I do feel some urgency in getting myself up to speed on Groff HTML,
> and having gone a month, now, without having been able to read one
> speck of the relevant docs that are already written on the subject
> so I can get started, when it should have been so simple to have had
> them available in the releases in the first place, and easy to find,
> and easy to read.

OK, I try to give a short intro into grohtml.  My sources of
information are

 .) `design.ms' in the grohtml subdir.  This file can be viewed on a
    terminal like this:

      groff -ms -Tascii design.ms | less

    (you will get warnings about some fonts unavailable which you can
    ignore).  Or, if you prefer:

      groff -ms -mhtml -Thtml design.ms > design.html

    [It is a bit embarassing that even this document can't be
    formatted correctly as a whole by grohtml :-)]

 .) tmac.arkup -- since it is a macro input file for groff, you must
    view it with a plain text editor, reading the comments in it.

First, you must decide which document macro package you want to use.
The file design.ms, for example, uses the `ms' macro package.
Unfortunately (as so many things within groff), groff_ms.man only
documents the differences between the original UNIX troff ms
implementation and groff's one.

On the other hand, complete documentation within groff is available
for the mdoc macros:

  groff -mdoc -Tps groff
  groff -mdoc -Tps groff_mdoc.samples.man > groff_mdoc.samples.ps

(interestingly, it doesn't work OK with -Tdvi... Here some
investigation is necessary).  Alternatively, you can try

  groff -mdoc -TX100 -X groff_mdoc.samples.man

to use xditview for displaying (this needs X Windows) -- note that
xditview isn't installed by default!  You must explicitly change to
the `xditview' subdir and follow the instructions given in the INSTALL
file.  Since it uses `imake' and not `configure', you can't install it
in your private bin directory if you do simply `make install'...

Other well documented macro packages in groff are `mm' -- just a
sample file is missing (I've just written to the author, asking
whether he can provide one) -- and `me'.

Finally, descriptions of the `man' macros are available in
groff_man.man.


Here a very short example using `man' macros.  The HTML output can be
produced with

  groff -man -mhtml -markup -Thtml test.man > test.html

(`-markup' defines the various HTML-specific commands); other devices
should omit `-mhtml'.

NOTE NOTE NOTE

I've just committed fixes to tmac.arkup so that the .FTP and .MAILTO
macros work with non-HTML devices also.


==== test.man ====
.\" man page for thaiconv
.
.TH THAICONV 1 20-Jun-1999 "CJK Version 4.3.0"
.
.
.SH NAME
.
thaiconv \- convert text strings in TIS 620 format into a special format
to be used with
.B emacs 20
in cooperation with
.BR cjk-enc.el .
.PP
It is not intended for stand-alone use.
.PP
This filter is part of the
.FTP "CJK" "ftp://ftp.ffii.org/pub/cjk/devel/cjk-current.tar.gz";
macro package for LaTeX2e.
.
.
.SH AUTHOR
.
The CJK package has been written by
.MAILTO "address@hidden" "Werner Lemberg"
==== end of test.man ====


Please check groff_man.man for the various used commands in the
example.

Empty lines should be not used in a groff file (since they cause the
insertion of empty lines into the output), thus lines just consisting
of a dot are used instead which do nothing.

If you run this with the command given above to create an HTML page,
you can see that `.SH' (and other header requests) automatically
create tags (Gaius, is it possible to suppress this?)

`.FTP' and `.MAILTO' are used as documented in tmac.arkup.

Hope this helps.

Anybody volunteering in writing a groff_markup.man file?


    Werner