Hi,
I'm not sure if we already discussed this but I want to make a proposal
for editing notes. The metadata we're currently adding with comments can
be moved to the designated metadata elements. The advantage here is to
provide the reader with detail information about what happened with the
document in the past. This information is currently not provided.
To achieve this, I propose to transform the following example comment
into the following structure (used it from toolbox/tool-airbrush.xml):
<!-- section history: -->
<!-- 2005-11-27 changed to figure and sect3 -->
<!-- 050522 de reviewed by axel.wernicke -->
into:
<sect2info>
<author>
<firstname>Roman</firstname>
<surname>Joost</surname>
</author>
<editor>
<firstname>Axel</firstname>
<surname>Wernicke</surname>
</editor>
<edition>$Id$</edition>
<revhistory>
<revision>
<revnumber>1.42</revnumber>
<date>2005-11-27</date>
<authorinitials>lexa</authorinitials>
<revremark>changed to figure and sect3</revremark>
</revision>
<revision>
<revnumber>1.41</revnumber>
<date>2005-05-05</date>
<authorinitials>lexa</authorinitials>
<revremark>de reviewed</revremark>
</revision>
</revhistory>
</sect2info>
The author element specifies who initially wrote the document. The
editor element who edited it afterwards. If proof readers mailed us
fixes, we should put them into a <contrib></contrib> element. The
edition is filled in with a CVS specific variable, which is expanded
during the checkin of the XML document. Afterwards it looks like this:
$Id: gimp-tool-airbrush.xml 1.42 2005-11-02 08:52:25Z romanofski $
The revhistory holds the equivalent entries of the current comments.
The revnumber should be the last revision number added by the CVS (every
docwriter can look it up in the edition tag). Unfortunately this element
is necessary. In my opinion, the date is enough for our needs.
The disadvantage can be the verbosity. Having a big header of metadata
is difficult to maintain. I propose, that we only hold five revision
entries there. If the reader needs more information he can use other
resources like the ChangeLog. I want to emphasise, that the info element
shouldn't be used *as a ChangeLog*. Just a quick description about what
has changed in the past and when it happen (like it is used now).
I would like to hear the opinion from other people.
Greetings,
--
Roman Joost
www: http://www.romanofski.de
email: romanofski@xxxxxxxx
Attachment:
pgpl1kITTZ27N.pgp
Description: PGP signature
_______________________________________________ Gimp-docs mailing list Gimp-docs@xxxxxxxxxxxxxxxxxxxxxx https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs
