Re: [Groff] Introduction

[Meg McRoberts]

Welcome, David!

> I have just been made a
> developer of the groff project to assist with your documentation,
> and with the texinfo manual, (and perhaps your website?).

This is great!  Excuse my ignorance, but how exactly is one made
a developer of a specific project?  I'm just curious how these
things work and what this means -- apropos of nothing 

> Regarding the groff documentation, I would like to spend some
> time getting to know of all you, getting a feel for this list and
> this project, before diving into working on improving our
> documentation.  Your suggestions--warm or coldly technical,
> scathingly critical or gently suggestive--are welcome and needed
> so that I can serve you best.

Ah, some of us dream of a geek who just wants to serve us ;-)

Seriously, my impression is that the existing documents are quite
excellent for what they are -- they are well-written and complete.

What is missing are the pieces to make groff accessible to the masses,
as it were.  Okay, I guess to truly appeal to the masses, we need a
WYSIWYG front-end, but let's talk about the middle ground...

The UTP provides good information for someone who needs to learn the
basics of groff input and the groff man pages then provide a complete
reference for the supported macros.  But the UTP material about running
the tools is for troff and not groff so only marginally useful.

Myself, I've been writing documents in groff for more than 20 years,
but most of that was in environments where we had professional tool
people who created and maintained the macro pages.  I think most of
the scions of this group are people who are very comfortable twiddling
with the macros, and I concede that the ability to control the output
that precisely is one of the advantages of groff.

However, I now need to write a few man pages and such.  It took some
work for me to figure out the command lines to process the text (and
ultimately I had to publish my pathetic attempts to the group for them
to fix them).  It would be nice to provide some sample scripts, or perhaps
the actual files that people could install in their own ./bin directories
to just take the input file name and process the file.  They can always
modify them if they want to, but it would make it easier to get started.

Another example: I can't remember how to control the font and numbering
of headers and such.  I remember that there is a line or two that specifies
the point size, bold/italic/roman font, and the spacing before and after
the headers but I can't remember how to do it.  Providing a few sample
lines that produce some common output types would be quite useful, again
to reduce the learning curve.

I'd also love to have a discussion with you about the relative merits of
groff versus XML/docbook.  I confess that I have an emotional attachment
to groff and would like to see it survive, but all the rational arguments
I can make for groff are also answered by XML and XML has some other
advantages.  Are other people interested in this or shall I take this
off-line with David?

meg