Skip to content

WIP: Reformat HIG using one-line-per-sentence convention

Jan Blackquill requested to merge work/janb/reformat into master

This is a convention used by various projects such as the Fedora Docs project and the Asciidoctor docs generator. In short, it means that every line exactly one sentence, and exactly one sentence.

From https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line:



Here are some of the advantages of using the sentence per line style:

    It prevents reflows (meaning a change early in the paragraph won’t cause the remaining lines in the paragraph to reposition).

    You can easily swap sentences.

    You can easily separate or join paragraphs.

    You can comment out sentences or add commentary to them.

    You can spot sentences which are too long or sentences that vary widely in length.

    You can spot redundant (and thus mundane) patterns in your writing.

Besides these benefits, it also makes git diffs easier to parse and understand, as git diffs work on a line-by-line basis. When you make your sentences 1:1 with lines, you get git diffs that work on a sentence-by-sentence basis.

Edited by Jan Blackquill

Merge request reports