groff
[Top][All Lists]
Advanced

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

Re: [Groff] Re: Simplifying groff documentation


From: Zvezdan Petkovic
Subject: Re: [Groff] Re: Simplifying groff documentation
Date: Thu, 28 Dec 2006 20:58:35 -0500
User-agent: Mutt/1.4.2i

On Sat, Dec 23, 2006 at 06:01:29PM -0500, Eric S. Raymond wrote:
> I use Emacs to edit DocBook markup directly.

That's not different from what I've been doing.
I wouldn't say that is a comfortable way of writing.

> For someone as bothered by tag verbosity as you are I would recommend
> using asciidoc, which can generate DocBook.

I wonder why asciidoc?
Is it really any different from docutils that we are supposed to use for
Python program documentation?
How about POD that we are supposed to use for Perl program
documentation?
I think I've learned enough "standard" documentation formats.

I do believe that -mdoc already provided a structured (as opposed to
presentation-oriented) way of writing *roff documents.
I use OpenBSD every day, and the man pages on that system are excellent.
The -mdoc macros suffer from the same problem as DocBook -- too many
structural tags for comfortable writing.  It should be noted however,
that writing a precise technical manual requires that kind of tagging.
Several editing iterations are needed to write a precise and concise
technical manual -- they could as well be used to get all the tags
straight.

For general writing, which is what I referred to when I asked
about the comfortable toolset, I find tagging distracting.
Most of the time only a limited subset of tags is needed.
I prefer to stay with *roff, define the macros for structured writing,
e.g. to tag a filename, and use only the tags I really need.
I can quickly change the look of my document with small edits to the
macros.  I can also quickly translate them with a simple script to any
other format (e.g. DocBook).

> On the back end, Norm Walsh's stylesheets do a perfectly competent job
> of generating HTML.  On the print side, I still use the grotty old
> PassiveTex stylesheets for previewing and huddle with the specialists
> at whatever publishers I'm working with (Addison-Wesley last time out,
> O'Reilly before that) to get really good rendering.

I used OpenJade, JadeTeX and DSSSL stylesheets.
The back engine is TeX in both cases, but the layout format is not very
appealing, frankly.  One can do much better with pure TeX or *roff and
structure macros.

> FOP is at 0.92 level now.  What with Java going open, I expect the 
> DocBook -> XSL:FO -> PostScript path via FOP will get really good
> sometime in 2007 or early 2008.

In other words I need this behemoth:

        $ pkg_info -s jdk
        Information for jdk-1.5.0p20

        Size: 227110409

just to typeset my documents.
And I already have a computer and groff installed on it.
Which one I'm going to go for?
:-)

Don't get me wrong.
I understand that we are in the 21st century, and I understand all the
advantages that DocBook offers.
There is a deeper philosophical question here.
Who needs to tag a document for all the sorts of semantic or any other
meaning?  Is it the author or somebody else?
I remember an anecdote about a faculty member from a non-scientific
department attending a seminar on use of computers.  Her comment was:
"Good Lord, you are turning us all into secretaries."

Best regards,

        ZP




reply via email to

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