================== Man, Info and Help ================== It is a good habit read man pages, help pages, and info pages instead of immediatelly jumping to a web search. .. 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 and previous experience, skills and expertise. Just keep trying. help ---- .. tip:: Read the document about *built-ins*. :ref:`built-ins-page`. Shells have built-in commands. Some of Bash's built-ins include commands like ``help``, ``pwd``, ``type``, and ``cd``. .. code:: shell-session $ type cd cd is a shell builtin ``help`` is a builtin command that provides usage information on other builtin commands. .. tip:: To see the list of Bash’s builtin commands, simply type ``help`` without any arguments. To display the help for a builtin, you can either do ``man bash`` and search for that command or, more simple, quick and practical, use the ``help`` builtin. Start with this: .. code-block:: shell-session $ help help $ help Yes, run ``help`` without arguments once to see a list of Bash's builtin commands. Then try some others: .. code:: shell-session $ help $ help help $ help builtin $ help . $ help source $ help command $ help [ $ help [[ $ help echo $ help printf # etc... info ---- First: .. code:: shell-session $ info info $ man info $ info --help .. note:: Of course, on Arch Linux, we are fine, but on Ubuntu, we need to ``apt install texinfo-doc-nonfree``. Generally, info pages are more user-friendly and tutorial-like than man pages. To read info pages, do .. code:: shell-session $ info $ info ed $ info sed $ info bash .. note:: Not all programs and commands have info pages, and when an info page does not exist for a given command, ``info`` shows the man page instead. ``vi``, ``vim`` and ``rsync`` are some such programs. You can also open info directly into a section of an info document (if you know the name of the section), something like: .. code:: shell-session $ info sed 'execution cycle' Programs in the *coreutils* group have an *invocation* section: .. code:: shell-session $ info coreutils $ info '(coreutils) echo invocation' $ info coreutils 'echo invocation' $ info '(coreutils) printf invocation' $ info coreutils 'printf invocation' $ info '(coreutils) kill invocation' $ info coreutils 'kill invocation' From GNU Emacs, you can read the info pages with: .. code:: text C-h i m # 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. info summary ~~~~~~~~~~~~ .. code:: shell-session $ info emacs --node Files $ info '(emacs)Files' $ info /usr/local/share/info/bash.info $ info ~/docs/doc.info $ info sed 'sed scripts' 'the "s" command' $ info emacs 'user input' Run ``info info 'moving the cursor'``. .. note:: ``META`` (or ``ALT``) can also be achieved by hitting ``ESC``, e.g. ``ESC-f`` for ``forward-word``. And ``ESC`` itself can be produced with ``C-[``. ``DEL`` is ``Backspace``. For a quick glance at *all* info commands and key bindings, open any info page, and press ``C-h``. man --- .. code:: shell-session $ man man $ man --help $ man foo When someone tells you something like “it is docummented in *some-command (3)*”, they mean it is in section 3 of the man pages. Then you would do ``man 3 some-command`` or ``man some-command.3``: A real example of that could be with the ``printf(1)`` command or ``printf(3)`` from the C Standard Library: .. code:: shell-session $ man 1 printf $ man printf.1 $ man 3 printf $ man printf.3 If we don’t know what a man page name would be, we can search the man page names and their sort descriptions by using ``-k``, which accepts a regular expression. By the way, ``man -k pattern`` is the same as ``apropos pattern``. .. tip:: If ``apropos`` or ``man -k`` says “nothing appropriate”, read ``man mandb`` and then run ``mandb`` as root. .. code:: shell-session $ man -k bc ... produces to many results... So, let’s match commands that start with “bc”: .. container:: formalpara-title **man -k ^bc on Ubuntu 19.04** .. code:: shell-session $ man -k ^bc bc (1) - An arbitrary precision calculator language bccmd (1) - Utility for the CSR BCCMD interface bcmp (3) - compare byte sequences bcopy (3) - copy byte sequence .. container:: formalpara-title **man -k ^bc on Arch Linux as of September, 2019** .. code:: shell-session $ man -k ^bc BC (3x) - direct curses interface to the terminfo capability dat... bc (1) - An arbitrary precision calculator language bc (1p) - arbitrary-precision arithmetic language bcmp (3) - compare byte sequences bcomps (1) - biconnected components filter for graphs bcopy (3) - copy byte sequence .. note:: On Ubuntu, *bc (1p)* wasn’t available, but it was on Arch Linux. .. note:: A “p” right after a section number of a man page means the standard POSIX program/behavior. “bc (1p)” refers to the POSIX specs and behavior, while Section numbers are more or less standard across Unix-like OSes, but the letters may vary. Finding Info Node Names ~~~~~~~~~~~~~~~~~~~~~~~ .. code:: shell-session $ info sed --output - | grep '^\*\s.\+::' * Introduction:: Introduction * Invoking sed:: Invocation * sed scripts:: 'sed' scripts * sed addresses:: Addresses: selecting lines * sed regular expressions:: Regular expressions: selecting text * advanced sed:: Advanced 'sed': cycles and buffers * Examples:: Some sample scripts * Limitations:: Limitations and (non-)limitations of GNU 'sed' * Other Resources:: Other resources for learning about 'sed' * Reporting Bugs:: Reporting bugs * GNU Free Documentation License:: Copying and sharing this manual * Concept Index:: A menu with all the topics in this manual. * Command and Option Index:: A menu with all 'sed' commands and $ info sed 'sed scripts' --output - | grep '^\*\s.\+::' * sed script overview:: 'sed' script overview * sed commands list:: 'sed' commands summary * The "s" Command:: 'sed''s Swiss Army Knife * Common Commands:: Often used commands * Other Commands:: Less frequently used commands * Programming Commands:: Commands for 'sed' gurus * Extended Commands:: Commands specific of GNU 'sed' * Multiple commands syntax:: Extension for easier scripting Then we use the names on the left column of the output above to read info for that command on that specific section. .. code-block:: shell-session $ info sed 'sed scripts' 'the "s" command' --output - | vim - $ info sed 'sed scripts' 'the "s" command' Or commands that end with “print” (but not “printf”, for example): .. code:: shell-session $ man -k print$ FcFontSetPrint (3) - Print a set of patterns to stdout FcPatternPrint (3) - Print a pattern for debugging FcValuePrint (3) - Print a value to stdout isprint (3) - character classification functions iswprint (3) - test for printing wide character print (1) - execute programs via entries in the mailcap file Bear in mind that all of these do the same thing: .. code:: bash man -k some_command man --apropos some_command apropos some_command To search on the entire text of the man pages, use: .. code:: bash man --global-apropos some_command man -K some_command Note that it is an uppercase “K” this time. \`cp' Man Page Example ---------------------- ``man cp`` produces this: .. container:: formalpara-title **Exerpt of \`man cp' on Arch Linux as of 2019** .. code:: text CP(1) User Commands CP(1) NAME cp - copy files and directories SYNOPSIS cp [OPTION]... [-T] SOURCE DEST cp [OPTION]... SOURCE... DIRECTORY cp [OPTION]... -t DIRECTORY SOURCE... DESCRIPTION Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY. Mandatory arguments to long options are mandatory for short options too. 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.txt foo.txt.bpk``, where ``-v`` is an *option*, or simply ``cp foo.txt foo.txt.bpk``, and not use ``-v`` or any other option at all. You can think as options as flags the enable, disable, or configure the way the program should behave. The three dots, ``…​``, like in ``[OPTION]…​`` or ``SOURCE…​``, 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 it has to occur one or more times. So, in the case of: .. code:: text 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. Recap: - ``[THING]`` optional and may occur at most once. - ``[THING]...`` optional and may occur zero or more times. - ``THING`` required and must occur exactly once. - ``THING...`` required and must occur one or more time. Since ``cp`` accepts multiple sources, we could copy more than one file at a time to a given destination directory. As an example, let’s copy three files to a backup directory. .. code:: shell-session $ cp main.c lib.h lib.c ~/bkpdir/ Suppose we want to use the options ``--verbose`` and ``--interactive`` (or their short versions, ``-v`` and ``-i``), we can do: .. code:: shell-session $ cp --verbose --interactive main.c lib.h lib.c ~/bpkdir/ And with the short option syntax, we can group options. All three commands below do the same thing: .. code:: shell-session $ cp --verbose --interactive foo.txt foo.txt.bpk $ cp -v -i foo.txt foo.txt.bpk $ cp -vi foo.txt foo.txt.bpk Note the ``-vi`` instead of ``-v -i`` in the last one! \`csi' -help Example -------------------- One of the popular Scheme implementations is “Chicken”, and its command line tools include ``csi`` (Chicken Scheme Interpreter, for the command line REPL) and ``csc`` (Chicken Scheme Compiler). .. note:: On some distros, the names are now ``chicken-csi`` and ``chicken-scs`` because there were conflicts with Mono’s C Sharp Compiler and Chicken Scheme Compiler. See this `Mono issue `__, this `Debian bug report `__, and this `Arch Linux bug report `__. .. note:: ``csi -help`` as of 2019 produces output different than showed here (as it was in 2017), but the examples and explanations are still very useful and enlightening. .. code:: shell-session $ csi -help 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: .. code:: shell-session $ csi program.scm # or $ sci # but this is INCORRECT: $ sci program.scm 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: .. code:: text csi [FILENAME | OPTION ...] Can lead one to think the syntax is: .. code:: shell-session $ sci program.scm -s which is incorrect. The correct is either: .. code:: shell-session $ sci program.scm or (because the option ``-s`` takes a filename) .. code:: shell-session $ sci -s program.scm That is, ``csi filename`` or ``csi