Re: gimp-help: markup conventions

[egger]

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

gimp-help: markup conventions

[Kevin Turner]

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

*) 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
question: 
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]