Updating formatting in ABOUT.md for Nextercism

[iHiD]

Hello @exercism/track-maintainers.

In preparation for the new look and feel of nextercism I'm trying to get all of the ABOUT.md files reformatted. This means removing things like line-breaks and markdown that we're not supporting.

As an example from the C++ Track, I've proposed going from:

to:

In summary, ABOUT.md should now only use:

• Bold
• Italics
• Links
• Bullet lists
• Number lists
• Each sentence should be on its own line
• Paragraphs separated by an empty line
• Explicit
  used to split a paragraph into lines without spacing between them (discouraged).

This is a checklist of the tracks that need doing. I am trying to send PRs to tracks that need updating, but if maintainers are happy to do it themselves that will save me hours of time. If your ABOUT.md already complies with these formatting rules, could you please comment and and I will tick it off the list. Thank you 💙

• bash
• c
• ceylon
• clojure
• coffeescript
• coldfusion
• coq
• cpp
• crystal
• csharp
• d
• dart
• delphi
• ecmascript
• elisp
• elixir
• elm
• erlang
• factor
• fortran
• fsharp
• go
• groovy
• haskell
• haxe
• idris
• java
• javascript
• julia
• kotlin
• lfe
• lisp
• lua
• mips
• nim
• objective-c
• ocaml
• perl5
• perl6
• php
• plsql
• pony
• powershell
• prolog
• purescript
• python
• r
• racket
• ruby
• rust
• scala
• scheme
• sml
• swift
• typescript
• vbnet
• vimscript

[kytrinyx]

Go follows the rules. As does R.

[NobbZ]

nd should not split paragraphs into lines.

Can you please choose a markdown parser that supporst this? I strongly disagree with single lines that span thousands of thousands of characters which will probably blow many editors as well!

If you have paragraphs that are longer than only 2 or 3 sentences its quite aburden to find the correct place when there's a need to update something.

[kotp]

Paragraphs should be characterized by a separation of 2 new lines. (to clarify, a new line, and then a line with only a new line on it) Any single lines that are not separated by two new lines should be considered one paragraph. Since early years in writing this has been the case. This is just how plain text works, even on paper.

[kytrinyx]

Any single lines that are not separated by two new lines should be considered one paragraph. Since early years in writing this has been the case.

For what it's worth, GitHub issues don't work like this.

this
is not different
paragraphs but
it
appears on different lines

[NobbZ]

Not even talking about generated diffs…

[NobbZ]

But rendering *.md does accept those as a single paragraph.

Just take a look at https://raw.githubusercontent.com/exercism/cli/master/README.md and compare how it is rendered on github or when you post it as a comment.

In a comment the paragraphs appear split up while when beeing rendered multiline texts appear as a single paragraph.

[kytrinyx]

Ah, yepp. I see that now.

OK, cool. Yes, I would suggest that we see if we can tell the markdown rendering engine to deal with paragraphs in this way.

[iHiD]

So we can change this but two things to raise:

1. The rendered line-wrapping won't respect the line-breaks that the author puts in the file, which I think is often confusing for the author.
2. We lose the ability to have deliberately specified line-breaks that don't turn into new paragraphs.

As long as we consider those two things to be ignorable, then I'll change it.

[ryanplusplus]

My 2 cents on this:

• Most editors support some sort of soft wrap so that hard line breaks are unnecessary. Atom does this by default for markdown documents and this may be the case for other editors with a markdown mode.
• Having manually broken lines means that it is difficult to resize a markdown document for editing. Users with poor vision may need to scroll or use soft wrapping which further disturbs the formatting; users with wide screens and small font sizes may have comically narrow documents.
• It is painful editing a file with manually broken lines because you have to redo all of the line breaks in order to respect the original (manual) formatting.

My vote is to enforce no breaks within a paragraph for easier maintenance. I haven't dealt with hard-wrapped markdown documents outside of Exercism and I have not enjoyed the re-formatting required when doing so.

[iHiD]

I wholeheartedly agree with @ryanplusplus and that's my vote too.

[kotp]

I think the rendered line wrappings is normal for the medium to take care of, the only thing it should understand is "a paragraph is words separated by two new line characters" and wrap as it sees fit.

Are there examples of deliberately specified line-breaks? Do we need them? Do we need them to not be considered a new paragraph?

[kotp]

Ah, @NobbZ when I hear "paragraph" I see it as Vim sees it. I see it as on paper. Your example with the shorter lines, I see as common to prose, a poem with a shape... that is a paragraph. (Even as rendered by HTML, with the br tags).

In HTML, it does not honor the breaks, like that on the editor it is tagged as such, in markdown, it is plain text,. I am starting to see the difference, perhaps harder to know the intent for display. I did not consider writing prose.

[kytrinyx]

For what it's worth, I always find it a huge pain to edit files with hard lines, because my editor settings are not typical. So basically, what @ryanplusplus says.

That said, I will happily do whatever we end up deciding, for the sake of consistency.

[NobbZ]

1. The rendered line-wrapping won't respect the line-breaks that the author puts in the file, which I think is often confusing for the author.

As someone who uses MD on a daily basis, I find it even more confusing when…

1. … there are new paragraphs where I do not expect them.
2. … my local preview differs from the server side rendering in the semantics

2. We lose the ability to have deliberately specified line-breaks that don't turn into new paragraphs.

We don't. Even if I do not like it how commonmark handles it, but common mark does render a trailing space as a line break (<br/>).

Most editors support some sort of soft wrap so that hard line breaks are unnecessary. Atom does this by default for markdown documents and this may be the case for other editors with a markdown mode.

Yupp, even emacs does. But working with overly long lines in emacs and vim (at least when used on CLI and not extended via plugins) is a pain, since cursor up/down means skipping a line, not "advance as much as necessary, to reach the next soft-wrapped line on screen".

We should consider such tools as well, some folks are still using them, eg. @kotp, @NobbZ

Having manually broken lines means that it is difficult to resize a markdown document for editing. Users with poor vision may need to scroll or use soft wrapping which further disturbs the formatting; users with wide screens and small font sizes may have comically narrow documents.

Doesn't your editor support clicking the preview and setting the cursor appropriately?

Even if I have a wide screen, and often use it fullwidth, I prefer to not have much more than about 120 characters in a line. Its just hard on the eyes to follow those lines…

It is painful editing a file with manually broken lines because you have to redo all of the line breaks in order to respect the original (manual) formatting.

Editing manually broken lines? Why?

Common sense is to have a sentence per line.

Easy to read, easy to edit and nicely diffed.

Ah, @NobbZ when I hear "paragraph" I see it as Vim sees it. I see it as on paper. Your example with the shorter lines, I see as common to prose, a poem with a shape... that is a paragraph. (Even as rendered by HTML, with the br tags).

I'm not sure what vim thinks a paragraph were, but for me a paragraph is all the stuff I'd put no empty line inbetween when writing markdown, LaTeX or plaintext (email), or enclose in <p></p> when writing HTML.

I accept though, that one sometimes wan't to have extra linebreaks inbetween a paragraph. Thats when I use trailing spaces in MD (or use <br/> to make it more visible), \\ in LaTeX or just a new line in plaintext. Of course I simply do <br/> in HTML ;)

---

The closer we stick to common-mark, the less bug reports will be filed by experienced markdown users.

[iHiD]

We don't. Even if I do not like it how commonmark handles it, but common mark does render a trailing space as a line break (
).

Can you explain to me how someone would insert a manual linebreak please? For example, how would I make the top three lines split?

How would
I make these split
like this when rendered?

This is a new paragraph.

[kytrinyx]

In case this wasn't clear:

• Almost everything I write every day that isn't code, is markdown.
• I use vim.

Editing manually broken lines? Why?

Because a lot of people break at 80 columns whether or not it's the end of the sentence. Then when I change the paragraph in any significant way I have to combine the lines into one, and rebreak it to respect the 80 columns limit.

Common sense is to have a sentence per line.

I would be happy with this approach.

how would I make the top three lines split?

You'd explicitly add <br/> in the markdown.

[kytrinyx]

working with overly long lines in emacs and vim (at least when used on CLI and not extended via plugins) is a pain, since cursor up/down means skipping a line, not "advance as much as necessary, to reach the next soft-wrapped line on screen".

I use search to jump around in long, wrapped lines. It's not ideal, but it's better than joining all the lines and rebreaking them, as I often end up having to do.

[kotp]

I think clearly defining a paragraph as any text delimited with a new line that has only a new line character.

I think the sentence per line tactic is sensible.

Using a space at the end of a line that you want broken will work. I prefer using the html tag
instead, as I really don't like trailing white space, it can be unclear what the intention is.

Like @kytrinyx I also would join the paragraph when reflowing it, it ends up being two characters to press in my vim, it translates to "join and reflow this paragraph". I map to jr.

[NobbZ]

For example, how would I make the top three lines split?

Either use <br/> explicitely as @kytrinyx already said, or use trailing whitespace (␣ means space):

How␣would␣
I␣make␣these␣split␣
like␣this␣when␣rendered?

This␣is␣a␣new␣paragraph.

The semantic meaningful trailing whitespace has some problems though:

• Often it is removed by semi-smart editors
• Often it is not visible in editors
• Quite many live-previewers I've worked with ignore it

[reflowing] ends up being two characters to press in my vim, it translates to "join and reflow this paragraph". I map to jr.

In emacs it's C-c C-q AFAIR, but I do it only in very rare cases.

In fact, I try to avoid reflowing completely:

1. reduce diff noise which happens by reflowing itself
2. reduce even worse diff-noise which happens because of different reflow algorithms/widths

[kotp]

It is true, for sure, during reflow, it does create some noise. This would indicate that single sentence per line, paragraph separated by empty new line, makes things easier in many aspects.

[mhelmetag]

Crystal follows this spec.

EDIT: Crystal's ABOUT.md follows the proposed spec.

[NobbZ]

I do not see a spec here, only a living discussion about how to treat paragraphs and lines.

Also you have at least 2 places that are rendered with an additional linebreak according to the rules presented in the OP:

**Local:**
The problem-specifications repo must reside at the same level as the developer's crystal directory, and must contain a canonical-data.json file for the given exercise.

**Remote:**
If the local problem-specifications repo doesn't exist, a request is made to GitHub to download (and cache) the test's canonical-data.json file.

New:

Local:
The problem-specifications repo must reside at the same level as the developer's crystal directory, and must contain a canonical-data.json file for the given exercise.

Remote:
If the local problem-specifications repo doesn't exist, a request is made to GitHub to download (and cache) the test's canonical-data.json file.

Current:

Local: The problem-specifications repo must reside at the same level as the developer's crystal directory, and must contain a canonical-data.json file for the given exercise.

Remote: If the local problem-specifications repo doesn't exist, a request is made to GitHub to download (and cache) the test's canonical-data.json file.

[kytrinyx]

It feels like the best of both worlds here is the following:

• each sentence on its own line
• paragraphs separated by an empty line
• explicit <br/> if needed

This will avoid the noisy (and painful) reflows, and also allows fairly reasonable navigation by line for editors where that is a thing. For editors that soft-wrap, each sentence will wrap, but you won't get those really weird things where part of a sentence is broken up across multiple lines.

Sound acceptable?

[mhelmetag]

Also you have at least 2 places that are rendered with an additional linebreak according to the rules presented in the OP

Ah... I was just looking at the ABOUT.md... whoops... 😆

I do not see a spec here, only a living discussion about how to treat paragraphs and lines.

Well... not an exact spec but I see what you're saying.

single sentence per line, paragraph separated by empty new line

+1 for that.

[iHiD]

The OP has been updated to reflect what @kytrinyx has proposed.

@mhelmetag - Crystal currently renders with paragraphs inside bullet points due to the newlines between points. Could you remove the spacing between those pls?

[robphoenix]

Then when I change the paragraph in any significant way I have to combine the lines into one, and rebreak it to respect the 80 columns limit.

@kytrinyx In vim, do you know you can visually highlight the paragraph and then press gw and it will format it for you. Found out recently and it saves me so much pain.

[kytrinyx]

@robphoenix I did not! Going to go try that right now.

[kytrinyx]

Oh. My. Goodness.

[drueck]

@robphoenix I love that technique. I use gwap to re-wrap the current paragraph all the time when working with text docs. Saves SO much time!

Actually, I guess what I use is gqap which seemingly does the same thing. I'll have to google what the difference is between gq and gw...

[robphoenix]

Oh. My. Goodness.

Pretty much my same reaction.

Saves SO much time!

I know! I can't believe I used to manually reformat every line in a paragraph after changing one word!

[kytrinyx]

Ok, it sounds like there's no great pushback on the suggested solution, so I'm going to call it. This is the plan:

• each sentence on its own line
• paragraphs separated by an empty line
• explicit <br/> if needed

@iHiD Would you implement this into the prototype?

[kytrinyx]

@iHiD Also: let's open a new, clean issue to keep track of things—this one is going to be hard for people to read through and parse.