*) Which DTD?

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.

In a message from Norman Walsh on DocBook-apps 
< http://xml.org/archives/docbook-apps/2000/06/0008.html >:

> This is pretty funny...  After convincing you (rightly, I think) that
> you should move to XML, we must now tell you that XML is in fact SGML.
> (At least for the time being.)  [...] You can process XML files with
> SGML tools (like Jade and the DSSSL stylesheets) [...]

*) Which top-level element for filter help?

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.

Note: The GDP chose to use "sect1" for their applets, and an applet is
kind of like a filter, maybe...

*) ID naming conventions.

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.

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).

*) Organizational Heirarchy

This is a part of DocBook I don't know much about.  How do I make it
clear that "I am one of many Pattern filters, which is a group of
Rendering filters, etc..." so the correct navigational links get set
up?  I guess if the help is processed as One Big Document, the structure
of the document will reflect that, but that won't work with help files
for 3rd-party add-ons.

*) Screenshots, areas, callouts

I am not at all confident that my mixing single-entry variablelists in
to the callout list is the right thing to do.  I will have to study
callouts more.

A plug-in to help construct the <areaspec> pieces might be handy,
though reading from the crop tool with units set to % works fairly

*) Credits

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.

DocBook Questions (probably belongs on docbook-list):

Element: callout 
Attribute: arearefs
TDG says "AreaRefs must point to one or more Areas or AreaSets." 
What is the syntax to point to more than one?

Kevin Turner <[EMAIL PROTECTED]> | 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 [EMAIL PROTECTED]

Reply via email to