Split sentences on to separate lines in User Guide

[jteh]

The current English User Guide has entire paragraphs of text on a single line. This makes it very difficult for translators to see what has changed when reading a diff.

Mesar Hameed requested that we break all lines at 80 characters. However, the problem with this approach is that the text has to be reflowed when changes are made. If a change is made in the middle of a paragraph and it is reflowed, it will cause the same problem for translators reading the diff. If we don't reflow, things get messy and we then have to do occasional "reflow" commits which are just silly.

My solution is to have one sentence per line. This means that translators only have to deal with changed sentences, which are much shorter and are a logical unit to translate. Most of the more recent changes to the User Guide follow this convention already.

Note that we can't do this for tables, as txt2tags requires table rows to be on a single line. However, this should be okay, as they are normally quite short or are a logical translation unit.

The only question is how to handle %kc:setting, which uses the first line as the description for a command. If we want the description to contain multiple sentences, this won't work. I'm tempted to just leave these alone like we do for table rows for the same reasons given above.

I don't think this is important for the What's New (changes) document, as individual entries aren't often changed. Where they are, they are relatively short and are probably a logical translation unit.

I'd appreciate feedback on this.

[msuch]

Most text editors (eg. Notepad++, editPadLite I generally use for translation) have the ability to split lines by themselves.
In fact, a very long line is split in several on display but remains one internally. You can turn out the feature at any time and the text returns to single line display.
So I think this is not really a problem.

[jteh]

Replying to msuch:

Most text editors (eg. Notepad++, editPadLite I generally use for translation) have the ability to split lines by themselves.
In fact, a very long line is split in several on display but remains one internally.

The point isn't that long lines are a problem for editing. The problem is that diff works line by line, so when you have an entire paragraph on a line (which could be very long), it becomes very difficult for translators to determine what changed by reading the diff.

[orcauser]

Hi Jamie,

Thanks for this, yes I still feel this is important, and it would make a noticeable diffrence, especially to translators that depend on speech to notice the changes.
As for %kc: i had a quick look through the english user guide, and didnt notice any excessively long lines.
I dont know, but maybe a \ at the end of the line can indicate to pull up the following line? Dont know if that is even an option.
Anyway, presumibly kc lines will be more resistant to change, and once they are translated they are done, so might not be worth worrying about them for now.

One further request, is that when this work is commited, it is only the new lines that are modified, therefore when we bring ourselves up to the commit before this one we know it is actual work, and when we handle the work created by this patch, it is only new lines, and that we dont have to worry about actual text being changed.

Thank you.

Mesar or (j.orcauser)

[jteh]

Replying to orcauser:

As for %kc:
I dont know, but maybe a \ at the end of the line can indicate to pull up the following line?

I don't think that is an option with txt2tags. It's pretty ugly at any rate.
Dont know if that is even an option.

One further request, is that when this work is commited, it is only the new lines that are modified

Yup, already thought of this. It will be noted in the commit.

[mdcurran]

Fixed in changeset:main,3766.