Re: jrb's help proposal (was Re: Undelivered ...)

[Jonathan Blandford <jrb redhat com>]

John Fleck <jfleck inkstain net> writes:

> Will we courageously abandon shipping HTML as part of standard GNOME
> packages and only ship the XML? I think the answer should be yes.

I vote yes.  I'm not writing many docs though... (-:

> So if I am writing documentation for app1 and I want to create a link
> within it to a particular section in app2's documentation with
> id="thesection", I would use as my ulink URI:
> 
> ghelp:app2/app2.xml?thesection

Yes, though the xml is optional.

> Do I have this right? Or would it be:
> 
> ghelp:app2?thesection

This is wrong.  You can link to ghelp:app2 if you want to generically
link to the application. 

> >   2.4) Converting a relative ghelp URI to an absolute URI:
> > 
> >     To convert URI schemes, the help browser must convert the
> >     <appid>/<file> part to the <path> field.  The basic way of doing this
> >     is to do
> >     <path> = <GNOME_DATADIR>/<appid>/<LOCALE>/<file>[<extention>]
> > 
> > 
> >     where <GNOME_DATADIR> is the datadir prefix where the
> >     help-browser/GNOME is installed and <LOCALE> is the current locale.
> > 
> >     extension = ( ".xml" | ".sgml" | ".html" | "")
> > 
> >     An interesting thing about doing the conversion is that it requires
> >     the application doing the conversion to check to see if the file
> >     exists.
> > 
> 
> To read KDE's docs, I believe we need to ad .docbook to the extension list.

Okay, will do.

> By "index of topics" do you mean a Nautilus-style
> ScrollKeeper-generated list of available help docs?

Yes.  That's exactly what I mean

> > [1] More information on actually writing the documentation can be found
> > at http://developer.gnome.org/projects/doc/  FIXME: need better link
> 
> http://developer.gnome.org/projects/gdp/styleguide.html
> for the style guide, and
> http://developer.gnome.org/projects/gdp/handbook.html
> for the GDP handbook.

Thanks.  I'll put up an updated version of the doc later tonight with
all the suggestions made.

-Jonathan