Re: Gnome Developer Documentation: how to make 'some' money, Re: Gnome Developer Documentation: how to make 'some' money

[Mathieu Lacage <mathieu gnu org>]

Hi sander,

> > Some may not agree with me but to me, the key problem with the current
> > state of things is twofold:
> >  - lack of a good developer documentation browser: must be lightweight,
> > must have indexing, fast keyword search, full-text search, must be able
> > to browse the documentation in its native form (ie: not the
> > HTML-converted version).
> 
> Soudns like yelp, execpt for the indexing part - but really, yelp should 
> also have indexing and full body search (imho). I undersatand that not all 
> people agree to my 'yelp, the one help browser for user and develoepr docs'
> vision though.

My personal stance is that it's better to have a developer-only help
viewer. I don't have any strong opinion on this though: I can't see much
difference between the UI for a user documentation browser and the UI
for a developer documentation browser. Maybe it's just because I am used
to microsoft's tools... 

I'd say I feel more concerned about having the infrastructure in place
asap rather than focusing on some of the viewer's UI.

> >  - lack of cross-indexing framework. ie: in GTK documentation, you want
> > to refer to some glib function. in libart doc, you refer to some gdk
> > function... Ideally, cross-indexing should work in both the pdf version
> > of the docs, in the documentation-browser version of the docs and in the
> > html version of the docs (for the Gnome website). I am mostly interested
> > in a solution working in the documentation browser though.
> >
> 
> This is a problem of many parts - you need to be able to do the crossrefs in

indeed. Many parts.

> gtk-doc in a menaingful way and onthe tools side you need to be able to 
> preserve the links. In case of pdf you ave to also figure out where the link
> needs to point to (local file? web site?). 

I would guess local file... 

I would say the problem is a bit the same for all of these cases. You
need some kind of unique ID which is independant on the file location
which is used in the XML source but which can be easily be turned into a
location-dependant ID by either the xslt processor or by the formatter
(formatter is either a specific documentation-browser or xsl:fo
formatter or web browser or web server).

So, we have three sub-problems here:
  1) define the location-independant ID format/specification
  2) use the location-independant ID in the developer documentation
and/or make changes to gtk-doc to use it.
  3) hack the conversion tools to support whatever needs to be supported
to recognize the location-independant ID and convert it to
location-dependant IDs.

Idealy, step 3) would be minimized. ie: only changes to the xslts would
be needed.

Some people suggested the use of the existing ghelp:// uri scheme. Some
other people claim this does not work. I personally do not like this
solution very much but feel free to try to convince me :)


Mathieu

PS: It looks like the post-only mailing-list does not work for
gnome-hackers. I thought it would: I guess the moderator will soon be
mad at me.

-- 
Mathieu Lacage <mathieu gnu org>