Re: The documentation web

[danilo gnome org (Danilo Šegan)]

Hi Eric, Shaun,

Yesterday at 22:12, Eric S. Raymond wrote:

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

You can decouple indexing from a viewer without having all content
downgraded to HTML.  Heck, that's what tracker/Beagle should provide
us in the very near future, and we may only need to provide proper
modules for them.


Now, I was just going to highlight two issues in Shaun's email which I
consider essential, but you did so yourself (though, you did so to
disagree :).

>> * 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.  And they would
have supported it better if such TeXinfo documents actually propagated
to users.  And maybe more people would work on such documentation, and
more maintainers would use it if it was simpler (for example, with
DocBook and Yelp atm, you can simply "yelp blah.xml" and get nice
output—and it took Yelp a while to get there).

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

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?


Also, I'd much rather go to more dynamic documentation (such as
providing menu/application labels from the UI, not hard-coding them,
than going back to more static stuff), which would also solve a big
i18n issue at the same time (some people use English locale on their
desktops, yet want to read translated documentation which will have
menus and buttons translated as well; and even more common is a case
where people use translated UI, but there is no translated
documentation).

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

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


Cheers,
Danilo