Limit line length in page content

[waldyrious]

For example, we could allow a maximum line length of 80 characters. This was raised in https://github.com/tldr-pages/tldr/pull/2793#issuecomment-506255809, and possibly elsewhere, but there doesn't seem to be a dedicated issue for tracking this. Quoting my comment from there:

Long lines typically mean we're trying to explain complex concepts, and the line limit could help identify and tackle those cases.

I see it as similar to our limit to the number of examples per page, and perfectly in line with our mission of TL;DR-ing manpages and complex documentation.

For future reference, it's also related to the (vertical) size limit discussed in #686 and in #1149 (and entered into the contribution guidelines in f0d4c16 following the latter).

[mebeim]

Just a note about your comment:

Makes sense. We can start with neverwrap and remove it later if we agree on a limit.

Seems like normally without neverwrap lines longer than 80 characters are wrapped, and this is an hardcoded limit, so we cannot really remove the neverwrap option unless we agree on a strict limit <= 80 (and even then, I would keep it anyway to avoid breaking builds assuming it isn't used).

[sbrl]

I think we'd need to be careful to apply the length limit to example descriptions and the description lines only. Some commands are just long, and it's unavoidable. I think there was a page I contributed a while back that displayed dialog boxes which had long commands, but it was just the way the command worked.

[mebeim]

Yeah @sbrl, that page (whiptail) is a perfect example of a simple yet very long command. It actually was the main reason we increased the current Markdown linter line length limit to 250 in #2965.

[waldyrious]

I'm fine with only applying the line length limit to the command descriptions, since that's what we have editorial control over (we can't change the syntax of commands). Would that be an acceptable compromise?

[mebeim]

@waldyrious agree. Not really sure where to add such check though... maybe a different "homemade" script? Since the linter checks every single line.

PS: just saw #3144... and woah french descriptions are way longer than I expected.

[waldyrious]

Yes we have been discussing an upgrade of the linter; it would certainly be easier to implement this after that is in place.

[sbrl]

Yeah. The linter does need to be easier to maintain. We've got a page on the wiki about it, if anyone's interested.

[mebeim]

Just to have an idea about the current situation, here's a list of which pages would be affected by which limits (generated with this script I wrote). Only page description and example descriptions are checked against the limit.

Limit 250: 0 pages over the limit.
-----------------------------------------------------------------
Limit 240: 0 pages over the limit.
-----------------------------------------------------------------
Limit 220: 0 pages over the limit.
-----------------------------------------------------------------
Limit 200: 1 page over the limit.
pages/common/xargs.md                               204 (4 over)
-----------------------------------------------------------------
Limit 180: 2 more pages over the limit.
pages/common/mosquitto_pub.md                       187 (7 over)
pages/common/q.md                                   187 (7 over)
-----------------------------------------------------------------
Limit 150: 22 more pages over the limit.
pages/common/renice.md                              180 (30 over)
pages/linux/run-mailcap.md                          178 (28 over)
pages/linux/top.md                                  177 (27 over)
pages/common/mongorestore.md                        176 (26 over)
pages.it/common/dc.md                               174 (24 over)
pages.pt-BR/linux/as.md                             172 (22 over)
pages/common/kak.md                                 169 (19 over)
pages.pt-BR/linux/arp-scan.md                       168 (18 over)
pages.fr/common/ssh.md                              165 (15 over)
pages.it/common/bedtools.md                         165 (15 over)
pages.pt-BR/linux/dmesg.md                          160 (10 over)
pages/linux/aptitude.md                             160 (10 over)
pages/osx/textutil.md                               159 (9 over)
pages.it/common/alias.md                            156 (6 over)
pages/common/dc.md                                  156 (6 over)
pages/common/ssh.md                                 156 (6 over)
pages.fr/common/install.md                          155 (5 over)
pages/common/finger.md                              155 (5 over)
pages/common/mosquitto_sub.md                       155 (5 over)
pages.pt-BR/common/alias.md                         154 (4 over)
pages/osx/launchctl.md                              153 (3 over)
pages.it/common/cpio.md                             151 (1 over)
-----------------------------------------------------------------
Limit 140: 13 more pages over the limit.
pages/common/bedtools.md                            149 (9 over)
pages/common/ldapsearch.md                          148 (8 over)
pages/common/sendmail.md                            148 (8 over)
pages.it/common/alex.md                             146 (6 over)
pages.it/common/assimp.md                           146 (6 over)
pages.pt-BR/linux/apt-get.md                        146 (6 over)
pages.pt-BR/linux/aptitude.md                       146 (6 over)
pages/common/cpio.md                                145 (5 over)
pages.it/common/autossh.md                          143 (3 over)
pages/osx/tree.md                                   143 (3 over)
pages/common/rbash.md                               142 (2 over)
pages.it/common/badblocks.md                        141 (1 over)
pages/common/fold.md                                141 (1 over)
-----------------------------------------------------------------
Limit 100: 228 more pages over the limit (avoiding listing).
-----------------------------------------------------------------
Limit 80: 416 more pages over the limit (avoiding listing).
-----------------------------------------------------------------

[jake-stewart]

the 80 column limit is the de facto standard.

screens have gotten wider, though if the 80 column limit is respect, it allows multiple panes side by side without readability issues.

i have found this tool today and i really like the concept. i do find the wrapping lines annoying. take for example the zip tldr:

    zip -r path/to/compressed.zip path/to/file_or_directory1 path/to/file_or_directory2 ... -x path/to/excluded_files_or_directories

the extra noise actually makes it less readable as the main concept of -x is drowned out. this example could be easily reduced to:

    zip -r compressed.zip included included2 ... -x excluded

i am aware that some commands are long by nature as @mebeim mentioned with whiptail. however, the 80 column limit can still be respected with escaped newlines:

    {{result_variable_name}}=$(whiptail --title "{{title}}" \
        --menu "{{message}}" {{height_in_chars}} {{width_in_chars}} \
        {{menu_display_height}} "{{value_1}}" "{{display_text_1}}" \
        "{{value_n}}" "{{display_text_n}}" ..... 3>&1 1>&2 2>&3)

of course, this makes copying and pasting less convenient. this is a matter of personal preference. since it is a matter of personal choice, the only rational choice is a config option or flag.

the easiest implementation would be to have a simple formatter which breaks long commands down via word wrapping. this word wrapping would not break down strings and would append a backslash to the end of the line. this approach would not require rewriting any tldr files. i believe this should be implemented alongside rewriting some tldr files. for example, the zip tldr should be written to be less verbose since the verbosity makes it less readable for all users regardless of whether it is wrapped or not.

i would be willing to create a pull request if the maintainers are happy with this approach.