> On 5 Mar 2015, at 09:14, 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 > 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>. > • 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
Welllll, I am opposed, obviously :) I think that it works better in the (some trivial, some non-trivial) RST docs I've written, but, I'm just one person, so, YMMV. However, I defer (ha), as those are real annoyances, and maybe the Twisted docs will never indeed reap the benefits of cleaner documentation diffs/reorganisation in the way, that, for example, my book will. - Hawkie
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
