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

into:

Roman
Joost


Axel
Wernicke

$Id$

1.42
2005-11-27
lexa
changed to figure and sect3

1.41
2005-05-05
lexa
de reviewed

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 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@gimp.org

Am 18.12.2005 um 18:59 schrieb Roman Joost:

On Sun, Dec 18, 2005 at 03:12:12PM +0100, Axel Wernicke wrote:

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.

The advantage is, that people are able to see what happened with the article they're looking at. If the document is out of date, because the
last change was a year ago, we could probably encouraged some people to
change that. Of course a very vague assumption, but not an impossible one.

That would of course work only if the revision entries were language dependant. Otherwise If someone translates content from the GIMP stone age the document seems updated recently to *ALL* readers, but was translated to a new language only :(

I think most of the content is independent of time anyway. It simply doesn't matter if a tutorial was written yesterday or two years ago. Where time (GIMP releases) matter of course is everything that is related to the reference part of the manual. May be we should hurry up to get up to date for the 2.2 release (I guess we are not that far away from that) and then freeze and release it as gimp-help 1.0. With this we could split up the changelog (which is btw. pretty large already now) and have a sweet start for bringing the relevant topics up to gimp 2.4 then.

So if we decide to switch to revhistory elements we need to - make sure we can hide it from release html / pdf versions - make it lang dependent (how is this supposed to work with cvs??) - define in which granularity it should be done (today we do it by file, but not sect1 sect2 specific)
- introduce it step by step

Greetings, lexa

It is a very technical approach. The disadvantage about the current comments are, that our readers don't see the comments. Though we have to think about the releases. During releases we should skip to display this metadata.

Greetings,

On Sunday 18 December 2005 12:12 pm, Axel Wernicke wrote:

Re: [Gimp-docs] Proposal for Metadata Date: Today 12:12:12 pm
From: Axel Wernicke
To: Roman Joost
CC: GIMP Docs

Message was signed with unknown key 0x47D9972D5B006E24. The validity of the signature cannot be verified. Status: No public key to verify the signature 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.

That's just a great motive to change the comments to actual XM content: whatever tool one will use, it will have to read the XML content, decoding it, and later encode it back - the scripts I was trying earlier did just that, for example. The problem is: when you parse XML, you _do_not_ have access to comments. They are ignored by the parser - (unless you make a custom parser, but even there, you are violating XML specs). well..any program which does not know about the comments, obviously cannot write then back when re-encoding the document.

JS
->

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

into:

Roman
Joost


Axel
Wernicke

$Id$



1.42
2005-11-27
lexa
changed to figure and sect3

1.41
2005-05-05
lexa
de reviewed

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 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@gimp.org

------------------------------------------------------------------------

On Mon, 19 Dec 2005 07:27:56 +0100, julien wrote: [...]

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.

I agree. Most users will not care about the full revision history of each file. At most, they may be interested in what was done in the last revision or in knowing whether they have the last revision or not. For most users, it may be sufficient to have $Revision$ or $Id$ included somewhere in the generated file. A link to the latest HTML version on docs.gimp.org may also be useful if they want to compare. That link could be visible or hidden in a comment. Or maybe we could have a link to the CVS log of the corresponding source file, like this: http://cvs.gnome.org/viewcvs/gimp-help-2/src/blah/blah.xml?view=log

The doc writers have different interests than the doc users. They will probably get most of the revision history from CVS anyway. Besides what is in the CVS log, a complement in the form of a short comment in the file can also be useful (like the current comments), but I think that these comments should be optional when the changes are small and they do not need to be longer than what we have now.

Again, take my comments with a pinch of salt as I am not contributing much to the writing effort anyway.

-Rapha?l