Re: Where we'll put docs for control-center

[Dan Mueth <d-mueth uchicago edu>]

On 9 Aug 2001, Aaron Weber wrote:

> Hey all. How does this sound?
>
> We'll add docs directories to gnome-control-center and
> control-center-plus. Zaphod and Hovinen will handle the makefile magic.
>
> The directories will be:
> gnome-control-center/doc/C/
> control-center-plus/doc/C/
>
> The shell will be documented in gnome-control-center.sgml, a complete
> article.
>
> Each capplet gets its own, complete sgml file: keyboard-capplet.sgml
> with its own DTD, not included in any other file. etc.  We'll want to
> avoid using "index" as an article id, however, in the capplet docs.
>
> Then we can install them all to $prefix/help/gnome-control-center/
> and link from the Control Center's help-->Control Center Help menu to
>
> $prefix/help/gnome-control-center/index.html,
>
> and from the capplets to
> $prefix/help/gnome-control-center/capplet-name.html
>
> Let me know if that's completely broken or wahtever. Otherwise, I'll
> start to do it in a few hours.

Sorry for the huge delay - I'm clearly more than a few hours late.

This is a little broken :(  The way the help functions are set up for
GNOME 1.x is that it expects the path and SGML filename to be correlated.
For example, if you call the help file foo.sgml, it looks for it in
$prefix/share/gnome/help/foo/<locale>/foo.sgml.

I believe the reason for this is that we basically retrofit the help API,
which was originally designed to be HTML-only, to handle SGML docs.  The
two parameters which were used for HTML docs, the path and the
file+anchor, became the path=filename and the id.  This is because
db2html generates HTML file names based on the id.

This will be fixed for GNOME 2, so we can have more than one SGML document
in a given path.  However, if this is for release before GNOME 2.0, then
you will need to correlate the SGML file name with the path.

In the past we just shipped one SGML document (probably one main SGML file
which called in SGML entities) for control-center I believe.  If you don't
do this, you will need to use one path for each main SGML file.

Either way, you should follow the convention of using "index" as the first
main id in each file, as given by the template.

Dan