Hi,
Managing xml file is difficult; they are getting hard to read. Adding
all this stuff will worsen the situation.
I agree, help user must know the author's name : but do you know who
wrote most of files first?
I think it's not necessary to have the dates of all modifications in the
history. Only the last one is useful: "Last review (en;fr)..."
Changes in the html structure are not interesting for help user, nor
typo corrections, but they may be interesting for the help writer.
So, we may have two histories:
- a history for help users, with only the author's name and last
revision, that appears in html file.
- a history between <!-- --> tags for doc writers.
atb
Julien
Roman Joost a écrit :
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
------------------------------------------------------------------------
_______________________________________________
Gimp-docs mailing list
Gimp-docs@xxxxxxxxxxxxxxxxxxxxxx
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs
_______________________________________________
Gimp-docs mailing list
Gimp-docs@xxxxxxxxxxxxxxxxxxxxxx
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs
