Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update and expand line breaks FAQ #7

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update and expand line breaks FAQ #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 42 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,11 +189,47 @@ $ git diff --word-diff
<dt>How do I force a line break?</dt>
<dd>

You can add a hard line break with the `<br/>` element.
Although CommonMark and other lightweight markup languages
allow trailing spaces to indicate breaks between consecutive lines,
this syntax is incompatible with
editors that automatically strip trailing whitespace.
Some lightweight markup languages provide a dedicated syntax for line breaks,
some support line breaks using the inline HTML element `<br>`\*,
and some do both.

<dl>

<dt>AsciiDoc</dt>
<dd>**Syntax**: A trailing space followed by a plus sign (`+`)</dd>
<dd>**Inline HTML**: Not supported</dd>

<dt>CommonMark</dt>
<dd>**Syntax**: A trailing backslash (`\`) \*\*</dd>
<dd>**Inline HTML**: Supported</dd>

<dt>Markdown</dt>
<dd>**Syntax**: None</dd>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I should have added a link. Thanks for doing so.

<dd>**Inline HTML**: Supported</dd>

<dt>MediaWiki</dt>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The correct term might be Wikitext. See https://en.wikipedia.org/wiki/Help:Wikitext

Copy link

@waldyrious waldyrious May 12, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.")

<dd>**Syntax**: Two trailing backslashes (`\\`)</dd>
<dd>**Inline HTML**: Not supported</dd>

<dt>reStructuredText</dt>
<dd>**Syntax**: Leading vertical line (`|`) in a [line block][rst-line-block]</dd>
<dd>**Inline HTML**: Not supported</dd>

> \*
> The _Line Break_ element is represented as
> an empty tag (`<br>`) in HTML,
> and either a tag pair (`<br></br>`) or
> a self-closing tag (`<br />`) in XHTML.

> \*\*
> Although CommonMark allows the use of trailing spaces
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the use of trailing spaces

More specifically, the use of two or more trailing spaces, as mentioned in the specs:

Again, not sure if this is necessary info; just saying. 😄

> to indicate breaks between consecutive lines,
> this syntax is incompatible with
> tools that automatically strip trailing whitespace.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


</dd>

Expand Down Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

[markdown]: https://daringfireball.net/projects/markdown/
[mattt]: https://mat.tt
[mediawiki]: https://www.mediawiki.org/wiki/Help:Formatting
Expand Down