Re: gedit Docs Coding Guidelines

[Phil Bull <philbull gmail com>]

Hi Daniel,

Great to hear you're working on the gedit docs! Please let us know if
you need any help with the conversion - reworking a manual into
topic-based help can become quite an involved process.

On Fri, 2010-12-17 at 21:31 -0500, Daniel Neel wrote:
> 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.

Yes, that's definitely a sensible policy. You'll probably find it
difficult to get people to stick to a 2-space indent policy, but that
shouldn't matter too much. The main thing is that it's easy to read the
markup.

> 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.

You can use a tool like "tidy" to automatically do this for you. It has
an XML mode.

> 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.

This is reasonable (I normally go for the latter).

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

> 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.

I've been using one revision tag and however many credit tags for each
topic. The credit tags are useful for keeping track of copyright when
the files are distributed, but (as you said) with git it's not necessary
to keep multiple revision tags.

> 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?

Defining a few basic guidelines can be a good idea, but don't go
overboard! If you try to legislate coding style too much it becomes a
pain for reviewers and contributors. I'm a fan of using broader guiding
principles instead - in this case it would be "keep it readable"!

Thanks,

Phil