Remove forced line-breaking in qubes-doc

[mfc]

This breaks our ability to move content seamlessly to our translation platform Transifex and back: #1452 (comment).

If this can be implemented before March 5 this would help with a lot of manual line-break-fixing on my end in the lead-up to the spanish localization sprint.

[jpouellet]

I currently try to follow a balance between "new sentence => new line" and staying below 80 chars per line, as those rules make reviewing diffs easier.

I propose we consider not requiring giant single lines and instead attempt automatic combination of multi-line markdown paragraphs as part of the automated translation workflow of #1452, unless it proves to be too error prone.

[jpouellet]

I currently try to follow a balance between "new sentence => new line" and staying below 80 chars per line, as those rules make reviewing diffs easier.

I propose we consider not requiring giant single lines and instead attempt automatic combination of multi-line markdown paragraphs as part of the automated translation workflow of #1452, unless it proves to be too error prone.

[jpouellet]

I've created https://www.transifex.com/qubes-testing to do some simple testing without bothering anyone, and have identified a few more issues.

I definitely agree that the current "wrap at 80 chars" causes clear problems for translation (single sentences being split across identified strings), but it's not clear to me that combining everything to single paragraphs is what we want either. If we have a large paragraph which has been translated, then make a commit to fix a little typo somewhere in the english version, the whole thing gets marked as needing translation again. If however we split strings by sentence, then it is less work for the translator.
As for languages not necessarily having a 1:1 mapping in number of sentences to convey equivalent meaning, I think this can be handled by simply having some sentences translate to empty strings, and others translate to multiple sentences (which works fine as long as their translations are entered on a single line).

Also, our style of

some [link name] in sentence

[link name]: url

causes problems when the [ contents ] are translated without exactly matching the link again.

[jpouellet]

I've created https://www.transifex.com/qubes-testing to do some simple testing without bothering anyone, and have identified a few more issues.

I definitely agree that the current "wrap at 80 chars" causes clear problems for translation (single sentences being split across identified strings), but it's not clear to me that combining everything to single paragraphs is what we want either. If we have a large paragraph which has been translated, then make a commit to fix a little typo somewhere in the english version, the whole thing gets marked as needing translation again. If however we split strings by sentence, then it is less work for the translator.
As for languages not necessarily having a 1:1 mapping in number of sentences to convey equivalent meaning, I think this can be handled by simply having some sentences translate to empty strings, and others translate to multiple sentences (which works fine as long as their translations are entered on a single line).

Also, our style of

some [link name] in sentence

[link name]: url

causes problems when the [ contents ] are translated without exactly matching the link again.

[jpouellet]

Looks like there have been previous attempts to do round-trip conversions from markdown => json k/v pairs => markdown specifically for use with transifex: https://iilab.github.io/contentascode/technology/translation/

[jpouellet]

Looks like there have been previous attempts to do round-trip conversions from markdown => json k/v pairs => markdown specifically for use with transifex: https://iilab.github.io/contentascode/technology/translation/

[unman]

If you do this you will remove one of the key benefits of using markdown, that it is easily readable. The current style guide calls for a hard wrap to maximise accessibility and readability. I think it should be retained, and would be strongly opposed to the proposed change.

[unman]

If you do this you will remove one of the key benefits of using markdown, that it is easily readable. The current style guide calls for a hard wrap to maximise accessibility and readability. I think it should be retained, and would be strongly opposed to the proposed change.

[marmarek]

Normally I'd say I agree with @unman. But while it's easy to turn on line wrapping in editor/viewer, hard line wrapping in source files pose major problem for translations. And actually for meaningful diffs too (re-wrapping makes diffs mostly useless).

So, if we can have easily some workflow for uploading non-wrapped text to transifex (or some middle ground like @jpouellet described), while still keeping original files wrapped, then ok. But if not - implementing this ticket makes life much easier for translators at not so high cost for others.

@andrewdavidwong what's your opinion here?

[marmarek]

Normally I'd say I agree with @unman. But while it's easy to turn on line wrapping in editor/viewer, hard line wrapping in source files pose major problem for translations. And actually for meaningful diffs too (re-wrapping makes diffs mostly useless).

So, if we can have easily some workflow for uploading non-wrapped text to transifex (or some middle ground like @jpouellet described), while still keeping original files wrapped, then ok. But if not - implementing this ticket makes life much easier for translators at not so high cost for others.

@andrewdavidwong what's your opinion here?

[andrewdavidwong]

I'm in favor of changing our policy from hard wrapping at 80 characters to inserting a newline at the end of each sentence. This mostly preserves source readability, results in the most useful diffs, and is easiest for translators.

[andrewdavidwong]

I'm in favor of changing our policy from hard wrapping at 80 characters to inserting a newline at the end of each sentence. This mostly preserves source readability, results in the most useful diffs, and is easiest for translators.

[andrewdavidwong]

As for problems with our reference-style links (#2639 (comment)), I think the solution there is to ask translators to translate both occurences of the reference (i.e., copy and paste).

[andrewdavidwong]

As for problems with our reference-style links (#2639 (comment)), I think the solution there is to ask translators to translate both occurences of the reference (i.e., copy and paste).

[andrewdavidwong]

@mfc: I can't tell whether you intended #1452 or this issue to track the actual line break changes (as opposed to the policy change). I intepreted this issue as being only for the policy and #1452 as being for the actual line breaks in the source, so I've closed this one. If that's not what you had in mind, feel free to re-open.

[andrewdavidwong]

@mfc: I can't tell whether you intended #1452 or this issue to track the actual line break changes (as opposed to the policy change). I intepreted this issue as being only for the policy and #1452 as being for the actual line breaks in the source, so I've closed this one. If that's not what you had in mind, feel free to re-open.