Lines are too freaking long!

[poxu]

WTF man? The text, which advises you to learn more about vim is formatted in a manner, which makes it hard to edit it with vim!

Ok, maybe you don't use vim, but fixing a typo leads to git thinking a whole paragraph was changed! Reading the diffs without using special viewers is no fun at all!

If that was plain text I would understand. You wanted text width to adapt to screen size I would think. But you're using markdown, which removes line breaks before rendering text!

Did you do it on purpose :) ?

P. S. I really like your work, but it's not as easy to contribute as it could be. Please, please make line 80 characters long! Or 120 characters long at least.

[ghost]

80 characters? Are you still using punch cards?.. Use word wrap.

[poxu]

I'm not using punch cards, but I'm still using git. Which is a vcs. And which shows the whole line as changed even if you only change one character. So, using reasonably short strings is convenient when working with version control system.

And, by the way, I'm still using vim. Which has problems working with word wrap. I'm not sure, but I suppose emacs has those problems too.

And finally it's not the best practice to use word wrap in source files.

[ashumkin]

+1 to @poxu

[kastian]

also +1 to @poxu

[jlevy]

Haha. I have a saying: It's impossible to have discussion about important things unless everyone can complain about the trivialities first. :wink:

You have a point, and I'm open to seeing what people think works best, based on actual experience using Github. It's not perfectly clear that your suggestion of wrapping at a fixed width is an improvement. The Github web interface and git --color-words can show sub-line differences, so diffs are still readable with long lines. And many people (including myself) use the web interface some of the time, and I've found it works better to have the browser UI do the wrapping, since otherwise you would have to re-wrap the lines manually (again causing a full diff on the paragraph) when you edit a few words (which is a headache since you're not using vim or whatever).

Perhaps the "right" solution is to break lines not by wrapping at a certain width, but logically by sentence, for clarity and to minimize merge conflicts. I might experiment with this, but I'd want to do it mindfully with the outstanding PRs in mind.

[jlevy]

I'll leave this open for further passionate debate.

[overvale]

I've run into this problem myself. The best solution I've come across is the one described here. I've even built a few wrap/unwrap scripts to help me with it.

[ShawnMilo]

Thanks, Oliver. I'd never seen that, but I like it. I generally try to wrap anything I type (code, ReStructuredText, Markdown, etc.) around 80 characters. Now I'm going to try it this way.

[poxu]

Wow, Oliver, that was exactly what I would write if I had brains! You don't mind me publishing a translation with a link to your publication, do you?

[poxu]

So, @jlevy, you're one of those guys, who think they can paint bike shed any color without consulting the public officials? Shame on you!

Also, thanks for your advice to break lines logically. I think, what Oliver wrote, is the same idea, pushed further, but still I wouldn't know about it if you didn't leave this PR open for further discussion.

[jlevy]

@poxu well, when it comes to religion, it's best to avoid controversy but still do what you think is right. ;)

@olivertaylor Thanks for the links. I've done this before, but hadn't seen the term "semantic linefeeds." It's helpful to give it a name, yes, as I think many-author Markdown documents are becoming increasingly common on Github. Of course even this seemingly sensible suggestion is evidently rife with controversy, but some of that is particular to MediaWiki format, not Markdown.

In programming, the modern and probably correct answer to feuds about this stuff is to use automated formatting, e.g. gofmt, yapf, IntelliJ, etc. Those perl scripts could help but don't actually understand Markdown. Longer term, it might be best to have an automated Markdown formatting tool (fully compatible with Github) run before every commit that does breaks via heuristics, probably mainly on sentences. It would enforce conventions and also migrate nonconforming documents. Is anyone aware of one that's suitable? I might (or would anyone else like to?) look into writing one otherwise.

[ShawnMilo]

@jlevy Automation won't distinguish between periods that are the end of a sentence or used in other ways. I vote for the newlines-between-sentences method described in the article, because it will minimize the diffs for future contributions.

[jlevy]

Right -- you'd use newlines between sentences, either manually or with the support of the tool. But the tool would allow one to migrate a non-semantic linefeed doc to one that is semantic linefeeds conservatively, via a heuristic, and to fix after any edits break that invariant. It should be safe always to run it. The heuristic to find sentence breaks would likely be something like the regex +[a-z]+. +[A-Z], which is fairly reliable. Classic TeX typesetting uses a similar heuristic for identifying sentence-ending periods. Finally, there would be some override in the doc for rare cases where that doesn't work. It'd also have to be adapted to other languages (also possible).