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
