Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Reading info and man pages

reading man and info pages

Created Sunday 08 April 2018

intro - man, help, info

Always read man pages, help pages, and info pages.

TIP: If you are new to *nix, don't expect to understand very much of the manuals when reading and trying stuff in the very first few attempts. It will really depend a lot on your background.

man

man man
man --help
man foo

Bash has builtin commands, like help, pwd, type, and cd.

type cd
# →  cd is a shell builtin

help

help is a builtin command that gives help on other builtin commands. To list all builtin commands, simple do:

help

And to see the help for a builtin, you can either do man bash and search for that command or do.

help <some builtin command>

info

First:

man info
info --help
info info

Generally, info pages are more user-friendly and tutorial-like than man pages. To read info pages, do

info <program or command>

like

info ed
info sed
info bash

You can also open info directly into a section of an info document (if you know the name of the section, that is), something like:

info sed 'execution cycle'

From GNU Emacs, you can read the info pages with

C-h i m <command>

For example:

C-h i m sed

Info has a lot of nomenclature, concepts and commands. info info explains about commands to find stuff inside info, navigate documents, etc. It is a somewhat complex system. Yet, a powerful one.

understanding man pages

Take a look:

man cp

Then you see:

NAME cp - copy files and directories

SYNOPSIS cp [OPTION]... [-T] SOURCE DEST cp
[OPTION]... SOURCE... DIRECTORY cp [OPTION]... -t DIRECTORY SOURCE...

Let's understand the man page syntax.

"cp" is the name of the command or program. No mistery.

Anything inside "[" and "]" means that thing is optional. In this case, [OPTION] means that command line options are optional, that is, you can do something like

cp -v foo bar

or simply

cp foo bar

Where -v is an option to the command (and since it is optional, it is up to you to use it or not) and "foo" and "bar" are files (you are making a copy of ‘foo’ and naming that copy as ‘bar’).

When you see SOMETHING followed by ..., like in [OPTION]... or SOURCE..., it means that thing may occur more than one time. If something is optional, it may occur zero or more times. If that thing is required, then may occur one or more times. So, in the case of

cp [OPTION]... SOURCE... DIRECTORY

it means we must use cp, followed by zero or more command line options. Then, SOURCE... is required, but it can occur more than once. Finally, DIRECTORY is required, and must occur only once.

Copy three files to a backup directory. We use vi options, which mean ‘verbose’ and ‘interactive’ (read about them in the man page):

cp -vi file1 file2 file3 bkpdir/

another man page example

One of the popular Scheme interpreters (repl) is “Chicken”, and its command line tool is csi (chicken scheme interpreter, for the command line repl).

csi -help

produces

usage: csi [FILENAME | OPTION ...]

Note that we have the square braces enclosing two things, and there is a "|" (the pipe character) between those two things. That character means 'OR', that is, either one thing, or the or the other. It doesn't mean “invoke csi followed by a filename followed by an option.” Nope, that is incorrect. What that means is either one of these:

csi program.scm

or

sci <some option>

but this is INCORRECT:

sci program.scm <some option>

On the other hand, if you look at the csi man page (or sci -help), you'll see that some options require a file name, like the -s (or -script) option.

The moral is that the man page shows something that can be easily misunderstood:

csi [FILENAME | OPTION ...]

Can lead one to think the syntax is:

sci program.scm -s

which is incorrect. The correct is either:

sci program.scm

or (because the option -s takes a filename)

sci -s program.scm

That is, csi filename or csi <option>, just that some options require a filename after the option itself.

where is the help for `for'?

help for shows help for the "for in" construct. How to make it show help for the for (( ... )) one? <go|dfish> FernandoBasso: well, (( )) is not part of for. help '((' <go|dfish> !(( ((...)) is an arithmetic command, which returns an exit status of 0 if the expression is nonzero, or 1 if the expression is zero. Also used as a synonym for "let", if side effects (assignments) are needed. See <http://mywiki.wooledge.org/ArithmeticExpression>. go|dfish, help lists all build in commands. It shows "for NAME..." and "for (( ..." I understood that as if those are two different for constructs. Anyway, thanks for helping. FernandoBasso, http://www.gnu.org/software/bash/manual/bashref.html#index-for !cfor C-style for loop: for (( expr; expr; expr )); do COMMANDS; done # Each expr is done in a math context. Example: for ((i=1; i<=n; i++)); do echo "$i"; done. Use in place of the non-working: for i in {1..$number}

So:

help '(('

Also see [http://www.gnu.org/software/bash/manual/bashref.html#index-for[bash's] manpage section].

for ((i = 1; i < 15; i += 3)) do echo $i ; done

If you do echo $- from inside a script, it won't show i. And ' foo ' bar.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.