gedit Docs Coding Guidelines

[Daniel Neel <dneelyep gmail com>]

Hello all, I wanted to send a note asking for recommendations about coding guidelines for the Mallard conversion of gedit docs. I'm assuming that one rule that can be established is that tags should be nested.

IE: Rather than having

<tag1>

<tag2>

<tag3>

<tag4>

<tag4>

</tag3>

</tag2>

</tag1>

we should shoot for

<tag1>

  <tag2>  [2 spaces on all indents]

    <tag3>

      <tag4>

      <tag4>

    </tag3>

  </tag2>

</tag1>

in documents, to show the relationship of tags with other higher or lower tags. Plus the first looks pretty confusing.

So I'm going to update the wiki with this suggestion and implement this in the code. Please tell me if another method would be better - this one seems obvious enough to go ahead and implement though.

Can anyone think of any other guidelines that would be helpful for writing the docs? Two that I can think of are:

How many spaces to put at the end of a self-closing tag. IE: <tag1/> or <tag1 /> ? I vote for the second as the tag's information seems a bit less cluttered and easier to read.

And how should Mallard's <revision> tag be used? My vote goes to the following format:

  <info>

    <!-- other tags here -->

    <revision pkgversion="x" version="x.x" date="yyyy-mm-dd" status="x" />

    <credit type="x">

      <name>namehere</name>

      <email>emailhere</email>

    </credit>

    <revision pkgversion="x" version="x.x" date="yyyy-mm-dd" status="x" />

    <credit type="x">

      <name>nextnamehere</name>

      <email>nextemailhere</email>

    </credit>

  </info>

This way, each revision of the document is visually grouped with the author who revised it. The revision tags should only be used on medium-sized+ contributions. Adding 5 lines of text to the file for each change would be a headache.

Or is it even worth using the <revision> and <credit> tags, since git keeps track of the code's revision history regardless? It could be nice to have a quick overview of how development of the document proceeded, but that might also clutter the document a bit.

Otherwise there doesn't seem to be a whole lot that can be specified for writing in Mallard (that I know of at least). Thoughts anyone? Am I over-thinking this?