Lack of a strict formatting style for XML

[Rocco Stanzione]

On Thursday 30 March 2006 15:25, Matthew East wrote:
> On Thu, 2006-03-30 at 15:39 -0500, Alexandre Vassalotti wrote:
> > While editing the documentation, I remarked a lack of style
> > consistence in the DocBook source files. For example, check
> > how the <para> tags are indented.
> >
> > I propose that we append a indentation style into the
> > Styleguide. Then, we could distribute a list settings for different
> > text editors. (ie. Emacs and VIM) Just like Linux did with their
> > Coding Style. This would ensure the readability and ease the
> > maintaining of the documents.
>
> I suppose we can run the documents through "tidy" or something. I don't
> know whether we should enforce this strictly, eg through the styleguide,
> because not everyone has time to be careful about this stuff and not
> everyone uses an editor which supports these settings (I use gedit,
> which I don't think has such an option). What do others think?
>
> > Along this, a list of the commonly used DocBook tags with a example
> > for each would be greatly appreciated by new writers. This would make
> > the DocBook format more accessible and would encourage a consistent
> > style in the sources.
>
> See https://wiki.ubuntu.com/DocumentationTeam/DocbookTags

As Matt mentioned there is a wiki page for commonly used docbook tags, but I 
think it could use some work.  If no one beats me to it, I have a plan to 
(once I get more comfortable with docbook and what it can do) extend that 
page significantly and then to go through our docs and identify opportunities 
to better take advantage of some of what docbook can do.  As far as adding 
things like indentation to the styleguide, I'm personally ambivalent.  To me, 
once something's in the styleguide it's to be adhered to carefully, and I 
don't know what's important enough to be included there; however, one thing 
that I've frequently found troublesome when editing the docs is very long 
lines.  Since I use a console text editor, it's more time consuming to get my 
cursor where it needs to be on very long lines than it is where lines are 
consistently, say, 80 characters wide.  Those are all the opinions I have on 
this topic.

Rocco Stanzione