Simplified man pages

[Jerry3904]

This is interesting and useful--makes me wonder if we could make use of them somehow:

The TDLR-pages project has compiled a collection of simplified manual pages which present commands with a clear explanation of what each command does and lists examples of how the command is most often used.

http://distrowatch.com/dwres.php?resource=man-pages

[Gordon Cooper]

Been thinking about something similar for a couple of years - but never did anything about it. Did print off several pages of Bash commands in an endeavour to use the
CL more often but dunno where those pages are now. Will take a look at TDLR.

[Richard]

This is a great idea!
It is actually the "TLDR-pages" project
at https://github.com/tldr-pages/tldr

[Jerry3904]

I think so too, and have asked the Dev Team to look into what we could do with that in MX Linux.

[skidoo]

announced in the Jan 31, 2017 distrowatch weekly newspage:
DistroWatch now hosts [TLDR] simplified manual pages...
We hope this will provide our readers with a quick and easy way to discover what a program does and how it is to be used.

Simplified Manual Pages http://distrowatch.com/dwres.php?resource=man-pages
A collection of simplified man(ual) pages

The standard set of manual pages (often called man pages) which are available in most flavours of Linux, BSD and Unix tend to be long and they can be cryptic. Manual pages tend to list what options are available without explaining why we might use them. Further, many manual pages do not provide examples.

The TDLR-pages project ( github.com/tldr-pages/tldr ) has compiled a collection of simplified manual pages which present commands with a clear explanation of what each command does and lists examples of how the command is most often used.

{{{ use the selectbox below to choose from a set of 500 or so command names, then click the "Go" button }}}

Writing clear documentation is hard work, so I appreciate their (TLDR and DW) effort
(emphasizing clarity here, having thrown in the towel regarding maintenance of comprehensive, up-to-date, documenation)
but a successful documentation effort requires achieving efficacious effective delivery, and ISTM they both (TLDR and DW) fail in this regard.

The DW lookup page, who will (want to) use that, forpetesake?
Should we pity the fool who wanders in via google search results, wades past sidebar ads and sitenav and whatnot to read the paltry 2 or 4 sentences?

Mommy, what's a "wacaw" ?
Will the seeker realize (no in-page explanation/disclaimer) the dropdown is populated with a mishmash of SunOS and macOS and linux commands?
Even if this "new DW feature" isn't an outright bullsh** search-engine-bait ploy... it seems more like a disservice, than service, to readers.

http://tldr-pages.github.io/

Try the live demo [ https://tldr.ostera.io/ ], have a look at the [ PDF version ], or follow the [ installation instructions ].

Using firefox 45esr here at the moment, and the "live demo" didn't do jack**** when I visited.
Installation? Hahaha... no. (and OMG all the framework crap involved... and they propose to curl http:/gitmeuptodate | sudo -h somescript.sh)
Aaaaargh! ...AND A SIDE ORDER OF FRIES!!!

on a brighter note:
Their pdf, at least it provides a collapsible hierarchy, separating the listed SUNOS and macOS commands from the leenooks commands.

========================
A link to http://commandlinefu.com within the MX helpdocs would be a useful addition
(user can see usage examples of various commands, can search for a given command name)
along with the caveats:
Be mindful when running 'code found online'
and
Never copy/paste web-snipped code directly into terminal !
ref: https://nakedsecurity.sophos.com/2016/0 ... web-pages/
ref: http://thejh.net/misc/website-terminal-copy-paste
ref: https://news.ycombinator.com/item?id=5508225
ref: https://www.reddit.com/r/netsec/comment ... inal_demo/

[aus9]

FWIW man pages can be learnt.

http://unix.stackexchange.com/questions ... r-a-script

they are just a text file with special syntax or formatting rules.

eg

Code: Select all

man inxi

eg after unpacking the gunzipped man page we have

.B \-v 2
\- Adds networking card (\fB\-N\fR), Machine (\fB\-M\fR) data, Battery (\fB\-B\fR) (if available), and shows basic hard disk data
(names only). Same as: \fBinxi \-b\fR
.TP

which looks like this in man reader



which is first make v 2 in bold

in the following text also make some other stuff bold eg N M B and "inxi -b"

2) you can then put your modified man page into /usr/share/man/man<number> and run it after repack

or if you have translators put it in /usr/share/man/locale/man<number>

##### I give the suggestions, you do the work

[Stevo]

I've packaged the little C command line interface version which one of our GUI tools could either use the output or maybe yoink code from--it has the MIT license, which is basically "go nuts with it".

[Richard]

tldr
Definitely a benefit to see usage of options and params.

Kinda slow reading the list.
Are the data files incorportated? Maybe this would speed it up.
Or are they being downloaded?

[Stevo]

tldr
Definitely a benefit to see usage of options and params.

Kinda slow reading the list.
Are the data files incorportated? Maybe this would speed it up.
Or are they being downloaded?

Heh, heh...run

Code: Select all

tldr tldr

to see how to download the database to your machine--it's pretty small at the moment.

[cpoakes]

While examples are sorely needed to illustrate the simple use cases of difficult commands like find, awk, or grep, or commands overloaded with options like chown or chmod, I am disappointed with the implementation and conceptualization. Some of the simple pages are not significantly different than the actual man pages like which. Some provide too little information to be useful like bash, vim or zsh and probably never can. Others have the bare essentials, but much is missing.

If the actual man pages were modified to have an EXAMPLES section (missing in grep), include simple use cases (horribly advanced in awk examples), and/or cover a single command (unravel gzip/gunzip/zcat), the naive user would have everything in one place. As is, all but the newbies are going to encounter enough shortfalls to realize they need the man pages, tire of two sources, and skip the simple ones entirely.