Am Mit, 2003-07-23 um 22.35 schrieb David Neary:
> I may be missing the point, but if you use relative paths for
> linking, there wouldn't be a problem, would there?
There is, because I still need to know the filenames somehow. Setting up
a mapping topic->HTML file for GIMP is not elegant but doable (in fact
that's what GIMP 1.2 does in source), the bigger problem is to get the
xsltprocessor to spit out little chunks of documentation with the
correct filename. I can only setup the granularity and provide filenames
which are more treated like hints, means: I say, give this chapter the
filename foo.html and the subsections the names bar.html and baz.html
and it'll go creating one file foo.html with the content of bar.html and
baz.html but not those files.
Note: This is not the only thing that can happen wrt to the generated
files, and exactly the reason why I reorganized the whole old helps'
structure to match the desired filesystem layout which is not only a
pain in the ass to maintain and setup but also überugly to read. Still
the old help is missing a few files which are there but have a different
than expected name and thus cannot be found by the helpbrowser; also
there's some really nasty link/copy/rename action involved at "compile
time"...
The new docs are designed around a natural reading to ressemble a normal
style manual which can be used as an online help as well. Though to get
usable results without bending around some filenames we need to directly
navigate to the desired point using canonicalized ids. This is AFAIR
only possible by doing something similar to yelp, i.e. using a DOM to
navigate directly to ids and render exactly the named element including
all subelements.
> In any case, I bow to your greater knowledge :) I really know
> very little about documentation mark-up.
This is really not about mark-up but about transformation. :)
> I understood that docbook2html xslt was out there, and that there
> were utilities that did docbook to pdf, html or text fairly
> easily.
The transformation is no problem, like
xsltproc --nonet stylesheets/plainhtml.xsl gimp.xml
and it'll create a directly placing all HTML files.
But this it what it looks like after the transformation:
egger@sonja:/devel/gimp-help-2/help/C/plainhtml$ ls
ch01.html ch03s04.html ch03s09.html ch03s14.html gimp-help-plain.css
ch02.html ch03s05.html ch03s10.html ch03s15.html go01.html
ch03.html ch03s06.html ch03s11.html ch03s16.html index.html
ch03s02.html ch03s07.html ch03s12.html ch04.html
ch03s03.html ch03s08.html ch03s13.html ch04s02.html
Now try to map that mess to something sensible in the GIMP. Consider
that I can change the name of either all ch[0-9]+.html *or*
ch[0-9]+s[0-9]s.html to something more usable, but not both. Also the
name of the glossary, which would be go01.html here is fixed. Changing
the granularity would mean less files which would mean that all data is
munched into fewer files resulting in even fewer targets to link to.
And I'm not even talking about navigation to the point here. The
chapters will only contain a description of the chapter or even just
links in case the author was lazy while the section files only contain
the content of exactly that one section. If you want to have both
because you'd like to link to a chapter (this can be transferred to any
other structural element as well) you loose.
--
Servus,
Daniel
Attachment:
signature.asc
Description: Dies ist ein digital signierter Nachrichtenteil
