Switch to one sentence per line?

[psalz]

I'd like to propose switching to "semantic linefeeds", i.e., having one sentence per line.

The spec currently mostly uses a 80-ish character limit, like in the olden days. Imposing a limit might make sense for program code, but for text it doesn't, in my opinion. One issue this introduces is that it is more difficult to CTRL+F something in the spec source, as a sentence might randomly contain a line break. In some places on the other hand, entire paragraphs are written without a single line break.

Both of these styles are not ideal from a version control perspective, as changing a single word can often cause large diffs spanning several lines, making it difficult to see what exactly has changed (yes, I'm aware there's word-diffs, but still), and may result in annoying merge conflicts.

Some might argue that having hard breaks between line-wrapped sentences makes the adoc source more difficult to read. This may be true for prose, but for a specification, where sentences often are more akin to disjoint enumerations of rules, it makes it easier read, in my opinion.

Here's an example from Table 103. Parameterized USM Allocation Functions, which currently uses a 80 character limit:

After changing it to one sentence per line:

And here's a paragraph from Table 143. Hidden friend functions of the vec class template, which currently has multiple sentences per line:

After adding line breaks after each sentence:

Yes, it's no longer as "neat", but IMO it is much easier to find a relevant sentence when quickly looking over it.

Thoughts?

[gmlueck]

I've been thinking about this too, and I've recently been writing the DPC++ extension specifications with a variation of semantic linefeeds. With this variation, I've been putting a line break at the end of every sentence and also at the 80 column mark. So far, it's been working pretty well. When there are changes to wording, the "diff" only shows the lines of sentences that changed. Other lines in the paragraph are unaffected. The 80 column limit helps keep the text more readable in the source file.

[nliber]

Sounds good to me.

[oddhack]

I've also found that keeping markup lines short eases viewing commit diffs in gitlab/github.

[keryell]

For me ASCIIdoctor and even more LaTeX is actually a program. ;-) Today there are 2 coding styles in use in the specification, originated from Windows-tooling Codeplay with long lines and my AUC-TeX Emacs-based 72 columns style + empty line to break paragraphs. Most of it was preserved during LaTeX to ASCIIdoctor conversion. Since we are cleaning things up, a uniform coding style seems like a good idea.

[gmlueck]

I think we have completed this, so I'm closing this issue. Feel free to reopen if you think more needs to be done.