> On Mar 4, 2015, at 8:14 PM, Glyph Lefkowitz <gl...@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@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
signature.asc
Description: Message signed with OpenPGP using GPGMail
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
