On 30 Jul, Kevin Turner wrote:
> 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?
> 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...
> 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...
> * Intimidation factor. Contributers are more likely to know HTML
> than DocBook, and may not be willing to invest in the transition.
May be right, but third party contributors can also pass pure text to
Piers or me and we'll likely convert it. BTW: It's not that hard to
learn. In this case it might be even more simple than HTML.
> 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"?
What about letting the user choose that?
> See: http://plugins.gimp.org/maze/help.html
> Is this a good style to follow, or no?
I think it's pretty good.
> Egger argues,
Please call me Daniel...
> "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...
--
Servus,
Daniel
