encryption-works
encryption-works copied to clipboard
freedomofpress
Line wrapping
I think we should wrap all the lines in the markdown source of Encryption Works at a reasonable length, e.g. 80 characters. Reasons:
- This is a common convention
- Aids readability of the Markdown source
- Makes diffs easier to read
- Makes pull requests easier to review (see https://github.com/freedomofpress/encryption-works/pull/225#discussion_r45834393)
If we do this, we should also document the preferred line length convention in CONTRIBUTING.md.
Follow up from https://github.com/freedomofpress/encryption-works/pull/225#issuecomment-159640371.
We might want to set the length cap a bit higher than 80 characters, since not everything in Markdown can handle hard-wraps. Headers don't wrap, for example, and the following line:
## A Guide to Protecting Your Privacy for Journalists, Sources, and Everyone Else
is 81 characters.
...after the line length passes a certain point, GitHub doesn't highlight word changes within the file...
Probably worth experimenting a bit to see what that "certain point" actually is before we settle on a number. I can't find anything about it in cursory searches.
@rileyjshaw I actually emailed them about this a while back and they gave me a concrete max length. I'll have to look it up though, I think it's hiding in my inbox somewhere.
Also, I wonder if Github Flavored Markdown might complicate matters a bit, because it handles newlines differently:
The biggest difference with writing on GitHub is the way we handle linebreaks. With Markdown, you can hard wrap paragraphs of text to have them combine into a single paragraph. We find this causes a huge number of unintentional formatting errors. In comments, GitHub treats newlines in paragraph-like content as real line breaks, which is usually what you intended.
This might lead to confusing discrepancies between the Markdown as rendered on Github and the Markdown as rendered by other tools (e.g. markdown, pandoc, etc.)
Oh good catch!
I can't actually repro the described wrapping behaviour in GitHub's Markdown editor for encryption_works.md. Here's what I get for the Roses are red... example:
Hmm, I just re-read the GitHub docs.
It appears that they only treat comments differently, which this comment confirms :)
On second thought, it probably makes sense to just wrap at 80 chars and leave hard-wrapping elements (eg. headers) alone. Thoughts on that @garrettr?