Re: docbook crossrefs

[Eric Baudais <drake gnome org>]

Mathieu-

We already have a system in place for doing most of the things you are
wanting for the user docs.  Jonathan Blandford has written a nice URI
for help called ghelp which makes referencing docs fairly painless in a
GNOME environment.  Yelp is a plain and small view which should work
well for any types of documentation.  The GDP has implemented a basic
infrastructure for doing this, but it is no where near finished.

The way I am recommending to cross reference docs using the ulink tag
and the ghelp URI.  This will only work for documents installed by
scrollkeeper, but should be good enough for the GNOME user docs.  If the
developer docs were registered with scrollkeeper then you could also use
the ghelp URI.  e.g.
<ulink href="ghelp://gedit">gedit manual</ulink>
makes a link to the gedit manual.  Also 
<ulink href="ghelp://gedit?intro">introduction to gedit</ulink>
makes a link to the gedit manual at the intro id.

You can use Yelp to display the developer documentation in GNOME.  Once
the docs are registered with scrollkeeper Yelp automatically includes
them into its categories and you can then view them.  Yelp might not
display the developer documentation in the nicest form, but we can work
on that through the stylesheets.

Displaying dia files might be a bit harder to do.  DocBook 4.2 supports
SVG files and hopefully the user docs will migrate to DocBook 4.2 by
GNOME 2.4.  However, this does not mean you could start experimenting
with it.  My own knowledge is rather limited in this area though.

Hopefully I have answered your questions about what type of tools and
mechanisma are in place to view and reference docs in GNOME 2.

Eric Baudais

On Sat, 2002-12-07 at 10:58, Mathieu Lacage wrote:
> hi all,
> 
> I have been trying to write some gnome developer top-level documentation. One crucial thing I need to do is to cross-ref multiple other docbook-based documents (the different api docs we have).
> 
> The question is: how can I write docbook which generates correct html links if it is translated to html by the help browser ? Is this possible without any G2-specific extension ? I don't rellay understand the ins and outs of the problem but I know what I want to do: I want to be able to click on the links when I cross-ref a function from my documentation and get the function's API doc be displayed by the application.
> 
> I also wonder if there is a specific application I should use to display developer documentation. I am not too excited by devhelp because it seems not to use native xml db as its source format and I'd like to ship users the xml and not any automatically-generated file.
> 
> Finally, it would make sense if we could provide users with a tool which can display dia files (and not pngs) in the document directly such that we don't have to ship pngs. 
> 
> I know most of the points above are:
>   - difficult if not impossible to implement
>   - subject to endless discussions
> but, as a doc writer, I'd like to know what the user experience will be when they read my doc and I'd like this experience to be as good as possible _and_ I'd like not to ship any automatically-generated file because it is always a pain to maintain.
> 
> I hope I won't generate too much hate-mail,
> 
> regards,
> Mathieu
> 
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list