Question about newline intentions and potential formatting improvements

Exercism Exercism Chat
1

I noticed that certain files, e.g. problem-specifications/exercises/resistor-color-duo/description.md at main · exercism/problem-specifications · GitHub, have parts that go beyond the sentence per line rule:

From the example above:
brown-green should return 15, and
brown-green-violet should return 15 too, ignoring the third color.

Should there be extra newlines in cases like this, to render this effect to the reader?

Alternatively, would parts like this (and the bullet list before it) actually be better as tables?

Just trying to get a feel for how to make improvements or if this is already how it’s intended to be. Thanks! :)

@kotp followed up with:

The newline after and should be removed in that case, as it is not a sentence break there.

But it appears as though the intention of communication there is to bring to attention the information, and a bullet list here could be helpful, providing the “side by side” view that is provided there with the split where it is. That is what it seems like the formatting is attempting to provide by having that line break there.

This happens if reading it in plain text but does not survive the rendering in this way. A bullet list would provide what seems to be intended, by my calculation.

(Thanks for humoring me and for your patience while I moved it to the forum :) )

Thanks for your perspective. I can do bullets, but just before I go to far with that, would tables (like real Kramdown → HTML tables for accessibility, not images) be even more welcome on the visual alignment front?

2

@codingthat Can you please post the link to the original discussion?

3

Question about newline intentions and potential formatting improvements · Issue #2552 · exercism/problem-specifications · GitHub but not really needed: I quoted the entire thing above, minus the bot message and @kotp saying it’d be better to discuss here. ;)

1 Like
4

Link also posted back to this discussion from the issue.

1 Like
5

Yes, but it wouldn’t look good. It would have to be changed to a bulleted list.

Does this need to be improved? No, in my opinion. Right now, it renders as a single sentence with an “and” that connects the two cases — it reads perfectly fine. If there were more than two cases, a bulleted list would probably be the better choice.

1 Like
6

It reads oddly in the terminal, where I usually read it, but it renders fine.

The document that explains why “one sentence per line” provides benefits when changes have to be made, and the form shown here in plain text is known as “ventilated prose”. The rendering does away with that, and the affects on the diffs are compounded with ventilated prose.

However, as a bullet list, we again gain some benefits as the things that would change are likely either the bullet point itself or its order.

The change should be done to remove the EOL (end of line) or convert it to a bullet point (and arguably an indented bullet for the reason that the second is also 15.) can be done at some point later, when and if more information is added to this file, and hopefully will be addressed then.

For the folks that read the information on the platform, it is not problematic at all, but for those that read it in the terminal, well, it does present oddly, compared to the accepted standard of “single sentence per line”, and when setting wrap to accommodate for that, this one area is “specially formatted” and obviously different from the rest of the reading material.

2 Likes
7

Don’t Kramdown tables work well enough in the terminal?

From the example above:

| Input              | Should Return                     |
|--------------------|-----------------------------------|
| brown-green        | 15                                |
| brown-green-violet | 15 too (ignoring the third color) |

To me they might present the best of both worlds, unless you wanted something like:

From the example above:

- brown-green        should return 15, and
- brown-green-violet should return 15, too, ignoring the third color.

But tables can be nicer to read (both in the terminal and rendered), especially for the earlier data with more rows, to keep everything aligned.