[Twisted-Python] getting rid of semantic newlines

[Donald Stufft]

> On Mar 4, 2015, at 8:14 PM, Glyph Lefkowitz <glyph at twistedmatrix.com> 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.
> 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?
> 
> Thanks,
> 
> -glyph
> _______________________________________________
> Twisted-Python mailing list
> Twisted-Python at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python


Not that my opinion of what Twisted should do should matter much, but I think that semantic newlines are a hack to try and work around deficiency in tooling. Look at Github’s “rendered diff” for how documentation diff *should* be. Tooling should make things easier for the developer, the developer shouldn’t have to go out of their way to make things easier for the tooling.

---
Donald Stufft
PGP: 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA

-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20150304/95cdf64b/attachment-0002.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: Message signed with OpenPGP using GPGMail
URL: </pipermail/twisted-python/attachments/20150304/95cdf64b/attachment.sig>