Page 1 of 2
Simplified man pages
Posted: Tue Jan 31, 2017 7:26 am
by 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
Re: Simplified man pages
Posted: Tue Jan 31, 2017 3:57 pm
by 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.
Re: Simplified man pages
Posted: Tue Jan 31, 2017 4:45 pm
by Richard
This is a great idea!
It is actually the "TLDR-pages" project
at
https://github.com/tldr-pages/tldr
Re: Simplified man pages
Posted: Tue Jan 31, 2017 4:47 pm
by Jerry3904
I think so too, and have asked the Dev Team to look into what we could do with that in MX Linux.
!
Posted: Tue Jan 31, 2017 5:09 pm
by 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.
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/
Re: Simplified man pages
Posted: Tue Jan 31, 2017 6:13 pm
by 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
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
Re: Simplified man pages
Posted: Tue Jan 31, 2017 6:14 pm
by 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".
Re: Simplified man pages
Posted: Tue Jan 31, 2017 8:00 pm
by 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?
Re: Simplified man pages
Posted: Tue Jan 31, 2017 8:46 pm
by Stevo
Richard wrote: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
to see how to download the database to your machine--it's pretty small at the moment.
Re: Simplified man pages
Posted: Tue Jan 31, 2017 10:14 pm
by 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.
