Change Typographical Conventions to Style Guide

[stevepiercy]

Establish a Style Guide for Pyramid narrative documentation as a reference. It excludes docstrings or comments in code.

The Style Guide would not be implemented immediately over all pages, but would be implemented as each section or page of the narrative documentation is reviewed or updated over time.

Note: "Adopt" in the list below is in reference to the Plone ReST Styleguide.

References

• Typographical Conventions
• Plone ReST Styleguide

Changes

• Rename Typographical Conventions to Style Guide.
• Add reference for how to build docs locally.
• Add reference for how to update and contribute to docs.
• Introduction: convert to paragraphs from note, break into an actual Introduction and sections for filenaming and image formats (see below).
• Adapt "Images".
• Use one line per paragraph and no longer restrict to 79-character limit on prose.
• Adopt "Document page format".
• Adopt "Tab policy".
• Adopt "Headings and filenames", but move filenames to separate section (see above).
• Adopt "Page structure", except for "contents directive".
• Adopt "Section structure".
• Adopt "Headings style guide".
• Adopt "Links".
• Adopt "Topic", while dropping sidebar.
• Adopt "Syntax highlighting", except no more ::, and make it required to specify language.
• Add emphasizelines, linenos, include, and other code-related things.
• Adopt "Other Sphinx and restructured text source snippets" as "Typographical Conventions", merging current content of Pyramid's "Typographical Conventions".
• Add admonitions seealso (and others?).
• Exclude "Including gists".

[tseaver]

"Semantic linefeeds" smell like an overall negative to me:

• Nobody writes real prose like that.
• It hurts readability of the source, which ends up looking like lit-magzine prose-poetry.
• It has no effect on rendered output, which is where the value should be.

[stevepiercy]

Consider the following rst sample source:

This is the first paragraph and it consists of one sentence on one line.

This is the second paragraph and it consists of five sentences on five lines.
This is an example of what I intend with modified semantic linefeeds.
One complete sentence per line.
This would be applied only in narrative documentation.
It would not—*absolutely not*—have any silly linefeeds after clauses, lists, Oxford commas, or colons as in the following example:

* This is a list of things.
* Fruits include apples, oranges, papayas, bananas, apricots, plums, nectarines, peaches, pears, and mangoes.
* Asparagus is a vegetable.

• This makes it much easier to do diffs on narrative docs. When I have had to change a single word in a multi-sentence paragraph, I have had to rewrap the entire paragraph, making it very difficult to pick out the single typo, word, phrase, or punctuation fix. Instead I have to compare a big red block of text against a big green block of text. See example in https://github.com/Pylons/pyramid/pull/2637/files#diff-7388f30072c94948c00ad2dfe1c30f03L17
• I typically do not write prose by hard wrapping (hitting return) at 79 columns. I typically use soft-wrap in my editors when writing prose or narrative stuff. Only because Pylons Project requires 79 columns do I hard wrap my prose after I have composed it, and often multiple times as I rewrite and jump about in the narrative docs. I don't think 79 columns should be applied to narrative or prose. For code, yes, absolutely, 79 columns is a good thing.
• Rewrapping of paragraphs would no longer be necessary because you no longer have paragraphs. A paragraph in .rst is rendered with two linefeeds, not one. Thus the above sample would be rendered as follows:

This is the first paragraph and it consists of one sentence on one line.

This is the second paragraph and it consists of five sentences on five lines. This is an example of what I intend with modified semantic linefeeds. One complete sentence per line. This would be applied only in narrative documentation. It would not—absolutely not—have any silly linefeeds after clauses, lists, Oxford commas, or colons as in the following example:

• This is a list of things.
• Fruits include apples, oranges, papayas, bananas, apricots, plums, nectarines, peaches, pears, and mangoes.
• Asparagus is a vegetable.

I hope that clarifies my intent.

[stevepiercy]

Here is an example of a horrendous diff because of rewrapping to 79 columns, as mentioned above. Can you find what was changed?
https://github.com/Pylons/pyramid/pull/2637/files#diff-7388f30072c94948c00ad2dfe1c30f03L17

[mmerickel]

If we want to do one paragraph per line that's fine with me. I'm also semi-okay with one sentence per line but paragraph sounds better to me. I am absolutely against just randomly breaking sentences into lines for "semantic reasons" because no one will understand the rules. I'm also fine with keeping the current 79-character width requirement instead. Also note that this only applies to rst docs, and NOT docstrings that use rst in code (they are both human consumable as well as in code files with strict 79-char limits). I would also be against applying these rules to README.rst and HACKING.rst which are very often human consumable.

[stevepiercy]

I put some thought into this and rubber ducked it on IRC. I've updated the issue description, and created a detailed checklist at the top. I think this would work well for everyone. Feedback appreciated.

[miohtama]

+1 for terminating paragraph with a new line.

Because that's how all word processors since mid 80s have functioned. That's how we were taught in the school on the sixth grade. Enforcing a line length makes it harder to edit paragraphs and doesn't make sense in the context of prose, as all sane editors, including Github, have been able to wrap lines tidily forever. Even vim.

Instead, too short lines make it hard for people, who are used to wider text editor areas, work with the text as they spend extra time to manually adjust line length to make it look nice.

Let's leave line length discussion to source code files and let's write English as we were taught in school.

[stevepiercy]

@tseaver @bertjwregeer I've updated the checklist, the significant change being this item:

• Use one line per paragraph and no longer restrict to 79-character limit on prose.

If you have no objections, I will proceed on this item.

[stevepiercy]

Work for this issue is in the branch style-guide.

[stevepiercy]

Closed by #2838