Hi,
> > Format issue 1: DocBook or HTML?
> > ================================
>
> > Points in favour of DocBook:
> > * Can be pushed to a variety of output formats with existing tools.
> > * Is more searchable and indexable and whatnot, using hypothetcial
> > tools. (If you can point to stable packages that index and
> > intelligently search docbook, I'll take that "hypothetical" back.)
>
> That's not the point, but you can also automatically create
> crossreferences and also something like:
>
> Sorry, this page hasn't been written in <Language> yet. Would you
> like to read this help in <available Languagelinks> instead?
As you might have noticed the creators of the help system have already
thought about that. The current help-system does not yet support
multi-language
help files, but the current directory structure and the code should allow to
add this feature anytime with little effort. Our plan so far was to use a
simple
shell-script to create links to english pages where other translations are
not yet done.
AFAIK there is no DocBook browser and we certainly don't want to write one.
The format is not even intended to be browsed directly. Creating HTML from
it will (at least in the short term) be the right thing to do.
I'm all for using DocBook to create the help files if and only if the help
authors feel comfortable with it, someone who knows DocBook and all that
stylesheet stuff volunteers to help and Yosh as the gimp maintainer gives
his OK, since he will have to build the releases. I'll help as much as I
can to create the necessary framework. As you might have noticed we already
use DocBook-SGML to create the libgimp API reference.
> > 1) This adds significantly to the time and tools the maintainer
> > requires to make a release.
>
> Tools: yes, Time: I doubt that. Automatically processing text makes
> things faster not lenghtier...
If you would have ever used Jade, you'd know that it adds a significant
amount of time. Processing SGML is a very CPU-intensive and time-consuming
task (at least with the available tools).
> > 2)
> > Making the output look good will require a non-trivial amount of
> > work on the transformation stylesheets. That's a relatively rare
> > skill, so finding someone to do that might be difficult.
>
> It's not that hard. I could do that...
Do I read, you could do that, or you will do that??
> > Everyone probably agrees that we shouldn't have a different background
> > colour for every help page. It might also be nice if there was some
> > organizational consistancy from page to page. Also, is there anything
> > that shouldn't be in the help file, or should always be in seperate
> > files? For instance, should information about using the plug-in
> > non-interactively not be displayed in the same file as the rest, to
> > avoid exposing the user to "scary pdb stuff"?
I'd vote for a plug-in API reference separated from the normal users help.
This API reference could be automatically created from the plug-in sources.
But please let us concentrate on finishing the libgimp API reference before
we start another project.
> > "GIMP doesn't *need* help files to run, so they can be
> > distributed seperately."
>
> That's just a fraction of my argument. I've no problem with
> shipping GIMP with online help. I just think it's better
> to keep the source archive smaller since the onlinehelp shouldn't
> depend on the source and thus can without any problem reside outside
> of our maintree which would make maintainance easier IMHO...
What advantage would we have if the help files are stored separately if
the release is going to include it anyway? Anyway, the one who creates
the releases should decide that.
Now to a few things Kevin pointed out in his first mail that I haven't
dealed with so far:
> ** Speaking of the help browser:
> I don't really know what the qualities and status of gimp's help
> browser are, or why we have our own instead of passing the job to the
> user's favourite browser. I vaugely remember some noise about "Oh, we
> need our own help browser because it is going to have special
> navigational things for our help architecture," so I let that issue
> slide, but since those people have largely signed off the project, do we
> need to re-think these questions?
The advantage of the helpbrowser plug-in is it's speed, small screen estate
and small memory footprint. I guess a lot of people are very happy that they
do not have to use their "favorite" browser since it's a huge memory-eating
monster that takes ages to start if GIMP is already running. For those of
us that are happy with their browser, they can continue to use it. At some
point we might consider adding another option, namely a gtkhtml-based
helpbrowser or interfaces to the GNOME and KDE help-systems. As all this
is implemented as a plug-in it should be trivial to do so.
> Egger argues, "GIMP doesn't *need* help files to run, so they can be
> distributed seperately." Why? It's the "Who has cvs.gnome.org
> write-access?" song again. But it's only been three days since Piers
> (our new Help-guy) requested write access, so I don't feel that's a
> cause for alarm yet.
He did not even ask for write access. I have offered him to ask the relevant
people so he can get write access. Until now I have not managed to reach
them, but as you might have noticed, I have taken care of putting the first
bunch of files into CVS and will continue to do so.
Salut, Sven
