80 characters per line

[gforcada]

Some more files, thanks @svx for merging the first pull request!

[do3cc]

Uhm, this is documentation not source code. It is debatable if 80 chars per line make sense here. http://rhodesmill.org/brandon/2012/one-sentence-per-line/

[aclark4life]

FWIW I definitely don't apply 80 chars per line to text

[hvelarde]

according to PEP 8: "For flowing long blocks of text with fewer structural restrictions (docstrings or comments), the line length should be limited to 72 characters."

[miohtama]

Better to have auto-wrap + one line per paragraph. Press new line at the end of paragraph like you would do in the word processor.

Dudes, this is not freaking 70s anymore. Your text editor can wrap text.

[miohtama]

Also let me apologize beforehand if my previous comment insulted any Vim or Emacs users.

[aclark4life]

@hvelarde PEP8 does not apply here as this is not source code (which is what @do3cc just said). @miohtama +1

[hvelarde]

@miohtama this is not about an editor wrapping text, this is about tracking changes easily; it doesn't make sense to change one character on a line and affect one full paragraph.

@do3cc @aclark4life this is not Python code, but there are still style guides: All reST files use an indentation of 3 spaces; no tabs are allowed. The maximum line length is 80 characters for normal text, but tables, deeply indented code samples and long links may extend beyond that. Code example bodies should use normal Python 4-space indentation.

[aclark4life]

@hvelarde I don't feel particularly inclined to follow the Python core developer's style guide here.

[hvelarde]

but we do feel to follow plone.api conventions on line length: The line length rule also applies to non-python source files, such as documentation .rst files or .zcml files, but is a bit more relaxed there.

[aclark4life]

@hvelarde Good for you! :smile:

[hvelarde]

@miohtama

_Hints for Preparing Documents_

Most documents go through several versions (always more than you expected) before they are finally finished. Accordingly, you should do whatever possible to make the job of changing them easy.

First, when you do the purely mechanical operations of typing, type so subsequent editing will be easy. Start each sentence on a new line. Make lines short, and break lines at natural places, such as after commas and semicolons, rather than randomly. Since most people change documents by rewriting phrases and adding, deleting and rearranging sentences, these precautions simplify any editing you have to do later.

— Brian W. Kernighan, 1974

[aclark4life]

@hvelarde Shark -> Jumped. I don't think it's a worthwhile investment of time to try to convince someone their preference is wrong. E.g. I'm going to continue to prefer what I prefer, regardless of how many quotes you include in this PR :smile:

[jean]

Be willfully obtuse if you like, but don't denigrate well-reasoned standpoints as arbitrary "preferences".

Yes, diff tools have improved and since quite recently can do sub-line diffs reasonably, most of the time. 'grep' will still show you the entire paragraph though, 'git stat' will count paragraphs and call them lines, viewing the source without program support for wrapping will be nasty (e.g. in browser, with 'less', etc).

Either way can be made to work but line breaks just work better with the whole range of tools for textual source files. And it makes sense to pick a style format and stick to it. What's the point of cultivating source with a mish-mash of styles. On 25 Jan 2014 4:31 vm., het "Alex Clark ☺" notifications@github.com geskryf:

@hvelarde https://github.com/hvelarde Shark -> Jumped. I don't think it's a worthwhile investment of time to try to convince someone there preference is wrong. E.g. I'm going to continue to prefer what I prefer, regardless of how many quotes you include in this PR [image: :smile:]

— Reply to this email directly or view it on GitHubhttps://github.com/collective/collective.developermanual/pull/241#issuecomment-33263248 .

[aclark4life]

@jean You haven't convinced me this isn't about preference. If that means I'm "willfully obtuse" then so be it. I understand some folks think this is a good idea. I happen to 1.) not agree and 2.) don't think it's worth arguing about and 3.) am +0 on what people do with line lengths in this documentation, short or long

I only object to the insistence that a certain line width is "better".

[svx]

@miohtama btw, I use vim and I have no problems to wrap text :)

@ all: If you want to have a discussion about guidelines about our documentation for sure if we talk about the future you should join one of the docs sprints this year, personally I am in +1 about 80 characters but I am 'soft' about it, means for the moment I think we have more important tasks to handle with documentation, but if people already using it/changing the docs like @gforcada I think its cool !. So if people are interested in a style guide for our docs lets say from Plone 5 on, lets start talking about it, if you can not make it to one of the sprints maybe on the docs-list ?

[aclark4life]

@svx +1 Note that I'm +0 here i.e. not against wrapping and not for it. Just trying to get folks to tone down "if you don't do it this way, you are wrong" sentiment. And I'm certainly capable of wrapping text for the community's sake. But I'm not sure if it should be one of the requirements we insist on for participation. Anyway, I'll re-join the docs list; haven't been active there for a while.

[do3cc]

This discussion is a bit embarrassing. So many opinions on such a minor topic and nobody doing his due diligence before commenting. (Including me). Here is the style guide for the developer docs: http://developer.plone.org/reference_manuals/active/writing/writing.html#style-recommendations