Should we change the HedgeDoc default for breaks from `true` to `false`?

Community Feedback
#1

Should we change the HedgeDoc default for breaks from true to false?

The default behaviour for new lines in HedgeDoc is, that a new line in the markdown code produces a new line in the rendering output. (breaks: true)

This is not common markdown behaviour and can be toggled off by using the frontmatter option (the YAML Metadata at the beginning of notes) breaks: false.

In common markdown normal new lines are ignored. You have to add spaces to the end of a line followed by a new line (see CommonMark spec). (breaks: false)

In the following we try to argue about the proposal to change the default behaviour to be breaks: false in HedgeDoc 2.0:

Pro

  • HedgeDoc is mostly based on the CommonMark standard. breaks is one of the few differences where we don’t follow the standard and for sure it’s the biggest rule we break. In fact most (perhaps all) markdown implementation incorporate this standard.
  • Other programs expect breaks: false from markdown files, so exporting and further use of files would be easier.
    • This could be mittigated by an extra export option (‘Export CommonMark’) that adds spaces, but would be confusing for people who don’t know the differences.

Contra

  • A change of this behaviour breaks the default our users are accustomed to. Also current notes would break, if they don’t have the breaks option set.
    • We could add breaks: false to all existing notes that don’t already have breaks in their frontmatter while upgrading 1.x instances to 2.0.
  • The newline situation of CommonMark is not very convenient for new users (of markdown or HedgeDoc) as it works not in the way other text programs do.
    • Other aspects of markdown are unintuitive, too (e.g. wrapping text in ** to make it bold)

What do you - the community members - think? Feel free to write a response to this post and/or participate in this poll.

Should we change the HedgeDoc default for breaks from true to false?
  • Yes
  • No

0 voters

#2

Eeek, close call! I personally think the way HedgeDoc renders newlines is very sane, and much more intuitive than the CommonMark implementation. But the CommonMark implementation is, well, common.

In fact most (perhaps all) markdown implementation incorporate this standard.

Interestingly, I notice that this (Discourse?) markdown implementation follows HedgeDoc!
Here’s a sentence directly after one new line to prove it.

Other aspects of markdown are unintuitive, too (e.g. wrapping text in ** to make it bold)

Actually, WhatsApp—the worlds most popular messenger I believe—supports exactly that: https://faq.whatsapp.com/general/chats/how-to-format-your-messages/?lang=fb so maybe it is intuitive by now? :man_shrugging:

Ultimately, I voted on the basis that I would like to be able to (continue to) recommend HedgeDoc to a diverse audience, most of whom have never heard of CommonMark.

2 Likes
#3

Personally I find CommonMark to be in the wrong, here.

Whitespace at the end of the line is fragile, there have been numerous instances where this broke. Some editors chose to “clean that up” and broke documents in the process (atom comes to mind, but others did this, too).

I furthermore think that hard-wrapping a block of text yourself is an anti-pattern. It breaks the usefulnes of history. In git and in our history it would create churn in lines that were not actually altered (but only shifted around in the process). That’s why I think for Text (not for code!) enforcing a line-length is a bad idea in general. That removes the neccessity to “ignore” a newline character to re-assemble a paragraph that shouldn’t have been broken up in the first place. And that’s why I think HedgeDocs current approach is more “correct”.

Thirdly, as pointed out before, it is much more intuitive for newcomers. A break creates a break. Easy. Try explaining “put two invisible characters somewhere” to every single person that you want to work with. People that do not care about markdown, but only want to jump into a document and work on it. I’m especially puzzled by this, because MarkDown set out to be a very human-centered format with the principle of least surprise in mind, but this choice especially is very much not made for humans.

And finally, also as pointed out, we’d break existing documents. I find “we’ve always done it this way” to be a bad reason to keep doing something going forward, so this comes in last in my opinion. Especially with a major revision coming up, backwards compatibility can be discussed. Still, tradition / backwards compatibility are also leaning towards “don’t change”.

So, in summary, newline should continue to create a line break. HedgeDoc should not change its behaviour.

1 Like
#4

I think that decorating a word with something is not at all unintuitive. On paper, you’d underline a word or use textmarker to highlight it. The asterisk has a similar effect of drawing your eye to this symbol, so while the asterisk itself has to be learned, it is very approachable. Especially by comparison.

#5

I don’t know what is the reason vote for this issue, but as I see the current breaking behavior perform very well.

#6

The default line breaking behavior in markdown is not very intuitive and has almost no use case. GFM does hard line breaks and everything else should follow that.

#7

interestingly, this has 220 views but only 17 votes. If you are a visitor, I’d encourage you to participate. You can of course also just comment and not vote, if you like.

2 Likes
#8

I generally like Markdown’s behavior of “ignoring” single line breaks. It also fits LaTeX’s and HTML’s behavior, but I can see that it’s unintuitive. However, I still prefer that as it allows to sturcture paragraphs without breaking them in the output, and in typography you mostly don’t want linebreaks in paragraphs.

I hate the “whitespace at the end of the line” behavior. Something you don’t even see shouldn’t change the output. I even configured my editor to remove dangling whitespace.

However, note that whitespace at the end of the line is not the only possibility in CommonMark to add a line break, you can also use a backslash: https://spec.commonmark.org/0.28/#hard-line-breaks. I always use that instead of dangling whitespace for line breaks.

A backslash is somewhat more intuitve at least for people with a coding background, can actually be seen and is easier to explain.

That’s why I voted yes, but the manual page should then explain the backslash as the default way of adding a line break in my opinion.

2 Likes
#9

As a general outcome, I guess it would be a good idea to come up with the HfM -> HedgeDoc-flavoured-Markdown as we have some special cases in our rendering setup. From automated embedding to certain code features and, of course, the outcome of this poll towards line breaks.

Those are modifications we should document and find a terminology for to make sure we don’t send people onto an unexpected road when researching behaviour.

3 Likes
#10

I signed up in this forum for participating in the poll. I think sticking with CommonMark would be a good choice. I often start a draft in CodiMD/HedgeDoc and then move it to other locations (e.g. a README file that will be published on GitHub). It’s great if this works seamlessly. (That’s the whole point of CommonMark, creating a unified markdown specification instead of having a dozen flavors with slightly different behavior that’s not immediately apparent.)

The CommonMark trailing space is horrible, but since markdown is a subset of HTML, you can always use <br> for forced newlines.

(Interestingly, Discourse also ignores this aspect of CommonMark and creates line breaks for newlines.)

2 Likes
#11

From my personal use: dangling spaces always confused me a bit. My normal use is: a single line break won’t break a line in the rendered output, I think I’m agreeing here with @Eisfunke.

I mostly use a blank line for a new paragraph as a main structure of my texts though.

So: trailing space are really not that intuitive and as long as hedgedoc will auto-wrap the written markdown a line break should be rendered as a line break (in this case, ignoring other markdown copied to hedgedoc).

1 Like
#12

I’d welcome that change

I like the CommonMark behavior of ignoring single linebreaks, because it allows me to use semantic linefeeds a.k.a. semantic linebreaks in the source (at most one sentence per source line), without interfering with the appearance of the rendered result.

I, too.

I’d welcome backwards-compatibility, too

Can I “have my cake and eat it, too”? I see too possibilities for making this change in a backwards-compatible way:

  1. have the new default only for new documents (created after the change)
    • That’s probably not something we want, because
      • Different documents on the same instance would counterintuitively behave differently for the same source content.
      • It means we have to store somewhere somehow which documents were created after the change and which before.
  2. offer automatic conversion. Offer some process that will
    • automatically insert a front-matter with breaks: true into pre-existing documents without front-matter
    • automatically breaks: true into the front-matter of pre-existing documents with front-matter
      • except when that front-matter already explicitly sets breaks to any value
1 Like
#13

explicit hard breaks in a breaks: false environment / in CommonMark

Heh, I didn’t know that. Thanks @Eisfunke! I, too, will use that (instead of two trailing spaces) in the future when I need a hard line break without beginning a new paragraph in a breaks: false MarkDown environment.

#14

Ignoring single newline in other text-based formats is quite common (TeX, mandoc,…) It allows to write text following the 1 sentence = 1 line paradigm, that makes following changes in VCS systems (git,…) easier.

1 Like
#15

True, however one should keep in mind, that this default targets everyone, not just people who throw text into any sort of version control system or do any post-processing of it.

Often enough HedgeDoc is used for conference call notes and alike which is basically scribbling paper. And it should be intuitive and easy to use for everyone who joins such a session and might not have lots of experience with (“professional”) text processing tools.

So all our decisions should target the the majority of newcomers. It’ll always be possible to change the breaks behavior in the document itself when one wants to have the mentioned benefits.

1 Like
#16

So all our decisions should target the the majority of newcomers.

This is exactly the point that leads me to believe we should not change the default.

I would instead propose to add a user-specific setting for the break-behavior. The user can then specify their preferred way, which would automatically be applied to all new notes. That way, power-users can easily use breaks: false, while we are still beginner-friendly by default.

3 Likes
#17

I vote also for following the CommonMark standard and making breaks: false the default behavior to easy the semantic linebreaks and improve interaction with an extended ecosystem of Markdown tools. For example, we start our collective writing mostly in HedgeDoc, then we put our documents in a Fossil repository and finally we use Pandoc to create HTML and PDF versions (the workflow is explained, in Spanish, in https://is.gd/documentaton). To support interaction with other tools, we need to always add breaks: false in HedgeDoc YAML metadata headers, but making this the default would follow the principle of least surprise, as stated in this issue.

#18

I think the result of this poll is that we keep the line breaking as it is.

#19

Seems so. I guess we can close the thread?

#20

per user - does that mean “a user creates a docuement and sets this setting on this document for everyone”? or does this mean “I take my setting around with me to whichever document I look at at the time”?

Because the latter would mean that two people looking at the same URL would see different results, and that would be the worst outcome in my opinion.