Re: docbook crossrefs

[Malcolm Tredinnick <malcolm commsecure com au>]

Mathieu,

I just wanted to post a reply to say that at least one person read this
and I'm thinking about it in the background.

On Sat, Dec 07, 2002 at 05:58:39PM +0100, Mathieu Lacage wrote:
> 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.

Right at the moment, this is not possible. The initial problem you have
is that you do not know where the API documentation is installed. The
solution is probably to install an OMF file with each piece of API
documentation and register it with scrollkeeper so that something like
Yelp can find the document. That still leaves the problem of how to get
Yelp to extract the right document, but let's cross one hurdle at a
time.

> 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.

Yelp? In theory, it should be possible to do it with a Mozilla-based web
browser as well, using the xml-stylesheet processing instruction, but a
quick experiment I just tried with this and a Docbook-XML document
failed in a way that indicates the Docbook DTD is not being read
correctly. I need to do some more research there (I literally spent
three minutes on it while I just knocking this reply together).

> 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. 

No thoughts on this at the moment, but it sounds hard, I'm not
completely sure I see the advantage, either. Your documents tend to
contain a lot of Dia-generated diagrams. Other documents contain
marked-up screenshots that are created from a few layers in the Gimp, in
other case, SVG images might be a good idea. It looks like a slippery
road here; where do we stop with "special format" display modes?

On the other hand, I see why you would prefer to ship stuff that is as
close to the source as possible.

> 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.

Mathieu, if you are going to put in the effort to write good developer
documentation, then it would be nice if we can support you with the
technology to make a good user experience. To date, this sort of stuff
has not been high priorty. Maybe it's time to change that. In my own
case, I must admit that I have sort of gone off the idea of shipping the
source XML for many documents and feel it is often less hassle to ship
generated HTML, since "everybody has a browser". But that is, again,
probably just a reflection on the tools we have to hand. You have
enumerated some of the obstacles quite nicely in your mail.

Like I said above, I want to think about this a bit more and maybe work
out how we get from "here, today" to "over there, where it's perfect and
easy" in twelve really hard steps.

Malcolm

-- 
The problem with the gene pool is that there is no lifeguard.