Re: Help file names

[Dan Mueth <d-mueth uchicago edu>]

On Wed, 5 Dec 2001, Malcolm Tredinnick wrote:

> 'Evening all!
>
> I'm currently going through the help handling in libgnome, trying to
> make sure it matches jrb's earlier api description and generally
> cleaning it up. Something has come up that I need to confirm/resolve.
>
> The main help processing code has just been lifted out of Nautilus and
> put into libgnome. There is some logic in there that does "promotion" of
> filenames from *.html to *.sgml, if necessary. This brings up three
> questions:
>
> (1) Do we want to do this (I think we do)?

Good question...

The reason we initially did this (starting in GNOME 1.4) was that the
GNOME platform's help support assumed all help was in HTML.  That decision
was made a long time ago and the API could not be changed when we more
recently developed tools for converting from SGML and XML to HTML
on-the-fly.

Now that we are putting out GNOME 2.0, we have an opportunity to make
backwards-incompatible API changes and explicitly support XML and SGML
document formats (in addition to HTML).  I think we want each application
to decide which format its documentation will be in (hopefully XML, but
not always) and then use the appropriate API calls to refer to those
documents.  For example, if gfloppy ships its docs in XML format, we
should not encourage or officially support having the application link to
its docs using index.html#abc.

The one place this would be useful is for cross-referencing.  Suppose
gfloppy ships its docs in HTML, then the Nautilus Manual may link to it as
an HTML file.  If gfloppy then ships a newer version with XML docs, the
old links from the Nautilus doc to the gfloppy doc will break without this
promotion system.  Since we are strongly encouraging the use of XML over
SGML or HTML starting with GNOME 2.0, this should not happen very
frequently.  It may happen more with non-GNOME docs which are viewed
through the GNOME help system.

> (2) The current promotion rules are
>    ghelp:/.../gfoo/C/index.html     -> ghelp:/.../gfoo/C/gfoo.sgml#index
>    ghelp:/.../gfoo/C/index.html#abc -> ghelp:/.../gfoo/C/gfoo.sgml#abc
>    ghelp:/.../gfoo/C/stuff.html     -> ghelp:/.../gfoo/C/gfoo.sgml#stuff
>    ghelp:/.../gfoo/C/stuff.html#def -> ghelp:/.../gfoo/C/gfoo.sgml#def
>
> These rules seems sensible, providing we commit to saying the main help
> file for application Foo should be called foo.sgml.

Yeah.  Our previous setup was fairly lame in that we required the SGML
document base filename and path to be identical (gfoo here).  I was
looking forward to relaxing this constraint, although in reality many
documents may follow this convention.

> (3) I assume we really want the promotion rules to be to first promote
> to foo.xml and then foo.sgml, right (assuming the *.html file requested
> doesn't exist)?

Right.


Overall, the utility of this URL promotion code is substantially
decreasing considering our new API as well as our relaxed constraints on
file and path naming.  I think it is fine to keep the code around for rare
cases where it automagically fixes cross-reference links between
documents, but it will not always work unless we go back to requiring path
names and file names be the same, which I don't think we want to do.   I
wouldn't put much effort into it though, and you may want to add some
explanation in the code that this just fixes some cross-links and should
not be relied upon for normal use.

Dan