The documentation web

[esr thyrsus com (Eric S. Raymond)]

Here is a look at what I'm thinking about in regard to documentation
infrastructure.  Read this with my previous post "Duck season! Rabbit season! 
Mallard season!" in mind.

The novel idea at the center of Mallard is that documentation needs to
be organized and styled in a particular, different, topic-centered way
than it now is in order to to be more effective. I agree with this.  
On-line docs that just read back the interface at me, and that tell me
nothing about troubleshooting when the app behaves unexpectedly, piss 
me off too.

But when thinking about the state of Linux documentation, I start from
a slightly different place than Shaun McCance does.

It bothers me that serious users have to learn finger habits for as
many as five different help browsers: a web browser, man(1), info(1),
the Emacs text editor, a dedicated GUI help browser such as GNOME Yelp
or the KDE Help Center, and the venerable more(1). These are driven by
as many as five different presentation formats (HTML, man, texinfo,
XML, and plain text) that don't share a uniform namespace; thus,
hotlinks that should exist don't and can't.

Additionally, I think it's perverse that Linux users have better
ability to search the external Web via Google than they do to search
the documentation on their own systems.

The disease of which these are symptoms is that the presentation of
Linux documentation is sadly fragmented.  Multiple composition formats
are not a bad thing, but having multiple *presentation* formats and
viewers to go with each one of them them just sucks.  And the
viewers...if it weren't for man(1) being a Hallowed Unix Tradition,
we'd laugh at it in 2007.  And rightly so.

My radical idea is that it's time to shoot man(1), info(1) *and yelp*
through the head and present everything through the user's choice of
web browser, with HTML as a uniform presentation format.  Actually,
I'm not quite that radical.  We can keep yelp and the other
specialized browsers around as backward-compatibility hacks if we're
clever about it.

I think this plan actually dovetails pretty well with the topic-centered 
documentation idea.  It doesn't even exclude writing a Shaun's Magic
New Language -- as long as that's rendered to HTML for user viewing.

HTML and its tools have the advantage of being distro-independent and
desktop-independent, too.  I'm not just after helping GNOME; I want a
solution that any distro and any desktop can use, and a browser gets
us a long way towards that.

In my view of the infrastructure problem, the big grotty issue is not
"how do we write new documentation?". If SNML just turns into HTML for
presentation, almost all of the Mallard architecture just works.  The
big question is, "how do we pull all the legacy stuff into the Web
world?".

I've solved the biggest part of that problem.  My program doclifter 
lifts manual-page sources to well-structured XML-DocBook.  Texinfo
can be translated to XML-DocBook with makeinfo.  Shaun's objections
to XML-DocBook as a composition format have some weight, but it
makes a dandy interchange format and is easy to generate HTML from.

The problem I want to focus on is how to build the software that will
check existing documentation such as manual pages into a system database,
automatically lifting it if it's manual pages and rendering to HTML to
be integrated into the local web.

I think I need to understand Scrollkeeper and Spoon better.

Comments and critcism will be welcomed.
-- 
		<a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>