> On Mar 4, 2015, at 10:20 PM, Hynek Schlawack <h...@ox.cx> wrote:
>
> 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.
Sure, but (A) you're wrong our style is way better than PEP8, just check out my
CAML CASE knuckle tat ;-), (B) the style is "PEP8, except..." and not a totally
different style (C) much of the codebase _does_ actually adhere to that
standard whereas none of the documentation does, (D) we have tools - janky
tools, but tools nonetheless - that validate our coding standard, but none that
can validate semantic line-breaking, and (E) not only do we not have tools to
check this automatically but it's not clear to me how you would check it
automatically. Especially the part where it's arbitrary if you want to break a
line around a clause it's optional, and maybe you don't need to break lines at
the end of short sentences.
So while I can appreciate that the not-quite-PEP8 case isn't exactly open and
shut, it's also a far less obviously beneficial change, in my mind.
>> 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”.
Personally and aesthetically I would also prefer "enter after paragraphs" a bit
better, but as long as we're going to make a change, going with the grain of
other community stuff seems worthwhile.
> Semantic newlines at least help me to quickly scan the structure of a
> document, they indicate when a sentence is too long etc.
One of the features of "semantic newlines" that I discovered in this process is
that it's not "lines at the end of sentences", it's "line breaks at the end of
any clause, optionally". If it were just "line break at the end of a sentence"
it would be annoying, but not quite to the threshold that would make me start
this thread :).
> 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 feel your pain.
When I first came to UNIX - from classic Mac OS - I thought it was crazy that
everybody wrapped lines at 80 characters. It struck me as inconceivable that
people would be inserting artifacts into "modern" (circa 1996), new data based
on the physical limitations of hardware from the 1970s. If you wanted your
lines to be wrapped, why not just have your text editor do soft wrapping?
Obviously "newlines" were only there for paragraph breaks in text files.
But, while this is part of our history, it is not entirely historical.
Line-wrapping is an extremely pervasive cultural convention, and just about
everything expects it. The one community where this hasn't taken root is ObjC,
and if you look at the lengths of some method-names in that universe you may
wish for some 70s-era hardware to dictate your stylistic choices again ;).
Not to mention the fact that if we were really going to throw off the shackles
of bad tooling, we'd be running something other than VT100 emulators to do the
majority of our daily work, but I'm guessing that during this conversation you
have at least one terminal window open ;-).
But have hope, the future may yet arrive. Emacs 24.4 just (just!) introduced
indentation-sensitive wrapping in visual-line-mode which looks vaguely like
you'd expect a post-1986 word processor to look, even if you're editing code.
Supposedly Vim has accepted a similar patch
<https://retracile.net/wiki/VimBreakIndent
<https://retracile.net/wiki/VimBreakIndent>> but I have yet to see it on a
build I've actually installed anywhere yet.
So... give it another 10 years, and the open source community may have cracked
the code of line-wrapping at run time :-).
-glyph
_______________________________________________
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
