Re: PROPOSAL: Help File Format Standardization

[James Smith <j-smith physics tamu edu>]

Bowie Poag wrote:
> 
>  The UISG proposes that..
> 
>  o All GNOME Application Help Text is to be written in HTML.
> 
>  o Why HTML? Simple. Plenty of authoring tools, its an accepted
>    standard, its portable, extensible, flexible, and clean. It
>    will also make the transition path for KDE developers a little
>    easier, once they've realize the error of their ways and start
>    developing for GNOME. ;)
> 
> Yes, I know about docbook.
> 
> Agree or Disagree?
> 

Disagree in part - I think html is good for on-screen help, but docbook
can generate html along with several other formats more suitable for
print, etc. (not sure what etc. is, but...).   If we have all help docs
as docbook or similar, then html can be generated as needed (and
cached?) along with TeX or any other type we may need.  Also,
compilations of documents would be a bit easier to coordinate, I would
think.  For example, a small program could have its help files as
articles (maybe one per game).  Then a compilation of articles is
possible - a volume for gnome-games.

I see html as good for day to day use by most users but docbook as more
flexible.  My vote is for docbook with automatic (behind the scenes)
translation to html as needed.  We could make docbook a G3/4 requirement
and html a G1/2 requirement.

--Jim Smith