Heated topic, this. Still, I feel that a few useful things have not been said yet, so I’ll see if I can get them across properly.
First off, terms:
- I’ll use hardwrapping and hardwrapped files to refer to files that use linebreaks in the middle of paragraphs. These linebreaks are placed to make the plaintext / markdown look good, they have no semantic meaning (it’s just one paragraph).
- I’ll use softwrapping to refer to using linebreaks in the markdown source only where they are semantically relevent as linebreaks or paragraph separations. In particular, this means that paragraphs end up as a single long line in the markdown source.
- I’ll refer to rendering a linebreak soft as meaning that a linebreak in the markdown does not produce a linebreak in the rendered HTML, and rendering hard means it does result in a linebreak. I think this is the same as what the spec uses.
Then, my own position: I’m a vim user that really wants to hardwrap all the things. I certainly think that rendering linebreaks soft should be the default, as it does not prevent people from using softwrapping. I do think some extra markup could make all of our lives easier. On to the details.
About hardwrapping. People have mentioned that “if the user pressed enter, that should produce a line break in the rendered output”. However, some editors (most notably vim) take care of this automatically - once you go over 72 characters (by default), it inserts a linebreak. It also has some commands to efficiently “reflow” a paragraph when needed. When editing plaintext files, this is convenient.
The result is a hardwrapped file, which:
- Looks exactly like the author intended, even on dumb editors
- Is convient to use with diff software
- Easier to work with in hard-wrapping editors
The opossite, softwrapping, or using a single line for each paragraph, is:
- Has configurable line width, regardless of what the author liked
- Easier to work with in editors which do not support handwrapping
- Markdown source doesn’t look so good without Markdown-aware wrapping
One interesting observation here is that the latter, using a single line for each paragraph, is rendered the same way, regardless of wether linebreaks are rendered hard or soft. So for regular paragraphs, which would be the brunt of markdown text, rendering linebreaks hard is more flexible (it supports either approach). The difference is in other context, such as addresses, where the linebreaks in the markdown do have semantic meaning (in particular, where linebreaks are needed, but there are not multiple paragraphs involved).
Above, I said softwrapping doesn’t look so good without Markdown-aware wrapping in the editor. This is probably best illustrated by an example. For ease of illustration, I’ll assume a very small (let’s say 40-character wide) editor screen, but everything I say applies to any width.
First off, a typical short paragraph. When it’s hardwrapped at 40-chars, the markdown source looks like:
Lorem ipsum dolor sit amet, consectetur
adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna
aliqua.
When softwrapped, the source is just one line, but when viewed in our 40-character editor, it also looks exactly the same:
Lorem ipsum dolor sit amet, consectetur
adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna
aliqua.
So, no difference there (actually, bonus points for softwrapped - if I resize the editor, the wrapping changes).
Now, suppose I add a list and some quoting to the equation. This is a single list item, containing a quote and some normal text, using hardwrapping:
- > Lorem ipsum dolor sit amet,
> consectetur adipisicing elit, sed
> do eiusmod tempor incididunt ut
> labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat.
Now, if I use softwrapping, these end up as 2 long lines, with an empty line in between. If I let a regular editor apply linewrapping to that, it will look like this:
- > Lorem ipsum dolor sit amet,
consectetur adipisicing elit, sed do
eiusmod tempor incididunt ut labore et
dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat.
Which, IMHO, is not quite readable, especially compared to the hardwrapped version.
Of course a smart, markdown-aware editor could certainly improve this, by adding indents and other prefixes to the wrapped lines based on the context.
But I think this example actually shows that Markdown lends itself well for hardwrapping the source code (just like email).
Now, people argued that if linebreaks do appear in the source document, they’re probably intended as such and should be present in the output. For example, comment #35 argues that a hard-wrapped paragraph will still look proper when the linebreaks are rendered hard (e.g. actually become linebreaks in the rendered output). However, there’s a few problems with that:
-
When rendered to HTML, this approach prevents reflowing the text dependent on the output width, line length depends on the source formatting.
I realize that this is a bit of a double sided blade, since the same argument could be made for softwrapping (and I actually mentioned this as an advantage of softwrapping above)
However, I think that this argument has more weight for the rendered HTML output, since people expect their line width to fill the available space (or whatever the layout and CSS rules dictate). If the text is rendered really narrow (which is usually the case when the source was hardwrapped at 80 or 120 characters) it just looks wrong.
-
When rendering, typically a proportional font is used. Depending on what letters are used on which lines, this could cause the line endings to look uneven. This is not a problem when the markdown source is viewed, since that typically happens in a non-proportional font.
-
When rendering, parts of the markdown might end up significantly shorter in the rendered output (this is actually just a special case of the previous point, I guess). Best illustrated with an example.
Consider this (hardwrapped) markdown source:
[Lorem ipsum](http://www.lipsum.com/)
dolor sit amet, consectetur adipisicing
elit, sed do eiusmod tempor incididunt
ut labore et dolore magna aliqua.
This looks balanced when viewing the markdown source, but when rendered the extra link markup disappears. When linebreaks rendered hard, this ends up as:
Lorem ipsum
dolor sit amet, consectetur adipisicing
elit, sed do eiusmod tempor incididunt
ut labore et dolore magna aliqua.
Which isn’t quite what you’d want.
So, that suggest that you want to render linebreaks hard, at least by default. However, even for people like me, that use hardwrapping, sometimes other pieces of text come up, that are not regular, flowing paragraphs. Addresses seem like a perfect example of this. I’d like to have the rendered output look like this:
Mr. Example
Example street 1
12345 Someplace
But none of these markdown syntaxes for this look good:
Mr. Example
Example street 1
12345 Someplace
Mr. Example\
Example street 1\
12345 Someplace\
Mr. Example
Example street 1
12345 Someplace
The first uses double trailing spaces, which look fine, but are not visually distinguishable from regular paragraphs. Trailing backslashes are better in this regard, but look quite ugly. Finally, making each line a separate paragraph looks bad and is semantically incorrect as well.
For and address like this, you really do want to render linebreaks hard (yes, even me).
The current spec says “A renderer may also provide an option to render soft line breaks as hard line breaks.”, which I take to mean that a rendere might have an option, like a commandline or configuration option, to render hardbreaks instead of softbreaks. Even though this seems like a solution, it’s not, due to lack of granularity.
More specifically, this would mean you could turn this option on or off for a single user or perhaps even system. However, a single user might have different needs in different documents and, as shown above, even different needs within a document.
If we could somehow detect between the different types of “paragraphs” (or rather, distinguish between a paragraph and a group of lines) without adding markupt for that this would be great. Comment #41 has a proposal for this, but I simply don’t think we can come up with something that works in enough cases, so the second-best option would be to somehow mark a single paragraph, or a block of markdown, to use hard-rendered linebreaks?
I’m thinking about something along the lines of the ``` syntax that can be prefixed and postfixed to a list of blocks to make linebreaks inside them rendered hard.
This also means that if a document needs all their linebreaks rendered hard, it could be possible to just wrap the entire document in this new syntax.
At first glance, such a syntax would solve all problems adequately (or did I miss anything). The only challenge left would be to come up with some decent markup that can be used, preferably something that gives some idea of what it does when reading it).
Thinking on this a bit more - this is actually a weakened version of the ``` syntax. Where ``` implies:
- (typically) Proportional font / code block
- No inline markdown formatting
- Hard linebreaks
This new syntax would only need to imply the last point. This raises the question: Is there any usecase for other blocks with just one or two of the above points? E.g. a block that is shown in a proportional font, but renders linebreaks soft and supports inline formatting? Or a block that doesn’t support inline formatting, but doesn’t get rendered in a proportional font? Doesn’t sound all that bad, though this might be overengeneering things.
Thoughts? Flames? Comments?