Re: Issues cooperation

[Eric Baudais <baudais kkpsi org>]

On Fri, 2002-11-29 at 09:02, Richard Stallman wrote:
> Using Docbook as a standard instead of Texinfo is one example of
> divergence on standards.  GNOME developers did not discuss this issue
> with me or even tell me that they were going to disregard a
> long-established GNU standard--I found out only by accident.  I
> proposed a compromise to resolve the divergence, that using Docbook
> for the source is ok if it can be converted automatically into a good
> Texinfo file.
> 
> Just recently I heard that GNOME is telling people to use a program
> called popt instead of GNU getopt; whether that raises any real issue,
> I don't know yet, but I hope we can have discussions before such
> decisions in the future.

The decision to use DocBook was made at the impetus of the GNOME 
Documentation project.  Since I was not involved then I do not know if 
you encouraged the documentation project to use texinfo.  That was the 
time to make such arguments for or against its use.  However, we are a 
long ways from those days.

The main reason for using DocBook is its separation of content and style.  
The DocBook tags describe what is written and try to give a writer a good 
structure to write the documentation.  The tags are to help write the 
documentation conveying the ideas the author intends.  DocBook is 
complimented with stylesheets.  The stylesheets convert the DocBook tags 
into a pleasant to read format and display the writer's work in multiple 
formats.  The stylesheets allow DocBook documentation to be fully 
accessible to people with many disabilities.  DocBook also integrates i18n 
into the document in certain places or for the entire document.  This 
allows translators the flexibility to translate the document in parts 
instead of translating on the entire document.

Texinfo is a decent format for manpages or describing commandline tools.  
However it lacks the ability to function well in a desktop environment.  
Texinfo does not separate the content from the appearance of the document 
making multiple formats and a11y difficult goals.  Texinfo only has i18n 
in the HTML format.  It does not have i18n through the info program.  Since
GNOME is an international project we need to have the ability to translate 
and display all of the documentation in many different languages.  Texinfo 
also lacks the variety of tags forcing writers to make due with a limited 
form of writing.  To quote from the Texinfo manual:
     "The 'Body' of the document is typically structured like a
     traditional book or encyclopedia, but it may be free form."

For these reasons I believe texinfo is not capable of handling the 
documentation needs of a graphical desktop.  There are many different forms 
our documentation takes from FAQs, Glossaries, Release Notes, and Whitepapers 
to articles and books describing each part of the GNOME Desktop.  DocBook 
allows us to use one format for all our of documentation keeping a consistent 
look and feel while not sacrificing a11y and i18n for the format.

Eric Baudais