141–150 of 169 posts
Man pages should not be "simplified". They should be easy to read, but comprehensive. How comprehensive? I literally learned NetBSD kernel programming by reading man pages. The same with learning how to write X programs two decades ago.
Anyone ever get anything useful out of info pages (vs man pages)? I never quite got what their deal was.
.Dd $MDocDate$
.Dt LS tldr common
.Sh NAME
.Nm ls
.Nd List directory contents.
.Sh EXAMPLES
.Bl -hyphen -offset ds
.It
List files one per line
.Pp
.Nm ls Fl l
.Pp
.It
List all files, including hidden files
.Pp
.Nm ls Fl a
.Pp
.It
Long format list (permissions, ownership, size and modification date) of all files
.Pp
.Nm ls Fl la
.Pp
.It
Long format list with size displayed using human readable units (KB, MB, GB)
.Pp
.Nm ls Fl lh
.Pp
.It
Long format list sorted by size (descending)
.Pp
.Nm ls Fl lS
.Pp
.It
Long format list of all files, sorted by modification date (oldest first)
.Pp
.Nm ls Fl ltr
.ElEarlier quoted context omitted.
Yup, and the examples section is usually last, with no possibility to jump directly to it
You can jump to it by typing /EXAMPLES Or if that seems like a lot of keystrokes, /EX will probably jump to what you want most of the time too.
> man less
/EX
pattern not found
/ex
ends up somewhere in the middle of the text
on a word that contains exEarlier quoted context omitted.
I must admit I'm not a fan of this. I feel like the work could go towards submitting patches to the man pages. The MAN page layout [0] allows for an EXAMPLES section which serves this purpose. Great effort in creating this tool but I think it's replicating functionality already provided by the man pages. I've submitted patches for MAN pages for GNU tools in the past and the creators are very receptive to updates. [0]…
Yup, and the examples section is usually last, with no possibility to jump directly to it
Earlier quoted context omitted.
> Man pages are manual pages, not howto pages. Isn't that a made-up distinction though? Who said manuals can't have representative examples for how to do certain tasks? Product manuals (including software product manuals) almost always do. They don't just enumerate features and flags.
> 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.
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
Earlier quoted context omitted.
dash is web documentation kept offline with limited search added on top of it. it's basically a browser window...
Which already makes it orders of magnitudes better than man
Earlier quoted context omitted.
I must admit I'm not a fan of this. I feel like the work could go towards submitting patches to the man pages. The MAN page layout [0] allows for an EXAMPLES section which serves this purpose. Great effort in creating this tool but I think it's replicating functionality already provided by the man pages. I've submitted patches for MAN pages for GNU tools in the past and the creators are very receptive to updates. [0]…
Yup, and the examples section is usually last, with no possibility to jump directly to it
How about '/examples'? Maybe you should take some time to actually learn how 'man' works before you start bashing it online...
I 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…
The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. The synopsis typically lists a bunch of command-line variations with literally no context, not even a line of commentary to tell the difference between the variations. Then comes a description, which is…
On a real UNIX like illumos and SmartOS, EXAMPLES are mandatory; I’ve no idea why people believe they may be optional, as they are one of the biggest reasons why someone would call up a manual page. It’s a manual.