Update and expand line breaks FAQ #7
Conversation
| <dd>**Inline HTML**: Supported</dd> | ||
|
|
||
| <dt>Markdown</dt> | ||
| <dd>**Syntax**: None</dd> |
There was a problem hiding this comment.
I don't think "None" is sufficiently transparent here. The double trailing spaces is an option prescribed by the original spec, even if we'd prefer not to encourage it. In any case, the ** should be added here as well.
There was a problem hiding this comment.
Agree, for transparency and consistency.
Then the text in ** should be updated to talk about Markdown in general, or Markdown and CommonMark, but not just CommonMark.
(I was unsure whether the original spec has this feature, and indeed it does: https://daringfireball.net/projects/markdown/syntax#p)
There was a problem hiding this comment.
Sorry, I should have added a link. Thanks for doing so.
| @@ -226,6 +262,7 @@ If you’d like to leave feedback, please | |||
| [commonmark]: http://commonmark.org | |||
| [github-issues]: https://github.com/sembr/specification/issues | |||
| [haddock]: https://www.haskell.org/haddock/doc/html/ | |||
| [rst-line-block]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks | |||
There was a problem hiding this comment.
Nit: should this be moved between [rfc2119] and [semver] so that the alphabetical order is retained?
(I suspect this used to be [line-block]. Then this would be the correct location.)
| <dd>**Inline HTML**: Supported</dd> | ||
|
|
||
| <dt>Markdown</dt> | ||
| <dd>**Syntax**: None</dd> |
There was a problem hiding this comment.
Agree, for transparency and consistency.
Then the text in ** should be updated to talk about Markdown in general, or Markdown and CommonMark, but not just CommonMark.
(I was unsure whether the original spec has this feature, and indeed it does: https://daringfireball.net/projects/markdown/syntax#p)
| > Although CommonMark allows the use of trailing spaces | ||
| > to indicate breaks between consecutive lines, | ||
| > this syntax is incompatible with | ||
| > tools that automatically strip trailing whitespace. |
There was a problem hiding this comment.
Other drawbacks of trailing spaces:
- Whitespace is not visible in all editors, so (accidental) trailing spaces can cause confusion.
- Trailing spaces can cause unnecessary diffs if some developers' editors automatically strip trailing whitespace while some other developers' editors do not.
Not sure if it's necessary or relevant to mention these in the spec.
| > a self-closing tag (`<br />`) in XHTML. | ||
|
|
||
| > \*\* | ||
| > Although CommonMark allows the use of trailing spaces |
There was a problem hiding this comment.
the use of trailing spaces
More specifically, the use of two or more trailing spaces, as mentioned in the specs:
- https://daringfireball.net/projects/markdown/syntax#p
- https://spec.commonmark.org/0.29/#hard-line-breaks
Again, not sure if this is necessary info; just saying. 😄
| <dd>**Syntax**: None</dd> | ||
| <dd>**Inline HTML**: Supported</dd> | ||
|
|
||
| <dt>MediaWiki</dt> |
There was a problem hiding this comment.
The correct term might be Wikitext. See https://en.wikipedia.org/wiki/Help:Wikitext
There was a problem hiding this comment.
Here I'd argue for at least keeping a reference to "MediaWiki". There are many wiki engines out there, and the syntax differs among them (which was the motivation behind WikiCreole). Calling this just "Wikitext" will be ambiguous for those unfamiliar with these nuances.
| <dd>**Syntax**: None</dd> | ||
| <dd>**Inline HTML**: Supported</dd> | ||
|
|
||
| <dt>OrgMode</dt> |
There was a problem hiding this comment.
https://orgmode.org/ uses "Org mode," not "OrgMode." (The logo and the main heading on the home page uses "Org Mode" with a capital M, but all other instances seem to be "Org mode" or just "Org.")
|
Off-topic question, if you don't mind: I find your way of using reference links interesting, in a good way.
Do you know any resources related to this? Kinda like the sembr spec, though I don't know if these simple practices warrant a spec. |
Resolves #6