Hi,

Am 13.01.2006 um 11:43 schrieb Roman Joost:

Hi!

As a result of our last discussion to display metadata at our document headings and refering additionally to bug[1] #168255, I want to propose
to add the following metadata.

We include revision, date and author for only the *last revision*. This
is automatically filled in by CVS, once we added the code example listed
below. It'll look like this (using sect1 as an example here):

$Revision$
$Date$
romanofski

OK, this directly leads to the question which elements we should to this for. Since there is no such thing in docbook as "pages", we have to decide for a level of sect I'd suppose. How about doing it for sect1 and sect2 elements?
By the way, it's valid not to have a revremark element.

The revremark element is left blank. I'm not sure if we should keep the
version history via comments and put a remark about the last changes in the revision tag.

So there we have the second important issue. As far as I see the usage of revhistory as proposed here has not the power to replace the remarks done for authoring in the head of each file. This is because your proposal gives the reader of the manual a date which he knows then is the least age of the content. Additionally he gets the revision - whatever that will tell him. It's neither language specific, nor does it contain the information about what changed in the content of a file at a specific time. So, whether we extend the revhistory to something like:

$Revision$
$Date$
cvs

2.2.10
2006-01-13
lexa

de: added translation for de an made file docbook compliant

2.2.10
2005-11-28
lexa
Replaced informalfigures by figures

2.2.8
2005-09-05
????
Added Making a selection semi-transparente</ revremark>

which is pretty verbose, but can replace the comments with something machine readable.
Or we stick to the comments as they are and do the sectinfo thing additionally.

A 'cvs' role will help us to filter out the metadata information, if we
need it.

Currently, DocBook renders a table which looks not very nice. I could rewrite the transformation of the revhistory to display the metadata as
a small box, which is grayed out or something like this.

[x] go ahead with this

Feel free to comment. If no one disagrees I'd like to add this in a few
days.

commenting done :)

Greetings, lexA

Greetings,

Am 16.01.2006 um 17:12 schrieb Roman Joost:

On Fri, Jan 13, 2006 at 08:02:55PM +0100, Axel Wernicke wrote:

We include revision, date and author for only the *last revision*. This
is automatically filled in by CVS, once we added the code example listed
below. It'll look like this (using sect1 as an example here):

$Revision$
$Date$
romanofski

OK, this directly leads to the question which elements we should to this for. Since there is
no such thing in docbook as "pages", we have to decide for a level of sect I'd suppose. How
about doing it for sect1 and sect2 elements?

Sounds good for me, I propose to include additionally 'book, part, chapter, preface,
index, appendix'. So, the list grows to:

'book, part, chapter, preface, index, appendix, sect1, sect2'

[x] agreed

By the way, it's valid not to have a revremark element.

Oh, that would be nice. Are you sure? I tested it and it gave me an error, but could have been my fault. Haven't investigated more ...

well, double checked that and - it seems indeed to be valid --> revision ::= (revnumber,date, (author|authorinitials)*, (revremark|revdescription)?)

The revremark element is left blank. I'm not sure if we should keep the
version history via comments and put a remark about the last changes in the revision tag.

So there we have the second important issue. As far as I see the usage of revhistory as
proposed here has not the power to replace the remarks done for authoring in the head of each
file.

I proposed to use only the last revision, because the last discussion turned out, that most authors don't want to write the each change in a revhistory element. I'm fine with that. Keeping the comments as a small
changelog for each article isn't that verbose as it would be, if we use
XML.

Its OK, so lets stick to the little xml comments for a short description of the most recent changes on content and use the revision elements for kind of a cvs revision mark.

This is because your proposal gives the reader of the manual a date which he knows then
is the least age of the content. Additionally he gets the revision - whatever that will tell
him.
It's neither language specific, nor does it contain the information about what changed in the content of a file at a specific time.

Is this really important? It is more important for the reader IMO, that
he reads an up-to-date document and not the first draft of one article.
Therefore having a revision and a date is much more interesting than what was changed in the last revision.

Btw. why do you want to provide language specific revision logs?

Lets say we have a file containing en and a fr translation. Content for booth is ages old.
Then somebody gratefully updates the en part and whops, the whole thing gets a new recent and shiny cvs revision. Also for the fr part which was not touched for ages.
Anyway to have some sort of revision and date is better than nothing. So lets go for it.

So, whether we extend the revhistory to something like:

[...] example with more than one revision elements

which is pretty verbose, but can replace the comments with something machine readable.

Hm.. no... let us keep the comments...

well, it was just an idea. I can live pretty well with the comments.

Greetings and thanks for all the efforts you put into this!

lexA

Greetings,