On 6 Aug, Kevin Turner wrote:
> gimp-help/whysgml.txt states that we are going to go through all the
> bother of writing well-formed XML files (e.g. being strict about
> always using closing tags, etc), but that we won't be actually marking
> the files as XML. If you have a grudge against xml, why bother being
> half-compatible? I'm a bit puzzled by this fence-sitting stance. If
> anyone is afraid that the XML tools are Not There Yet, remember that
> the tools that work with DocBook in its SGML form work with
> DocBook/XML too.
However the DTD you were using for the maze plugin is more like a
experimental hack. I you like to have the real XML DocBook you might
consider using the version 4.0. I personally have no problem using
DocBook/XML 4.0 versus using DocBook/SGML 4.0, however we should consider
using ONE of them for the whole project because everything else is a mess.
And the conversion from one to another is pretty simple as (like you
stated) we already conform to most of the xml conventions.
Please note, that I took notice of DocBook/XML just 5 days ago and that
it's not really advertised on www.docbook.org, thus I didn't really know
that Jade really works fine with that.
> I feel the on-line help is a reference, with distinct entries for
> specific parts of the application. A help entry for a filter is like
> a man page for that filter. I feel DocBook's "refentry" is the best
> fit for this.
Hm, I'll have a look whether that can be integrated in a seamless
fashion. If yes, why not....
> To address or link to some part of the document, that part needs to be
> tagged with an ID. How shall we organize that namespace? For
> filters, I might use their PDB name, but some filters may have more
> than one PDB entry. And much of the help system is going to be
> describing user interface elements with no PDB name, so that's
> probably not a good plan.
You normally shouldn't give subparts of your document id's and the
naming for the mainpart of it should be pretty obvious, it's the
name of the dialog or the plugin you're describing. However if you
like to link to subparts of your document give it an id like:
maze-001, maze-002 and so on... that should solve the problem. Of course
if we have a plugin with the same name like an internal function we have
to choose a different name, but that really shouldn't happen.
> There needs to be a regular way to construct a refentry's ID, and also
> a way to ensure all ID's inside that refentry are unique to that part
> of the document (so my "width" section doesn't end up pointing to
> something about cropping without meaning to).
See above. Of course you also may name this section (applied to the
maze example): maze-width.
> A man page usually has a "Credits" and/or "Authors" section. Do these
> belong in the help page? I'm guessing not, but it's not like plug-ins
> have About boxes or anything.
Are you asking about the Authors of the document or the plugin?
BTW: Please Kevin consider making a ChangeLog entry when you check
something into gimp-help, thanks....
--
Servus,
Daniel
