Standardize source formatting of ubuntu-docs source xml

[Connor Imes]

Binary package hint: ubuntu-docs

The XML source for ubuntu-docs currently has no standardization, which results in a variety of formatting in the source documents. This can be troublesome when editing the docs, and quite possibly for translators as well. Some sentences span multiple lines, and in other cases a paragraph can be in one line.

I would suggest that the docs be formatted with one sentence per line. This means if a sentence is changed, only this string needs to be changed. Then there is a complete sentence structure that needs to be re-translated, rather than a partial thought or entire paragraph.

Reformatting of the source docs may be a good parallel target when switching to Mallard since strings will likely need to be re-translated at this time anyway.

[Matthew East (mdke)]

Agreed. This should become part of our new styleguide and team wiki pages.

[Matthew East (mdke)]

As for what the standard would be, I would like:

 * 80 or 100 characters per line [1]
 * Space indentation
 * As many line breaks and line spaces as you dare

For example:

QUOTE

  <list>
    <title>Other applications which support video calls include</title>

    <item><p>
      <app>Skype</app>
    </p></item>

    <item><p>
      <app>Ekiga</app>
    </p></item>

  </list>

UNQUOTE

[1] http://mail.gnome.org/archives/gnome-doc-list/2011-April/msg00041.html

[Connor Imes (ckimes)]

I think we need to establish indent parameters, too. Should we use a tab for indent, or a double space? I noticed that a lot of the gnome-user-docs pages don't have any formatting, particularly in the top sections of the document before it gets to the real material.

I also think that only the lowest level elements should be on the same line as the actual text, like you did above.
    <item><p>
      <app>Skype</app>
    </p></item>

In fact, that could be:
    <item>
      <p>
        <app>Skype</app>
      </p>
    </item>

This helps with viewing the document for syntax errors as well. Even the validation checker can be confusing when it spits out a problem, I spent a full five minutes trying to track down a silly problem today when it told me the document was invalid, and it was a small document at that.

[Jim Campbell (jwcampbell)]

On Sat, Apr 30, 2011 at 3:56 PM, Connor Imes <email address hidden> wrote:
>
>
> In fact, that could be:
> <item>
> <p>
> <app>Skype</app>
> </p>
> </item>
>
>
Does this kind of spacing affect the on-disk size of our docs? I'm in favor
of this kind of spacing, and think we need to be consistent about it, but
don't want to blow-up the size of our packages because we add an extra line
for every <p> tag that we use.

[Connor Imes (ckimes)]

Jim, it would just add some whitespace characters, the change in size should be minimal. It is better to keep the source organized at the expense of a few kilobytes than to be disorganized in order to save a few kb.