On 5 Mar 2015, at 2:14, Glyph Lefkowitz wrote:
I find the "semantic newlines" standard which we have been attempting
to enforce for documentation a constant source of annoyance.
Ostensibly, the purpose of using semantic newlines is to reduce the
size of diffs. However, given that we have oceans of documentation
_not_ using this style, we are unlikely to reap that benefit any time
soon. Also, unlike code, documentation rarely needs small spot fixes;
a fix to a document should result in changes elsewhere within the
sentence or paragraph.
In pursuit of this questionable benefit, we have to accept the
following annoyances:
It's inconsistent with pretty much every other Sphinx project out
there. Python lays out an 80-column maximum for Sphinx documents, the
same as code:
https://docs.python.org/devguide/documenting.html#use-of-whitespace
<https://docs.python.org/devguide/documenting.html#use-of-whitespace>
and an inspection of pretty much every other Sphinx project out there
shows this style is consistently followed.
We don’t follow PEP8 either and that’s a much bigger annoyance to
me.
It's inconsistent with the coding standard and requires special
explanation in the docs. I was prompted to write this message by
attempting to review <https://twistedmatrix.com/trac/ticket/7786
<https://twistedmatrix.com/trac/ticket/7786>>.
It requires special editor configuration. ReST mode in emacs, vim,
and sublime text expect to wrap paragraphs at 80 characters and
keeping the semantic newlines where they're supposed to be has no tool
support and involves avoiding other bits of tool support around
re-flowing. It also looks bad in an editor, with a ragged right edge.
It looks bad in online code browsers; long sentences horizontally
scroll or wrap.
I think this style might have made sense ago 10 years ago in HTML, but
with present-day RST it seems to go strongly against the grain.
Would anyone else like to make our documentation style-guide more
harmonious with existing standards? Anyone opposed?
I’m opposed; in general I have the same opinion as Donald: bad tooling
shouldn’t dictate standards.
However I come to a very different conclusion: 80 chars for prose *is* a
very artificial standard set by shitty tooling. If we wanted to be
consequent, it should be “enter only after paragraphs”. Semantic
newlines at least help me to quickly scan the structure of a document,
they indicate when a sentence is too long etc. In other words: it’s a
concession to bad tools but at least it’s a useful one. 80 chars/line
is just terrible in every regard and resulting from soft line wraps
being NP-hard or something.
I’m not gonna veto it or something, just wanted to point out the
tooling-inconsistency in the arguments that are frequently brought up.
_______________________________________________
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
