On Wed, Nov 15, 2006 at 11:33:01PM +0100, Torinthiel wrote:

I will (time and laziness permitting, so don't hold your breath too much) try and reformat the XML documentation to stick to some common guidelines. Problem is setting those guidelines.

My propositions are:

<sect1>: before each sect1 there's a line of <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> with two blank lines before and two after.

<sect2>: before each sect2 there's <!-- ********** --> with blank line before and after.

I think just a few blank lines, maybe 3, will do the trick as well, but I'm not very particular about this.

<sect3>: two blank lines before.

<title>: Each title goes just below it's corresponding tag (<sect?>, <formalpara> or whatever), and stays in one line (this can mean the line can get very long).

Nah, I'd say the lines can be broken.

<para> start-tag and end-tags in separate lines, don't indent the content (more than <para> itself is indented, that is).

Fine with me.

Things like tables, lists etc: start and end tags in separate lines, increase indent by 2 spaces, item start and end tags as well in separate lines (but when whole item contains a single <para> or something like that than this <para> goes with element start tag.

Fine with me.

All 'small' tags (title, ulink, link, application, keycap, etc.) fit in a single line.

Line limit of 80 characters (With exception of small tags above).

Fine with me.

<screen>: either in single line, like small tags or like this: <screen> text (with no indent) \ maybe continuation of a longer command (indented)<!-- --><screen>

with <screen> and --> beginning at the current indentation level.

Fine with me.

Any comments? Objections? Better formats? Clarifications? I'm not very much attached to this, we just have to start at something and this seems to be mostly how the doc's are formated now.

Such a reformatting would be welcome. Go right ahead. Diego