Re: The documentation web

[danilo gnome org (Danilo Šegan)]

Hi Eric,

On Friday at 16:34, Eric S. Raymond wrote:

> Danilo Šegan <danilo gnome org>:
>> >> * Installing the presentation format is 87% of what's
>> >>   wrong with info.
>> 
>> Seconded.  Maybe new texinfo stuff (such as images) would get used
>> more if info readers actually supported it properly.
>
> HTML supports images, so I don't see how this criticism makes a lot
> of sense.

The point was: when we distribute documentation in its source format,
it gets more widely used, and (new) features get to everybody faster.
Texinfo-using packages currently install only '.info' files which lose
data about images which can be viewed with a (very, "CVS", "snapshot")
recent Emacs and not much else.  And .info files are a presentation
format for TeXinfo, which is much more semantic than info (it's also
much harder to render info file in non-monospace type in a pretty way
than texinfo for the same reason).

The idea is that it's advantageous for everybody: for maintainers who
can simply install source document files; for users who can easily
read them even when they change slightly; for documentors who can
easily update them and send their changes to maintainers.

>> Completely broken and backwards, IMHO: with all the tools we have
>> already developed to provide such behaviour, a reason to go back to
>> as limiting behaviour as you suggest would be?
>
> Well, the big one would be being able to cross-link documents no matter
> what their original format was.

Like "man:bash" or "info:gettext"?  Ah, Yelp already does that.  And
I'm pretty sure that's how KHelpCenter (or whatever's the name) does
this as well.

>> But one can do so much better when you go more specific.  I'd prefer
>> more specialized code than worse experience for users.
>
> OK.  Better how?

Gecko currently has its own problems regarding a11y, and by providing
TOC and document movement using Gtk+ and atk, one can actually improve
the experience for a11y users *today*.

We can guess what users will want to do more commonly with help than
with regular web pages (like "next page", "up", "find topic"), so we
can also optimize for that.

When I load untranslated document inside Yelp, I want it to show me
user interface elements using translated Serbian terms (which is what
I'll see).  If we dump Yelp, we won't be able to do that, but we can
extend a specialized help-browser to support something like this
(though, this is not yet supported in Yelp, and nobody is actually
working on it, but it's an example of how you can make it better in
practice).

And take for example printing: we can do much better printouts from
dedicated help reader then from a web browser which is usually good
only at printing web pages.  One by one.

> And 'worse' is multidimensional.  I keep coming back to the fragmented
> formats, fragmemted tools, and impoverished link structures.  It seems to
> me that fixing that would be worth a lot.

I agree, but I don't agree with your proposed solution of switching
back to static HTML files when we can instead provide better
experience this way.

Cheers,
Danilo