Re: Help file names

[Malcolm Tredinnick <malcolm commsecure com au>]

On Thu, Dec 06, 2001 at 09:30:51AM -0600, Dan Mueth wrote:
> On Wed, 5 Dec 2001, Malcolm Tredinnick wrote:
> > 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.

Hmm. My brain is full, can I be excused now?

I had a bit of a difficult time understanding all of this, but I think
you're suggesting that we leave th existing funtionality and mark it as
deprecated, right? However, not in a GNOME_DISABLE_DEPRECATED fashion --
more in a way that people are just "encouraged" not to use these
features. Is that reasonable?

That would be fine with me. Having read through and tested the code in
question a bit more over the last couple of days, I think it does what
it claims, but in a fairly fragile way. So marking as deprecated would
be fine with me.

If nobody has anything further to say about this over the next half day
or so, I'll go with this, since I want to get things squared away in a
fashion that won't change so that we can start testing in earnest.

Cheers,
Malcolm

-- 
The early bird may get the worm, but the second mouse gets the cheese.