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?
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)
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.
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.
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.
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.
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.
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.
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.
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.)
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).
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:
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.
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
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.
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.
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.
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.
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.
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.
