Standard for wrapping prose in version controlled documents?

Data Management
#1

Now that we’re moving to write our design documents in text files backed by GitHub, I’m wondering whether there’s a policy for line wrapping of prose?

There are a few options here:

  1. Hard wrap at 80 characters, or the like. I’d call this the old-school approach.
  2. Let the editor soft wrap (i.e., wrap without inserting carriage returns) everything. Two carriage returns separate paragraphs. I’d call this the new-school approach.
  3. One soft-wrapped line per sentence. That is, each sentence is its own line. I’d call this my approach.

The problem with the old school is that it creates chaos in git diffs. Content moves from one line to the next without any change in semantic meaning.

The new-school approach produces cleaner diffs, but the diffs are too coarse. In writing, I feel that the sentence is the key unit of content. That’s why I promote one-sentence-per line writing.

Does anyone have any feelings one way or the other? Are my concerns about git diffing unfounded? Do we already have a standard in place?

#2

I laughed at this because I hate the no-linebreaks approach for writing text documents precisely because you get a hard to read diff where you spend all your time trying to work out what changed. I’m forever doing fill-paragraph on Latex to prevent these problems. Yes, it does mean that in the paragraph after the change you lose track of what really changed but I prefer that to the madness of a line that is hundreds of characters long.

#3

What about git diff --color-words and GitHub’s prose diff feature? They do real word-by-word diff highlighting. And as far as I know, line breaks will break them, no pun intended (someone correct me if I’m wrong on this).

As for the long lines, you can set your editor to do a soft wrap at any length you please. Responsive text documents! :smile:

#4

I saw this, and I was all ready to reply "oh, you just want --word-diff". But I see you’ve already mentioned --color-words, which is broadly the same. Given that, I don’t see the “chaos” you’re worried about.

My preference is “old-school”, but value consistency over any particular standard.

#5

Oh my bad. I see that --word-diff and --color-words aren’t broken by newlines.

If everyone really likes hard wrapping, what line lengths do you want me to make all the design documents? 72 seems common?

#6

If we’re going old-school, I prefer 65 <= line length <= 80.

#7

That’s my favorite, too, and is my LaTeX style.

#8

My vote is for hard-wrapping at 78 characters, because I’ve already figured out how to configure my editor to do that, but I don’t have a terribly strong opinion. I’m sure I can figure out how to make my editor do any of these options well enough.

#9

Okay, it seems that most people have their editors set to hard wrap. By default pandoc also creates 72-character wide hard wrapped documents. I’ll ship those as-is and if a document owner wishes to, can change it. :slight_smile:

When I start shipping LSST Stack Docs I/we will have to write a style guide to specify this.