Hacker News Reader

Comment by dom0 | Hacker News Reader

> Note that the "rule of silence" (combined with the habit of writing documentation like longform essays) is also one factor that makes unix-like systems newbie-unfriendly. (Famous example: trying to exit vi)

    $ man foo
    *scroll to the end with the EXAMPLES section*

There should be an option for that. man --take-me-to-the-examples foo

View on HN

(NOTE: The parent comment was edited. This response applies to the original parent comment that contained just the command line ("man foo" + EXAMPLE section) and nothing else.)

Wow, I haven't seen such a blunt and unhelpful RFTM comment for a while. This comment is inappropriate in so many ways:

1) The unix systems have an inconsistent documentation mix of man pages, info pages, "-h", "-help", "--help", HTML docs, separate manuals (e.g. Debian Administrator's Handbook) and so on.

2) "man foo" leads to: "No manual entry for foo"

3) "man vi", as well as "man vim" both lead to a manpage that has no EXAMPLES section at all (see https://www.freebsd.org/cgi/man.cgi?query=vi, https://www.freebsd.org/cgi/man.cgi?query=vim)

4) The Vi(m) manpages explain only the command line arguments, not the editor commands. The latter are available by typing ":help" in the editor.

You don't really need an "examples" section for vim, 90% of the time you just type "vim file" which the usage info probably covers well enough. You only need an "examples" section for something like zip.

> you just type "vim file" which the usage info probably covers well enough

This is wrong. If you just type "vim file", you don't get any usage info, not even in the status line. See also: https://news.ycombinator.com/item?id=13165795

You might find this intersting:

https://github.com/tldr-pages/tldr

Thanks for this, you've just made my day!

That project is a symptom of manual pages not having good “EXAMPLES” sections. The examples on that web page should be contributed upstream to the manuals pages of the software that they are for.

The issue isn't just the lack of EXAMPLES, but also with how man pages tend to be structured. They tend to be very "encyclopedic". There is a set ordering for sections, with a lot of them very verbose, and examples, when present, near the end. Options are often listed in alphabetic order, which doesn't usually correspond to how often they are used or useful.

Man pages are OK when you're first learning how to use something; but if you're already familiar with a command and just need to remind yourself of a the specific sequence of options to achieve a desired result, they're not the most convenient.

I think it's useful to have a tool that fulfills the latter purpose without worrying about the former.

Microsoft documentation was mentioned earlier in this discussion. One of the things that MSDN and TechNet doco does is have both "X reference" and "using X" sections. Manual pages are reference doco, in this way of organizing things.

The FreeBSD, TrueOS, and related worlds put the "using" doco into what are often called "handbooks" or "guides".

* NetBSD Guide: https://netbsd.org/docs/guide/en/

* FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html

* DragonFlyBSD Handbook: https://www.dragonflybsd.org/docs/handbook/

* TrueOS User Guide: https://www.trueos.org/handbook/trueos.html

* PC-BSD User Guide: http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html (viewable off-line directly in both PDF and HTML forms in /usr/local/share/pcbsd/doc/)

Some parts of the Linux world do the same. upstart had the Upstart Cookbook for example:

* http://upstart.ubuntu.com/cookbook/

The Linux Documentation Project was supposed to contain a wealth of this stuff, but large parts of it are seemingly moribund, and incomplete after decades or woefully outdated. Wikibooks tried to take up the slack with an "anyone can edit" Guide to Unix and a Linux Guide:

* https://en.wikibooks.org/wiki/Guide_to_Unix

* https://en.wikibooks.org/wiki/Linux_Guide

If you want examples and doco that works from the basis of what you usually want to do, then these handbooks and guides are the places to go, not reference manuals.

Whenever the discussion comes up about man pages and how documentation should be organized, I like to quote this section from the GNU coding standards about how Info documentation is structured:

----

Programmers tend to carry over the structure of the program as the structure for its documentation. But this structure is not necessarily good for explaining how to use the program; it may be irrelevant and confusing for a user.

Instead, the right way to structure documentation is according to the concepts and questions that a user will have in mind when reading it. This principle applies at every level, from the lowest (ordering sentences in a paragraph) to the highest (ordering of chapter topics within the manual). Sometimes this structure of ideas matches the structure of the implementation of the software being documented--but often they are different. An important part of learning to write good documentation is to learn to notice when you have unthinkingly structured the documentation like the implementation, stop yourself, and look for better alternatives.

[…]

In general, a GNU manual should serve both as tutorial and reference. It should be set up for convenient access to each topic through Info, and for reading straight through (appendixes aside). A GNU manual should give a good introduction to a beginner reading through from the start, and should also provide all the details that hackers want. […]

That is not as hard as it first sounds. Arrange each chapter as a logical breakdown of its topic, but order the sections, and write their text, so that reading the chapter straight through makes sense. Do likewise when structuring the book into chapters, and when structuring a section into paragraphs. The watchword is, at each point, address the most fundamental and important issue raised by the preceding text.

https://www.gnu.org/prep/standards/standards.html#GNU-Manual...

See also http://bropages.org

User-submitted and voted-upon examples for commands.

(hadn't seen tldr, looks great, I'll check it out)

If you want a fast way to read the EXAMPLES section only for a command, here is a shell function which creates an ‘eg’ command which only displays the “EXAMPLES” section of manual pages:

  eg(){
      MAN_KEEP_FORMATTING=1 man "$@" 2>/dev/null \
          | sed --quiet --expression='/^E\(\x08.\)X\(\x08.\)\?A\(\x08.\)\?M\(\x08.\)\?P\(\x08.\)\?L\(\x08.\)\?E/{:a;p;n;/^[^ ]/q;ba}' \
          | ${MANPAGER:-${PAGER:-pager -s}}
  }

 Usage:

  $ eg tar
  EXAMPLES
       Create archive.tar from files foo and bar.
             tar -cf archive.tar foo bar
       List all files in archive.tar verbosely.
             tar -tvf archive.tar
       Extract all files from archive.tar.
             tar -xf archive.tar
  $

Here's mine:

  examples ()
  {
    man $1 | less +/^EXAMPLES
  }

Usage:

  $ examples su
  EXAMPLES
       su -m man -c catman
              Starts a shell as user man, and runs the command catman.  You will
              be asked for man's password unless your real UID is 0.  Note that
              the -m option is required since user “man” does not have a valid
              shell by default.  In this example, -c is passed to the shell of
              the user “man”, and is not interpreted as an argument to su.
       su -m man -c 'catman /usr/share/man /usr/local/man'
              Same as above, but the target command consists of more than a
              single word and hence is quoted for use with the -c option being
              passed to the shell.  (Most shells expect the argument to -c to be
              a single word).
       su -m -c staff man -c 'catman /usr/share/man /usr/local/man'
              Same as above, but the target command is run with the resource
              limits of the login class “staff”.  Note: in this example, the
              first -c option applies to su while the second is an argument to
              the shell being invoked.
       su -l foo
              Simulate a login for user foo.
       su - foo
              Same as above.
       su -   Simulate a login for root.

You probably still want the MAN_KEEP_FORMATTING=1 part, to keep colorization and bolding etc. in the manual page. Also, your solution does not respect the user’s pager preference; the user might prefer to read man pages in “w3m”, for instance.

>You probably still want the MAN_KEEP_FORMATTING=1 part, to keep colorization and bolding etc. in the manual page

Underlining is the only formatting I care about and that works without MAN_KEEP_FORMATTING on FreeBSD.

I don't have colorization enabled in man pages on my laptop, and also I don't have bolding enabled either. I like it this way.

>your solution does not respect the user’s pager preference; the user might prefer to read man pages in “w3m”, for instance.

The pager preference of the user in this case is `less`. I know because the user happens to be myself :^)

Reply on news.ycombinator.com