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?
_______________________________________________
gnome-doc-list mailing list
[email protected]
http://mail.gnome.org/mailman/listinfo/gnome-doc-list
