Re: [Groff] groff documentation

[Larry Kollar]

Werner LEMBERG wrote:

> > > What is it that you need out of texinfo and why is that not being
> > > added to groff?
> >
> > I would guess that what's missing is built-in TOC and xref
> > processing.
>
> Exactly.  Additionally, it is the `official' GNU documentation
> utility.  A lot of packages are documented in texinfo, and the `info'
> interface provides easy access with a uniform interface.

I would hazard a guess that many more packages are documented
in DocBook these days. I won't go into what I think of info's interface
here -- some browsers like Konqueror make it somewhat palatable,
but I would much prefer a set of HTML pages or a properly tagged
PDF for online reading.  Sometimes, a graphic is what's needed and
no amount of words or topics can provide a workaround.

> > ... Beyond that, frankly, I'm not sure what texinfo offers
> > besides the FSF's blessing.
>
> Well, having a uniform documentation format for many packages is
> something which I consider as valuable.  For example, I prefer
> documentation of LaTeX in texinfo format also, mainly for looking up
> keywords, environments, etc.

Again, I think that uniform documentation format (outside the FSF)
is DocBook. Groff can play a part, though -- doclifter does a decent
job of translating groff to DocBook (I've tried it with real documents)
and an XSLT can complete the circuit. DocBook is simply too verbose
to hand-code, but groff is just right.

> What we need are additional tutorials how to actually use groff.
> pic.ms is a very good example; the same should be written for other
> macro packages also.

I definitely agree there. OTOH, a lot of the work is already done.
There's the manpage-HOWTO, the Groff and Friends HOWTO, and
my document on using ms for starters. (And finishers? no) The UTP
is a good resource now, and will get better. The things that are
missing (IMO) are an in-depth treatment of mm (the UTP has a good
introduction, but doesn't cover the things that make mm *the* package
for long documents), good tutorials for the other preprocessors, and
an organized central repository of all the stuff that's already out 
there.

--
Larry Kollar   k  o  l  l  a  r  @  a  l  l  t  e  l  .  n  e  t
There's a fine line between a Christmas wreath and a bunch of dead
clippings tied in a circle. I think it's the red bow that makes the 
difference.
  -- Larry the Cucumber