Newline or Not To Newline -- what's best for explanatory source text?

[psherman42]

For consistent look and feel across all .adoc source files, is it best to keep each line short, entering hard-return newlines at horizontal character position 72 like in the old days with punch cards; or let lines run and wrap freely, where newline serves as indicator of new paragraphs.

In favor of the former, short source lines are very easy to read, without horizontal scrolling, on very simple browers and CLI screens using, for example, vi(m).

In case of the latter, it makes commenting-out a block very easy: only one comment character is needed at the beginning of the (very long) line.

The latter, long-line style, also favors document translation and localisation ease. The line above (or below) can be the un-translated source phrase easily. It makes very clear the precise basis and nuance for the particular target/translation phrase, and traceable point of reference. For example, with Thai, assuming '%' is the comment symbol, %Sometimes life is too sharp. บางเวลาชีวิตก็ทารูณโหดร้ายเกินไป Because there are no spaces between words in Thai, artificially putting spaces in the source text is awkward, at best; and mis-leading (or complete meaning changing) at worst.

Whichever style is preferred -- max-line-length with carriage returns or freely flowing sentences or paragraphs -- we might want to impose document stylistic suggestions for the .adoc template and stick with them.

[wmat]

I've been thinking about enforcing ventilated prose It makes text stored in source control easier to generate changesets against and much easier to translate I've yet to try this out though, but have it on my list of things to do.

[psherman42]

Very interesting and just the point of consistency I was thinking about. Never knew of this fascinating history.

Very good point of the current practice of artificially keeping short "punch card" lines, "... And those reflows usually inflate the diff. Changing a word at the beginning of the paragraph can cause every line in the paragraph to shift." When you happen to add a long phrase at the beginning, you have to take time to reflow all later lines. The diff-set is also a nightmare. The only time it's valid to do that is

    int rough_consensus;
    char running_code;
/*---------------
   when you have a large comment block in actual
   code and you want it to preserve good aesthetic
   form in your program source code.
---------------*/
    if (rough_consensus && running_code) return;

or equivalently,

    int rough_consensus;
    char running_code;
// when you have a large comment block in actual
// code and you want it to preserve good aesthetic
// form in your program source code.
    if (rough_consensus && running_code) return;

The semicolon, or "super comma" as I learned in Grade School does not receive newline ventilation, because its sentence components are part of the same broad idea:

In ventilated prose, each sentence gets its own line; similar to how we put each statement on its own line in code.

It's akin to placing multiple code statements on a single line:

x = read(); x = modify(x); write(x);  // atomic, of sorts

This is precisely how Thai language is written, since there is no period and no full-stop; a space delineates the change from one idea to the next.

I believe ventilated prose is the most natural way to write. It aligns best with how we think, which is per sentence / point. And thanks to our digital writing environment, we can do this without altering how the text is displayed.

It also makes easier writing in or translating into other languages which are not subject-verb-object, but rather subject-object-verb. In Thai you say กุญแจบ้าน [kune jae bahn] (lit., key house) when you mean house key.

(Of course, it's never okay to begin a sentence with and, or, but; nor end a sentence with for; that's what while and however are for, although.

A very good reminder is William Strunck and E. B. White's quintessential paragraph,

Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all sentences short or avoid all detail and treat subjects only in outline, but that every word tell.