Ok, so it looks like we need to start filling in the help files. There
are a number of things about the help files that never got decided (or
at least the decisions were never made public), because we were told
"someone else is taking care of it". But now, it looks like we've got
to hammer those things out ourselves...
Issues:
1) Format of the help files.
B) The help browser.
C) Location of the help repository.
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.)
Points against DocBook:
* We don't have a DocBook browser, so we'd have to transform it all to
HTML for browsing.
1) This adds significantly to the time and tools the maintainer
requires to make a release.
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.
* Intimidation factor. Contributers are more likely to know HTML than
DocBook, and may not be willing to invest in the transition.
Summary: I'm a believer that DocBook is the Right Thing for the Long
Run. But that doesn't necessarily mean it's the right thing for this
particular case, today.
Points in favour of HTML:
* The on-line help is really only going to be read on-line anyway.
And the only on-line browser we have is a HTML browser. So the
only thing that matters is how it looks in HTML.
Also, if our HTML browser has a limited feature set, we might need to
tweak it for that instead of using auto-generated HTML that might
assume a full implementation.
** 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?
Format issue 2: Style guidelines.
=================================
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"?
In the (two) help files I've authored so far, I've used the
time-honoured organization of the man page as a template, with the
www.gimp.org colour scheme.
See: http://plugins.gimp.org/maze/help.html
Is this a good style to follow, or no?
Location:
=========
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.
Personally, I don't want a single package of gimp 1.2 to ship without
help files bundled in. And while some of us decided that we'd like a
seperate CVS repository for plug-ins, Gnome's documentation team seems
to get along without one, so I don't know that its required.
Love,
- Kevin
--
Kevin Turner <acapnotic@xxxxxxxxxxxxxxxxxxxxx> | OpenPGP encryption welcome here
Plug-ins: They make GIMP do stuff. http://gimp-plug-ins.sourceforge.net/
This list is archived at http://marc.theaimsgroup.com/?l=gimp-developer
To unsubscribe, mail gimp-developer-unsubscribe@xxxxxxxxxxxxxxxx
