Re: <OK> [Groff] Simplifying groff documentation

[M Bianchi]

On Sat, Dec 23, 2006 at 12:56:47AM -0500, Eric S. Raymond wrote:
> M Bianchi <address@hidden>:
> > On Fri, Dec 22, 2006 at 06:19:15PM -0500, Eric S. Raymond wrote:
> > >   :
> I think you'll see from my previous reply to Ted Harding that 
> I agree with this.

Yes, I see.
  
>       :
> Well, of course what we want is "clear, cogent and accurate documentation".
> But I can't solve *that* problem.  What I can do, and have been doing more 
> or less by stealth since 2001, is lining up all the technical ducks in a
> row so we can address the format and infrastructure problems.

I think you *can* very much help solve that problem.  The management of
documents has gotten in the way of the maintenance of documents and so many man
and info pages are out-of-date.  Many HOWTOs are very dated. 

I'm beginning to think that maybe a wiki front end that yielded XML-DocBook of
the RefEntry document type could encourage keeping lots of documentation
current.  The Linux Documentation Project might find that appealing also.

> > Could the wikipedia markup be (close to) adequate?  Something
> > similar?  Standing firmly on an existing popular standard could be
> > important to achieving wide acceptance.
> 
> And that's why, in the grand master plan, XML-DocBook has a central
> role.  Nobody wants to read it directly -- you render to HTML or
> Postscript with a stylesheet to do that.  But it makes a dandy 
> format for masters and searchable archives.  Wiki markups doesn't
> quite have the structural richness needed.

Maybe the current Wiki markups don't do the job, but I'm thinking that
something more modern and structured that man pages and texinfo is needed.

If editting XML-DocBook directly is unappealing, we need something that is.

>       :
> Multiple composition formats (including man markup) but all feeding to 
> one richly-structured exchange format, which is then rendered to 
> different media by stylesheets.

Dealing with the legacy sources is important, but I'm convinced that the
underlying problem is the lack of a good, common-knowledge mechanism that would
make document creation/maintenance more appealing and less dependent on arcane
knowledge, which I believe is your ultimate goal.

I propose the wiki idea because it _is_ currently popular and _seems_ to be the
_sort_ of mechanism that could last for a long time (Order: decades).

I encourage the  flat text  format because sometimes things like X fail and you
want access to the documents without requiring the fancy programs work and a
flat-file editor is all you have.

 +-------------+                                     +--------------------+
 |  man pages  |-----+                          +--->|  HTML on browsers  |
 +-------------+     |                         /     +--------------------+
                     |                        /
 +-------------+     |        +-------------+/       +===========+
 |  Texinfo    |-----+------->| XML-DocBook |=======>| flat text |
 +-------------+     |        +-------------+\       +===========+
                     |                        \
 +===============+   |                         \     +------------------------+
 | RefEntry wiki |<==+                          +--->| PostScript on printers |
 +===============+   |                               +------------------------+
                     |
 +-------------+     |
 |  other      |-----+                                     ====  Added
 +-------------+

And if noone has said it, THANK YOU for tackling the problem of adding
appropriate structure to the document base.  It _has_ needed attention.

-- 
 Mike Bianchi
 Foveal Systems

 973 822-2085   call to arrange Fax

 address@hidden
 http://www.AutoAuditorium.com
 http://www.FovealMounts.com