search

apiaryio / api-blueprint

API Blueprint
https://apiblueprint.org
MIT License
8.64k stars 2.14k forks source link

Wrap long lines in descriptions #325

Closed jean closed 8 years ago

jean commented 8 years ago

Wrap lines, it's more suited to a plaintext format like markdown.

For rendering, paragraphs don't need to be wrapped. But markdown uses a double-linebreak as paragraph separator so that paragraphs can be wrapped. As Gruber writes:

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

For me, this includes wrapping lines. A lot of source code, such as C or javascript, doesn't need wrapping either. But yet we do, for readability and better diffs.

Here's a markdown style guide that raises the same points (both pro and con): http://www.cirosantilli.com/markdown-style-guide/#line-wrapping

jean commented 8 years ago

No semantic linebreaks.

zdne commented 8 years ago

Hey @jean, thanks for the PR! I've read through all of the changes and it looks good to me. I like the provided reasoning. One thing I would consider in future is to separate the formatting change pull request from the grammar fixes. But overall this is 👍.

Just for the record: Are you suggesting the wrap should occur at column 80? We should probably note it somewhere and keep it in mind for future.

jean commented 8 years ago

Hi @zdne thanks for the merge :-)

Yes, I apologize for smuggling in the grammar fixes together with the format change.

Possibly the chosen line length (and other properties) can be noted by putting it in a .editorconfig file and inviting contributors to use http://editorconfig.org/

I'm not personally that fussed about the chosen column. In fact my original PR proposed semantic linebreaks, i.e. break on clauses to make diffs maximally clear. I don't like whitespace noise, e.g. reflowing a whole paragraph because one word was inserted. I would reflow (gq<motion> in Vim) just the line that grew too long (and maybe the next one, to end the short line on a natural break). And, if a reflow would cause a cascade, I wouldn't reflow if the edit exceeded the line length by less than say 10 characters. In the Blueprint spec, I avoided breaking [links](long/link/target) across lines.

In the end, it's about working on a file that edits nicely, generates readable diffs, and is comfortably readable without needing to be processed. I'm OK with requiring some judgement to maintain this state.