Lack of a strict formatting style for XML

Alexandre Vassalotti avassalotti at gmail.com
Sun Apr 2 00:14:45 UTC 2006


On 3/30/06, Matthew East <mdke at ubuntu.com> wrote:
> 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

We could use a non-interactive program to do the work, like GNU indent
or Tidy, and make it run as a cron job. The script would probably do
this:
   1. Check out the docs from SVN
   2. Clean and indent
   3. Validate
   4. If all went ok, commit it

Personally, I don't like the idea but it could used as a last resort.


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

Then, we could also distribute an GNU indent script or at least get
the peoples make the correct indent by hand.

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

This page doesn't show examples about how to use those tags. It just a
list of tags with no relations between them. What I'm talking about is
a page showing a XML file with all the commonly used tags, much like
the Convention section in the preface file. I practically learned
DocBook from this file. So, it would be a good idea to teach the
DocBook basics with a file like that.

On 3/31/06, Rocco Stanzione <grasshopper at linuxkungfu.org> wrote:
> 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.

Yet another thing that was bugging me about the inconstancy,
especially in the <para> tags. The coding style should include a max
line width, too.

--
Alex V.




More information about the ubuntu-doc mailing list