[Twisted-Python] getting rid of semantic newlines

[Glyph]

> On Mar 4, 2015, at 10:20 PM, Hynek Schlawack <hs at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20150305/86162d17/attachment-0002.html>