Re: [Gimp-docs] Proposal for Metadata

Axel Wernicke <axel.wernicke@xxxxxx> · Sun, 18 Dec 2005 15:12:12 +0100

Hi Roman,

to be honest I don't see the benefit of changing the kind of comments  
we do by now. The information is almost the same, but due to that  
huge surrounding docbook structure it's very hard to read in the  
source. Right now I'd prefer to stick to the way we are doing it  
today, but may be you can convince me.
I'd like to focus on how to make contributing easier - we could need  
some more editors, and right now writing content is very technically.  
To deal with all that docbook stuff is more like writing source code  
than like writing a book. I'd be very open minded to see proposals on  
how to change that.

Greetings, lexa

Am 18.12.2005 um 12:44 schrieb Roman Joost:

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

---
Live is like a chocolate box, you never know what you wanna get...
GPG Signatur auf http://wernicke-online.net/Impressum/ prüfen

Attachment:
PGP.sig

Description: Signierter Teil der Nachricht
_______________________________________________
Gimp-docs mailing list
Gimp-docs@xxxxxxxxxxxxxxxxxxxxxx
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs