Propose capping length of rendered output at 24 rows

[notpeter]

I recently ran across a couple commands which I think have too many examples. To combat this, I propose cap on rendered markdown output at 24 lines. Then in a standard height (25 rows) terminal we never scroll the first example off the top of the screen.

This leaves plenty of space for examples. 6 examples with a two line command description is 23 lines rendered. It'll even support 7 commands, if the command description is a single line and two of the example commands are nested under a common description.

Commands which would need to compacted to comply:

• grep (29 lines, 8 examples)
• ssh (26 lines, 7 examples)
• tar (26 lines, 7 examples)

This also makes the "only 5-6 examples" recommendation easy to enforce with Travis.

[igorshubovych]

Interesting idea. I like it.

[rubenvereecken]

Ugh sooo much repairing old pages nowadays. I should know.

24 feels a bit arbitrary, even though you've thought it out well. We render on more screens than just the 25-line terminals though. I doubt I've seen one lately. ls certainly renders nicely on mine. Then there's web clients and the like.

[notpeter]

Default window size for PuTTY, cmd.exe and OSX Terminal are all still 80x25 and this is a project targeting inexperienced command line users.

It may "render nicely" but it reads poorly.

[waldyrious]

I agree with a cap, especially since it's a clear way to ensure we're fulfilling the most essential element of tl;dr, which is to be brief. I'll just add that two commands under the same example is a no-no (although case-by-case reasoning is always possible), but 6 examples are certainly enough to cover the basics of most commands.

[rubenvereecken]

Capping at 6 is a good thing either way. We'll get rid of the multiple examples thing. I'll generate a list with the offending pages soon.

This should be in the linter.

[waldyrious]

Uh... I must've miscounted earlier, but

6 examples with a two line command description is 23 lines rendered.

doesn't seem to hold out (anymore? Did the recent formatting changes include more newlines? @rubenvereecken)

If I'm counting right, a page with a single-line description and 6 examples clocks in at 27 lines, so perhaps we can set the limit at 30 lines?

[rubenvereecken]

I noticed the same thing. Nothing changed.

[waldyrious]

@notpeter please enlighten us :)

[notpeter]

It turns out there's a little bit of variation between how clients render the markdown. My count previously was based on the tldr-cpp-client but things are slightly different with the node based client.

SCP is a good baseline (double description line, six examples, 28 lines of markdown) and the nodejs client renders it as 22 lines with two trailing newlines (24 lines). tldr-cpp renders only one trailing newline (23 lines). We could implement the test for 28 lines of MD or as 24 lines rendered.

[rubenvereecken]

Right so "-1" per example, that's easy enough to track.

I'm keeping it at 6 examples and 3 lines of description. That's more than enough for anyone.

[rubenvereecken]

npm install tldr-pages/tldr-lint#page-length

Damn I started typing out a list here but it seemed too long. Many pages have 7 examples, together with one line of description that brings them at 24/26 lines without/with newlines. So these are okay too right. Annoying.

[rubenvereecken]

I'll implement a check for 29 lines of MD and I think the node client should be nicer in its output, or might there be a particular reason for this @igorshubovych?

[waldyrious]

I don't see why are we counting lines as rendered -- it's up to the clients to decide how to format the output. What we should care about, IMO, is the lines of markdown in the source, i.e. here on the repo. In that case the format (per the guidelines) includes empty newlines between the example description and the actual example, which results in (as I mentioned above) 27 lines for a page with a single-line description and 6 examples. Hence my proposal to cap at a nice round 30 lines.

In fact, I even did some tests to see if we could compact the markdown code and remove the extra line between the example description and the command line, but it looks like the safest approach (to be well understood by most markdown renderers) requires the newline. In fact, to be in the clear we'd have to indent the command line with four spaces (two spaces works for some markdown renderers, but not all), so that they are contained within the same list item when rendered. As a bonus, that also makes the plain-text more readable:

# command-name

> Short, snappy description.
> Preferably one line; two are acceptable if necessary.

- Example 1:

    `command -opt1 -opt2 -arg1 {{arg_value}}`

- Example 2:

    `command -opt1 -opt2`

- Example 3:

    `command -opt1 -opt2`

- Example 4:

    `command -opt1 -opt2`

- Example 5:

    `command -opt1 -opt2`

- Example 6:

    `command -opt1 -opt2`

Check out the output by multiple markdown renderers in Babelmark :)

[waldyrious]

@notpeter @rubenvereecken any comments?

[rubenvereecken]

Don't have much time but in short I don't want to indent. It's a lot prettier and it even works well with Markdown renderers but our clients usually aren't regular renderers anyway. Most of all it'd create a contributor nightmare, that's the bit that puts me off the most.

30 lines is a nice cap though too much according to @notpeter's analysis. That'd scroll the page.

[waldyrious]

Most of all it'd create a contributor nightmare

You mean for client authors or for page authors (given the open PRs)?

As for the line limit, if we can't afford 30 lines then we could set a hard limit at 5 examples, which with the newlines format that we currently use here in the source would result in a 24-line max (with a 2-line description). So we could cap at a nice 25 lines, which would comply with the standard height @notpeter mentioned.

[rubenvereecken]

Take this to Gitter then recap here.

[waldyrious]

As discussed in #1149, we have now agreed on a maximum 8 examples per page, which with the current format results in a total of 29 lines. Since the clients can choose to render the output in more compact or more spaced-out formats, the limit doesn't correspond to line count specifically, but to command count which IMO is a more useful metric. I'll close this, but since the discussion in #1149 had considerably less participants than this one, feel free to voice any disagreements here and we can revisit the decision.