Re: The documentation web

[esr thyrsus com (Eric S. Raymond)]

Shaun McCance <shaunm gnome org>:
> > 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).
> 
> In terms of finger habits, man == less, info == emacs, and
> Yelp == Epiphany (alternately, KDE Help Center == Konqueror).

I think you're oversimplifying.  I'm counting the invocation
keystrokes as part of the finger-habit overhead, too.  Haven't you
ever typed 'man foo 2' when you meant 'man 2 foo'?

> > 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.
> 
> We *can* link from our help pages to man and info pages,
> but I can't see how man and info pages are going to link
> to help pages without being horribly broken when you view
> them with man(1) and info(1).  Gnome doesn't have control
> over what's written in most of the man and info pages on
> your computer, so it's doubtful there's much we can do.

One category of links we can recognize in info documents immediately
is links to man pages.  

There are some pattern-matching tricks that will make links in the
other direction -- we can look for the word 'texinfo' on a manual page
and look for words nearby that match the known subject of a texinfo
document, then turn them into links.  This capability depends on
having extracted a list of candidate subject words, which is one of
the reasons the architecture I'm envisioning needs a systemwide database of
documention properties behind it.

> > 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.
> 
> This is, again, a writer problem.  We can pat ourselves
> on the back all day for having built clever documentation
> tools, but if writers don't write the content, we're not
> worth a damn thing.  Writers are king.

No, this is *not* a writer problem.  It can be solved very easily with
an engine like ht://dig, provided (a) everything is in HTML, (b) 
ht://dig is told where the HTML trees are, and (c) ht//dig's indexes
get (at least partially) recomputed whenever a package is installed.

This is one of several reasons everything needs to be in HTML.  I want
to use the single-presentation-format property to decouple the various
pieces of the documentation infrastructure from each other.  Neither
ht://dig nor your browser would have to 'know' that any given piece
of HTML is part of local documentation managed by the help system, 
and that's how it should be.

> Let's look at this:
> 
> * We're not about to make Epiphany able to transform
>   DocBook, Mallard, man, and info into HTML on the fly.

Agreed.  That would be too slow,

> * Thus, we have to install the presentation format.

Agreed.  That's my plan.

> * Installing the presentation format is 87% of what's
>   wrong with info.
> * Installing the presentation format seriously hinders
>   our ability to adjust the formatting for accessibility
>   and localization needs.

I don't think so.  Multi-user machines with different users using different
localizations are not a case we need to worry about.  So we localize the
HTML *once*, at document-lifting time, and we're done.

As for accessibility, we leave that to the browser, which is where
accessibility efforts belong anyway (close to the user and easily
tunable by the user).  This is another place where we'd get to
decouple the pieces of the documentation system from each other and
avoid big lumps of specialized code.

> Taking the least-common-denominator route doesn't sound
> like pushing things forward to me.  It sounds more like
> giving up.

Nothing least-common-denominator about HTML, not that I can see.  It's
as rich or richer than any of the other presentation formats in normal
use (e.g. plain text, info, and formatted man pages).
 
> I'd call man pages a very small part of the problem.

Then you'd be wrong.  They swamp everything else in sheer page volume.
Like it or not, about 90% of the documentation on a typical Linux
system is man pages (and yes, I've checked this on a modern Linux).

> Honestly, the sort of content that's generally found
> in man pages is not stuff most people care about.

I think that's a very patronizing judgment.  Let's write infrastructure
that gives our users room to grow and explore, eh?

> But if I have an hour in the evening to work on Yelp,
> and I have the choice between developing tools to help
> us create a better user guide and making man pages work
> a bit better, guess which one I'll choose.

That's an easy guess, and I'd actually *prefer* you made that choice
because I'm more interested in the other end of the problem.
 
> So you want a system daemon that finds all installed
> documentation in any format, converts it all to HTML,
> and stores that HTML so it can be viewed in a web
> browser?  That sounds like a lot of wasted space,
> especially since we've been successfully doing the
> transformations on the fly for years.

It's no worse than preformatting man pages, really -- and, in fact,
the space overhead is comparable since one of the results is that
we can *get rid* of preformatted man pages.
-- 
		<a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>