Not a fan of needing npm. Why not provide a binary? Or did I miss that?
Maintainer here. You are free to use the C++ or Go or Rust client. Use a binary all you want.
Npm is just one client.
Simplified and community-driven man pages
161–169 of 169 posts
Re: Simplified and community-driven man pages
#162Oh my, someone please document tc, iptables and ffmpeg.
Maintainer here. iptables and ffmpeg are already there. You are most welcome to send a PR for tc :)
Re: Simplified and community-driven man pages
#163I was lucky to first be introduced to man pages by someone who often just called them "manuals" and (to my best recollection) explained them by telling me "Manuals are to be read, top to bottom, contemplated, and maybe read again, before you act." Thus I was never under the delusion that man pages were, or should strive to be, How-To's of some sort. This TLDR tool definitely needs to exist, but in conjunction with ma…
Maintainer here.
> This TLDR tool definitely needs to exist, but in conjunction with man pages, not as a replacement.
tldr is _exactly_ that. We do not and will not aim to replace man pages. We have a hard limit of 8 examples at max for every command. Therefore, our scope is very limited and we try to mention the 8 most important and practical examples a beginner needs to know for a command.
If someone needs to go deeper, man pages are always there.
Re: Simplified and community-driven man pages
#164It would be very nice to have some way of integrating this into OhMyZSH as a plugin. OMZ can already do extraction of command line arguments by tab completion (and it will attempt to make a brief description of what the flag does) [0][1]. It might be nice to be able to type "tldr compress a folder into a tarball" and click tab to have a set of templates suggested to you. You can navigate to them and click enter to re…
Maintainer here.
The node client already has autocompletion for OMZ users - https://github.com/tldr-pages/tldr-node-client#zsh.
It also supports command search. So you can do `tldr search "compress a folder into a tarball"`. And you will be shown the top 10 matches. Yes, its not exactly autocompletion. It's more of a match to the apropos command.
Re: Simplified and community-driven man pages
#165Earlier quoted context omitted.
> Who said manuals can't have representative examples for how to do certain tasks? Dennis Ritchie defined what goes into the manual in the 3rd edition of UNIX, at the behest of Doug McEllroy. Ken Thompson also did some work on man pages, and I believe Lorinda Cherry was involved too. As I understand it (and I could be wrong though) the terseness of man pages was Ritchie's design, with input from Thompson.
Which might have been good for late 70s -- and the main users being academics and the designers of the system itself, but might not be as good for late 2010s. Besides, we already have the Examples section, would it be too much to ask to have it better (or at least somewhat) utilized in all manpages? We could even have different sections, shown with flags, and keep regular output as it is. man --examples foocommand
You clearly don't understand core Unix philosophy[1]. It's this that drives commands like man, that have been around since 3rd edition Unix.
You're failing to understand who the main users of Unix were (Bell, a telecoms company. Academics didn't start using Unix in anger until the late 70s, by which point Unix had been established for about 3-7 years within AT&T/Bell depending on whether you count Berkeley and Illinois's initial use as academia, or it's more widespread adoption following the release of the BSD distribution and V7/V32).
Before you start complaining about man pages, consider that in order to access them on your shiny new computer that it simulates a 1970s era virtual terminal, which itself emulates an advanced 1960s era teletype terminal to display it.
The problem isn't man pages. They do their job generally well. The problem is that you want man pages to do something they aren't designed for, and will not change to. Use /usr/share/docs or info instead. That's what these things are there for.
Re: Simplified and community-driven man pages
#166Earlier quoted context omitted.
Which might have been good for late 70s -- and the main users being academics and the designers of the system itself, but might not be as good for late 2010s. Besides, we already have the Examples section, would it be too much to ask to have it better (or at least somewhat) utilized in all manpages? We could even have different sections, shown with flags, and keep regular output as it is. man --examples foocommand
You clearly don't understand core Unix philosophy[1]. It's this that drives commands like man, that have been around since 3rd edition Unix. You're failing to understand who the main users of Unix were (Bell, a telecoms company. Academics didn't start using Unix in anger until the late 70s, by which point Unix had been established for about 3-7 years within AT&T/Bell depending on whether you count Berkeley and Illino…
>You clearly don't understand core Unix philosophy[1].
That's because it's trite cargo cult. And even worse, it's totally unapplicable to our discussion, as it pertains to program design, not how to write or what to include in a man page. man, the program, would still just be a simple manpage showing program.
Besides it, and other basic unix core utils and userland programs, have adopted 10,000s of flags and new functionality over the years, to the point that shooting down my --examples suggestion for "breaking the unix philosophy" is total BS.
Heck, Emacs includes everything AND the kitchen sync, but it's a much beloved part of Unix tradition.
>It's this that drives commands like man, that have been around since 3rd edition Unix.
Tradition doesn't make it right. Where's the science? How about some actual measurements of levels of head-banging of users between different approaches?
Also note that I started on Sun OS, when Solaris was a new unstable OS, and have used HPUX, IRIX and other such flavors in workstations of the time (and actual VT terminals). I'm not some teenager that got into Linux with the latest Ubuntu.
>The problem is that you want man pages to do something they aren't designed for, and will not change to.
Sorry, you've already lost that battle. Lots of manpages already have EXAMPLES sections. It's just that not enough attention has been paid to their content.
Re: Simplified and community-driven man pages
#167Earlier quoted context omitted.
You clearly don't understand core Unix philosophy[1]. It's this that drives commands like man, that have been around since 3rd edition Unix. You're failing to understand who the main users of Unix were (Bell, a telecoms company. Academics didn't start using Unix in anger until the late 70s, by which point Unix had been established for about 3-7 years within AT&T/Bell depending on whether you count Berkeley and Illino…
> You clearly don't understand core Unix philosophy[1]. That's because it's trite cargo cult. And even worse, it's totally unapplicable to our discussion, as it pertains to program design, not how to write or what to include in a man page. man, the program, would still just be a simple manpage showing program. Besides it, and other basic unix core utils and userland programs, have adopted 10,000s of flags and new fun…
> it's totally unapplicable to our discussion
Wait, we're talking about the Unix man command, and you're saying that the fundamental philosophy upon which this command's entire design and purpose is based is somehow unapplicable? Really?
> but it's [EMACS] a much beloved part of Unix tradition.
No. EMACS is not part of the Unix tradition. EMACS was invented before Unix at MIT. Unix was invented at Bell Labs. EMACS was designed for an OS called ITS as a successor to the TECO editor (developed in 1962). You're getting mixed up with vi, which was created for Unix by Bill Joy in the 70s as a separate mode for ex, which was a successor to ed.
You're possibly thinking of GNU EMACS, which would be ironic, considering that GNU is an acronym that stands for "GNU's Not UNIX".
The Operating Systems you or I have used aren't really relevant to the discussion. I can see that you may have filled in context that wasn't there and assumed I'm some old unix beard telling you to get off my lawn. That's not the case.
I have two points:
1. Man exists because of specific documented conventions. Man pages are the way they are because they're expected to follow conventions built over the past 40 years.
2. There are places that howto documentation belongs in most Unix-derived OSes, certainly for anything BSD derived and anything following the Linux Filesystem Hierarchy Standard.
Take a step back and try to see what I'm seeing. I see someone who seems to insist that we should change a specific 40+ year old convention to suit environments that implement other 40+ year old conventions, when there's already a place for the things they want (again thanks to explicit and implicit convention and documentation). It's not going to happen.
You are not going to get Apple, Red Hat, Debian, Ubuntu and the BSDs to change the way they've done things forever to suit your whims. You're also definitely not going to get them to change them when perfectly functional alternatives already exist.
Re: Simplified and community-driven man pages
#168Earlier quoted context omitted.
People who complain about man pages tend not to understand man pages. Man pages aren't howto documentations. They're very specifically designed to document the different components of a command, call or configuration file. OP is absolutely spot on about man pages being community driven. At least half the time someone complains to me about a man page, the man page is the wrong place to look. Usually, the answer they'r…
"People who complain about man pages tend not to understand man pages." There could not be a more valid complaint. If the man pages aren't understandable, what program is supposed to explain them?
There isn't really a single program. Man pages have been built through convention by people who've taken the time to write them, at various points following guidelines from Ritchie et al. It's usually down to the OS to explain the purpose and function of man pages in their own documentation.
For some Operating Systems, man pages are exceptionally high quality (most notably the BSDs). For some, they're bilge, but such systems tend to have init managed through systemd.
Having said that, many OSes support info(1), which provides more detailed software manuals for many pieces of software.
Of course, there are actual physical locations for forms of documentation not in man format or structure. You can find out where such documentation lives on your system on most Unix-like OSes through man:
$ man hier
Re: Simplified and community-driven man pages
#169Earlier quoted context omitted.
I disagree. man pages are optimized for time spent. The cryptic synopsis at the top is enough if I’m checking a frequently used command. The examples are at the bottom for newbies, which need to spend some time reading anyway. man pages are not «good documentation», they are there for people who need to quickly figure out how to run a command. Good projects should have tutorials and complete references online in addi…
Why should good documentation not be bundled with the product?
Sure. Cmake has a brief man page and a big bulky HTML manual.