Re: [Groff] Re: ms docs?

[Ted Harding]

On 02-Jan-00 Eddie Maddox wrote:
> 
> See the disconnect here? The fact that he used ms means Somebody has ms
> docs Somewhere. Right? So, ms Is documented, after all, somewhere, it
> would seem.

There is at present NO self-contained complete documentation for
the groff ms macros.

Those of us who use them have either migrated from using them
on other UNIUX troffs or have had access to UNIX troff documentation
and have used groff 'man ms' to ascertain the differences; as well
as maybe also studying the internals of tmac.s.

My personal mission is to (a) produce a comprehensive groff reference
manual for gtroff (i.e. the troff part of groff) and then (b) to turn
to the macros, starting with ms (since that is what I mostly use
and therefore know well).

A reasonable starting point for anyone starting from scratch is
to find a reference for UNIX ditroff ms macros (the relevant pages
of "UNIX in a Nutshell" by Daniel Gilly et al, published by O'Reilly,
are quite useful, if you don't have access to a real UNIX manual),
together with a study of the differences as documented in the groff
'man ms', suplemented by some experimentation sho that you can find
out what is not documented in either place!

The O'Reilly book is, however, purely a reference summary: there is
practically nothing in the way of illustrative examples (very little
for troff, tbl, eqn or pic and nothing at all for the mm, me and
ms macro packages). As reference material, however, it is good.

Everyone's concern about what is lacking or incomplete or needed
in groff is shared by Werner and myself: indeed, it was our discovery
that we were both impatient for someone to take it in hand that prompted
us both to grasp the nettle. My particular concern, as indicated above, is
lack of documentation; I am well aware -- and it is well illustrated by
Eddy's remarks -- that potential newcomers to groff are going to have a
hard time; many indeed may well give up, if the documentation is not
there. Hence my concern to prepare good documentation.

Nevertheless, may I, please, plead with everyone to try to be patient
(and I am sure Werner would wish to join in the plea). Doing a
half-baked job is perhaps not too difficult. Doing a thorough one is a
major task, and a thorough job is long overdue. Rest assured that the
task is in hand and is making good progress. I hope, indeed,
that a first draft of the "Groff Reference Manual" will be
avialable for comment before long.

At the same time, I am becoming sufficiently conscious of a general
need for macro documentation to begin work on a "User's Manual
for the Groff ms Macros", so that has started too -- but only just!

Best wishes -- and a very Happy New Year -- to all.
Ted.

--------------------------------------------------------------------
E-Mail: (Ted Harding) <address@hidden>
Date: 02-Jan-00                                       Time: 19:37:54
------------------------------ XFMail ------------------------------