Updating formatting in ABOUT.md for Nextercism

[iHiD]

Hello @exercism/track-maintainers. This post supersedes #84.

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 <br/> 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
• [x] coldfusion
• [ ] coq
• [ ] cpp
• [ ] crystal
• [x] csharp
• [x] d
• [ ] dart
• [x] delphi
• [ ] ecmascript
• [ ] elisp
• [ ] elixir
• [ ] elm
• [x] erlang
• [ ] factor
• [ ] fortran
• [x] fsharp
• [x] go
• [x] groovy
• [ ] haskell
• [ ] haxe
• [ ] idris
• [x] java
• [x] javascript
• [x] julia
• [x] kotlin
• [ ] lfe
• [x] lisp
• [ ] lua
• [x] mips
• [ ] nim
• [ ] objective-c
• [ ] ocaml
• [ ] perl5
• [ ] perl6
• [x] php
• [ ] plsql
• [ ] pony
• [ ] powershell
• [ ] prolog
• [x] purescript
• [x] python
• [x] r
• [ ] racket
• [x] ruby
• [x] rust
• [x] scala
• [ ] scheme
• [x] sml
• [ ] swift
• [ ] typescript
• [ ] vbnet
• [ ] vimscript

[Smarticles101]

You can check off java :)

[ilya-khadykin]

I've also updated one for Groovy in PR #59

[lpil]

One for Purescript https://github.com/exercism/purescript/pull/64

[NobbZ]

You can tick off erlang as well. Also you have missed to wrap at least on <br/> in backticks as it seems ;)

[stkent]

Handling Kotlin right now. Kotlin is done 🖖

[petemcfarlane]

PHP looks already compatible

[ErikSchierboom]

F# is also done.

[rpottsoh]

Delphi is done.

[kotp]

Ruby can be checked off, I believe.

[ilya-khadykin]

Created PR #511 with updates for Python

[ozan]

MIPS looks fine.

[iHiD]

@exercism/track-maintainers You can now see your ABOUT.md and all the other bits on pieces on the prototype at https://v2.exercism.io/tracks/{track_id}.

Two good examples: R and Go.

[ErikSchierboom]

Looking great!

[mcmillhj]

SML can be checked off: https://github.com/exercism/sml/pull/43

[verdammelt]

@iHiD I'm curious about the desire to have each sentence on an individual line? Perhaps I am a dinosaur but I like to wrap my lines at a reasonable length with a line-break. I didn't think that Markdown or HTML cared.

[NobbZ]

Each sentence on its own line takes the burden of reflowing a paragraph after changes. Also it reduces the noise in diffs, since only a single line is affected for a single word change in a sentence, instead of huge noisy diff over the whole paragraph. This has been discussed (as well as other things) in #84.

Also I'm not quite sure if ORG-files would work out. There is a markdown engine rendering the file… That will not look well.

[iHiD]

@verdammelt Markdown cares depending on the settings chosen. For some reason, v2 had the setting to have sentence = line. ("some reason" being a set that flag but don't know why :)) But you're correct that in it's default state it doesn't care.

If you have text-wrapping on in an editor, then leaving a line between paragraphs is the same as what you see in the final render, which is why it's my preference. But I lost that debate :)

[verdammelt]

Thanks for the info about why it is important. I can agree to that. I'll have it fixed up shortly and update this ticket.

[verdammelt]

Common Lisp is done.

[lindakatcodes]

I've updated the JavaScript track's file - pull request is here. First pull request! So please let me know if I need to adjust anything.

[ilya-khadykin]

I've update it for ColdFusion (or should I say CFML?) - https://github.com/exercism/coldfusion/pull/60

[SaschaMann]

The Julia track has been updated as well: https://github.com/exercism/julia/pull/79

[dogweather]

So, no code fences?

[kytrinyx]

@dogweather there should not be a need for code blocks in the ABOUT.md doc, as far as I can tell. Do you have a specific use case that you think we should consider?

[dogweather]

Yep, @kytrinyx , the Haskell ABOUT.md. Personally, I like the little code sample; similar to a picture being worth 1,000 words.

[kytrinyx]

@dogweather I agree that a code example is crucial (and worth 1000 words). The plan is to stick the code example in docs/SNIPPET.txt, which gives us more control.

I'd love to take the code example from ABOUT.md and move it to SNIPPET.txt in place of the hello world that is currently there. Here's what the v2 page currently looks like: https://v2.exercism.io/tracks/haskell

[dogweather]

Excellent - will do! I was thinking that's how it should be, i.e., a quasi-rich-content CMS with defined content pieces.

[kytrinyx]

I'm going to go ahead and close this, as we had help this summer going through and fixing it.