groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Groff] groff documentation


From: Larry Kollar
Subject: Re: [Groff] groff documentation
Date: Mon, 2 Dec 2002 22:28:06 -0500

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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]