Re: [Groff] Re: Simplifying groff documentation

[Eric S. Raymond]

Zvezdan Petkovic <address@hidden>:
> > For someone as bothered by tag verbosity as you are I would recommend
> > using asciidoc, which can generate DocBook.
> 
> I wonder why asciidoc?

Because it's the simplest way to compose DocBook-structured stuff I've
seen yet.

> 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.

You left out Texinfo :-).

My vision is that all of these feed into DocBook, which then 
(a) becomes the transfer format everybody uses, and (b) has a
common back end for rendering HTML or print that everyone can use.

Thus, you would be able use any "standard" format you like for composition.
Past the point where it got turned unto DocBook, nothing would care.

But this wouldn't be worth doing for its own sake.  The goal is to
change the way Unix documentation is presented so that it all comes through 
the user's browser and has hyperlinks to everywhere.  

We can't get there without converging all the formats at some point.  
Where the path I'm advocating differes from the ad-hoc, 
bash-everything-to-HTML-with-its-own-converter approach is that it
captures (or deduces) more semantic information at an earlier stage.
I think this is worth doing because when you do that you get better
HTML out the other end.

> 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?

Who tags the man pages you write?  Who should tag them?

This isn't a silly or confrontational question -- because doclifter
can turm your man pages into high-quality DocBook markup, it's
actually the *same* question.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>