60

I understand what GNU Info is and how to use it, but what is it for? Why does it exist in parallel to the man pages? Why not write detailed man pages rather than provide a separate utility?

  • 3
    texinfo file can do a lot more the groff macros. – jordanm May 29 '13 at 14:45
  • 15
    It's got one advantage over man pages: "hyperlinks". The rest are disadvantes, starting with Not Invented Here Syndrom, funny key bindings, hassle of dir maintenance and many more. – Jens May 29 '13 at 21:59
  • 4
    Use info --vi-keys to make info's keybindings feel more familiar. You can also use less with info to make it feel just like man: info --subnodes -o - $1 | less. You do lose some text formatting this way though. – user26112 Jun 15 '13 at 11:12
  • 1
    Alternatively, point your browser at gnu.org/manual. (Using Vimperator/Vrome is optional.) – nwk Mar 9 '14 at 21:21
60

GNU Info was designed to offer documentation that was comprehensive, hyperlinked, and possible to output to multiple formats.

Man pages were available, and they were great at providing printed output. However, they were designed such that each man page had a reasonably small set of content. A man page might have the discussion on a single C function such as printf(3), or would describe the ls(1) command.

That breaks down when you get into larger systems. How would you fit the documentation for Emacs into man pages? An example of the problem is the Perl man page, which lists 174 separate man pages you can read to get information. How do you browse through that, or do a search to find out what && means?

As an improvement over man pages, Info gave us:

  1. The ability to have a single document for a large system, which contains all the information about that system. (versus 174 man pages)
  2. Ability to do full-text search across the entire document (v. man -k which only checks keywords)
  3. Hyperlinks to different parts of the same or different documents (v. The See Also section, which was made into hyperlinks by some, but not all, man page viewers)
  4. An index for the document, which could be browsed or you could hit "i" and type in a term and it would search the index and take you to the right place (v. Nothing)
  5. Linear document browsing across concepts, allowing you read the previous and next sections if you want to, either by mouse or keystroke (v. Nothing).

Is it still relevant? Nowadays most people would say "This documentation doesn't belong in a manpage" and would put it in a PDF or would put it up in HTML. In fact, the help systems on several OSes are based on HTML. However, when GNU Info was created (1986), HTML didn't exist yet. Nowadays texinfo allows you to create PDF, Info, or other formats, so you can use those formats if you want.

That's why GNU Info was invented.

  • 6
    man -K foo, with uppercase option, does a global full text search. Try man -K global-apropos - it finds the pages for man itself, in english, and in local language. – Volker Siegel Jul 25 '14 at 16:43
  • 1
    How do you find out what '&&' means?... you look in the index: "man perl", from there you see Overview, Tutorials, Reference Manual, Internals, Misc (books, community sources, license, change-logs(~40), language + platform specific docs. Of those, for '&&', I look in the Reference Section and see syntax, data and operators, as 1st 3 sections like most language ref-manuals. && looks like an op, so I look in the perlop manpage, and 2nd screen down lists all the operators. Compare that to figuring out keys for --vi-mode arg to 'info'... good luck. – Astara Jun 12 '18 at 3:06
41

The reason the Info system was invented is necessity, but I guess "laziness, hubris and impatience" is an equally good explanation.

The point of the GNU project was to develop a freely modifiable and freely distributible operating system and tools. The traditional Unix man system was based on the nroff/troff document formatting system from Bell Labs, which was at the time commercial (non-free) software. Eventually that system was reverse engineered and a free replacement called groff was created, but that was several years after the GNU project started. So using the man system for GNU documentation before then would have required implementing a troff replacement, a huge undertaking.

Meanwhile GNU Emacs was the first big project of GNU and it required extensive documentation. Facing a mountain of work implementing the GNU system, Richard Stallman cast about for existing software that he could use in his system. TeX already existed and had powerful document formatting capabilities. Unlike nroff/troff, TeX was free to use and redistribute. Texinfo was created as a documentation system to leverage the power of TeX for printed manuals and GNU Emacs for processing and online documentation reading. The original Texinfo processor and Info document browser were both written in Lisp and ran inside Emacs. The standalone Texinfo utilities came several years later.

20

As the Wikipedia page says, TeXinfo was designed as the official documentation of the GNU project by Richard Stallman. It is a set of macros on top of TeX, and was designed for writing software manuals. I think Stallman considered man pages inadequate for the task. Two advantages Texinfo has over man pages is that it is hyperlinked, and second, that it is, by design easy to convert into other formats.

ADDENDUM: While not strictly relevant to the question, note that man pages are still considered the standard documentation system on free Unix-like systems like those running atop the Linux kernel and also the various BSD flavors. For example, the Debian package templates encourage the addition of a man page for any commands, and also lintian checks for a man page. Texinfo is still not widely used outside the GNU project.

  • 2
    +1 especially for the note about hypertext, which I think was a major reason to want to move away from the (then more than now) hardcopy-oriented man format. – tripleee May 29 '13 at 16:49
  • @ChristopherSchultz edited – Faheem Mitha Feb 7 '15 at 5:16
  • I am used to books for reference materials. I can read them cover-to-cover. If manuals and books are inadequate for writing documentation, computers and languages would never have been taught or learnt. In learningk most follow a progression from low->high knowledge with more complex topics building on simpler ones. Books are almost what every child learns from -- sequentially presented information. H-links are for focusing on random topics of interest: if expert & master of topic - you know what you want and links can take you there fast. For reference & learning, links are a poor fit. – Astara Jun 12 '18 at 3:21
7

From a practical view, info is the most detailed of three levels of reference documentation:

The three levels are usually increasing in detail:

--help as a common command option - a short usage summary,
man - the classic man pages, a quick reference, and
info - a more detailed, GNU-speciffic manual - the full, official documentation.

If an info page is not available, the man page usually contains the full documentation.

Note that the man page contains exactly the same information like the --help output for many commands from GNU coreutils - for example ls;

Compare ls --help and man ls to see that the difference is only in formating.


The default info viewer is info.
There are more comfortable alternatives, like for the terminal pinfo, of for the GUI konqueror:

pinfo ls

konqueror info:ls

  • Well, you are thrifty, I'll give you that. – mikeserv Jul 29 '14 at 4:36
  • @mikeserv I did not find the sub-answer include feature. ;) – Volker Siegel Jul 29 '14 at 12:04
  • hmmm... very interesting, except that you forget to mention help as a command for builtin bash commands, and apropos and whatis as man with options for there practical use. – user171470 May 27 '16 at 9:08
  • A hyper-linked reference is not a manual or book. A wiki? maybe, but manuals never come with hyperlinks in the off-line world. They come with references (see chapter 38), but they aren't good to learn from. Having recently read through the newer C++ book, I can agree it uses forward and backward references if you want more info about a topic that will be covered later. Once you've read the book, those references can be a great aid in finding things. But for someone new to a complex program? I'll prefer a book over a linked HTML or info page every time. – Astara Jun 12 '18 at 3:26
2

1 - advanced, but lightweight technology

Man pages are flat.

info is a tree.

Both remain text based, so they can be used during low level system development, (unlike http, which requires a full blown GUI and browser before you can use it.)

This is also useful because linux can run on many low resource machines, for example, the stuff that runs on my Arduino from Atmel is found in info.

(History: info is similar to gopher, if you remember that. It was what we had just before we all moved into GUI OS's, and the the world wide web exploded. I remember that gopher worked pretty good for finding information, and it was fast and simple. It was easily expandable, fully text based, and fast.)


Man pages can't have operable hyperlinks. (It's just not possible in this technology.)

info can and does have many operable links from node to node, or from node to leaf, making it much easier to navigate big manuals quickly.


2 - contains content not found in man pages

Many standard packages also have a sister -doc package. Often this content is then found only inside info.

These documentation packages add booklets inside info, with sections, and sub-sections. In info lingo, these are called nodes, and nodes can contain other nodes in a tree structure.

There are commands to climb around the tree, here are some examples:

  • up a section, e.g. from section 2.1 to section 2
  • next section (i.e. move along branch tips from page to page), e.g. from Section 2, to Section 2.1, and (assuming there is no Section 2.2), onwards to Section 3
  • right a section, e.g. from Section 2 directly to Section 3, skipping section 2.1

If you're reading and you scroll down line by line, then you'll visit all sections of each booklet.

Important commands

l - go back - Lower case 'L', as in last. It's like the back button on your web browser. - Go back to the last node seen in this window (initially we only have one window). Wow, we can split the document window in half too!


d - my people - Go to the main 'directory' node. - This is the top of the INFO tree. Contains links to the families:

t - my family - Go to the top node of this document. - Generally the table of contents

u - my parent - Go up one level. e.g. go from Section 2.1, to Section 2.

n - my siblings - Go to the next node on this level. e.g. section 2 -> section 3 (not 2.1)

p - my siblings - Go to the previous node on this level. e.g. section 3 -> section 2

] - my children - Go to the next node in the document, e.g. section 2 -> section 2.1

[ - my children - Go to the previous node in the document, e.g. section 2.1 -> section 2


I also didn't really understand why I would want to use info. I had previously dabbled in it, and at first found it old-school. But because I needed some more information for an autoconf project, and it was suggested to me that this is where that documentation was, I took another look recently.

The first thing I had to do was to figure out how to navigate better. I found the help given by H almost unhelpful. That was until I noticed that I could scroll down into this help, ..but then there was too much confusion.

So I copied this help and pasted it together into a Gnote, and began to try to understand how info worked.

As I learned more, I rewrote their help for myself. I wanted to know what they full range of commands were, and how they were categorized.

I noticed that many of the key-strokes were duplicated, with 2 or 3 ways to execute a given command. I also noticed that this all looked very much like emacs.

Here is my cheat sheet of info commands:

HELP - info - commands

#####################################################################################################################################################
Short list - 'basic' Info command keys (see below for full list)

        C-g         Cancel the current operation.
        H           Close this help window. (toggle help window)
        q           Quit Info altogether.

        h           Invoke the Info tutorial.


        Move in this node
                Up          Move up one line.
                Down        Move down one line.


                PgUp        Scroll backward one screenful.      - also backspace
                PgDn        Scroll forward  one screenful.      - also     space

                Home        Go to the beginning of this node.
                End         Go to the end       of this node.

                TAB         Skip to the next    hypertext link.

                /           Search forward for a specified string.
                }           Search for next     occurrence.
                {           Search for previous occurrence.

        Move to other nodes
                RET         Follow the          hypertext link under the cursor.

                1...9       Pick the first...ninth item in this node's menu.
                0           Pick the last item in this node's menu.

                l           Last in history.  Go back to the last node seen in this window (initially we only have one window). (?? history)


                d           Go to the main 'directory' node.                    my people
        the Info main menu - "This is the top of the INFO tree."

                t           Go to the top node of this document.                my family       Generally the table of contents

                u           Go up one level.                                    my parent       e.g. go from Section 2.1, to Section 2.

                n           Go to the next     node on this level.              my siblings     e.g. section 2 -> section 3  (not 2.1)
                p           Go to the previous node on this level.

                ]           Go to the next     node in the document.            my children     e.g. section 2 -> section 2.1
                [           Go to the previous node in the document.  (?siblings)


                m <name>    Pick a menu item specified by name.
                f           Follow a cross reference specified by name.
                g           Go to a node specified by name.

                i           Search for a specified string in the index (if there is an index), and select the node referenced by the first entry found.

                I           Synthesize menu of matching index entries. ???




#####################################################################################################################################################
Full list - of commands available in Info windows:

Notes: 
        M-              (meta) is Alt;  (also you can use an Esc prefix instead of meta -hwj)
        M-C-            means hold both Ctrl and Alt down at same time
        *               Basic commands (listed above)



     HELP
*               H                                       (get-help-window)               Toggle display of help message
*               h                                       (get-info-help-node)            Visit Info node '(info)Help' (this gets:  man info )


     CANCEL
*                       C-g     C-x C-g M-C-g           (abort-key)                     Cancel current operation  (?? esc)

*               q       C-c                             (quit)                          Quit using Info
                        C-x C-c                         (quit)                          Quit using Info


     WINDOWS
                        C-l                             (redraw-display)                Redraw the display

                x       C-x 0                           (delete-window)                 Delete the current window
                        C-x 1                           (keep-one-window)               Delete all other   windows (leaving 1)

                        C-x 2                           (split-window)                  Split the current  window  (into 2)
                        C-x t                           (tile-windows)                  Divide the available screen space among the visible windows

                        C-x ^                           (grow-window)                   Grow (or shrink) this window

                        C-x o                           (next-window)                   Select the next window (other)

                        C-x C-b                         (list-visited-nodes)            Make a window containing a menu of all of the currently visited nodes

                        C-x w                           (toggle-wrap)                   Toggle the state of line wrapping in the current window

     VIEW OTHER FILE
                        C-x C-f                         (view-file)                     Read the name of a file and select it
                        C-x C-v                         (view-file)                     Read the name of a file and select it


     SCROLL
                        C-v                             (scroll-forward-page-only)      Scroll forward  in this window staying within node      ('v' looks like a down arrow)
                                M-v                     (scroll-backward-page-only)     Scroll backward in this window staying within node      (meta-v is the reverse, or up arrow)

*       PgDn    SPC                                     (scroll-forward)                Scroll forward  in this window (at end moving to next node??)
*       PgUp    DEL     C-h                             (scroll-backward)               Scroll backward in this window (at end moving to next node??)  (DEL = Backspace or Del)

                                M-C-v   ESC PgDn        (scroll-other-window)           Scroll the other window
                                        ESC PgUp        (scroll-other-window-backward)  Scroll the other window backward


     CURSOR MOVEMENT (within a 'node' / page)
        Right           C-f                             ( forward-char)                 Move forward  a character
        Left            C-b                             (backward-char)                 Move backward a character

                                M-b                     (backward-word)                 Move backward a word
                                M-f                     ( forward-word)                 Move forward  a word

                        C-a                             (beginning-of-line)             Move to the start of the line
                        C-e                             (end-of-line)                   Move to the end   of the line


*       Up              C-p                             (prev-line)                     Move up   to the previous line
*       Down            C-n                             (next-line)                     Move down to the next     line

                                M-r                     (move-to-window-line)           Move the cursor to a specific line of the window

*       Home    b               ESC <                   (beginning-of-node)             Move to the start of this node
*       End     e               ESC >                   (end-of-node)                   Move to the end   of this node


     SEARCHING
                /                                       (search)                        Read a string and search          for it
                s                                       (search)                        Read a string and search          for it
                ?                                       (search-backward)               Read a string and search backward for it

                R                                       (toggle-regexp)                 Toggle the usage of regular expressions in searches

                S                                       (search-case-sensitively)       Read a string and search for it case-sensitively

*               }       C-x n                           (search-next)                   Repeat last search in the same    direction
*               {       C-x N                           (search-previous)               Repeat last search in the reverse direction


                        C-s                             (isearch-forward)               Search interactively for a string as you type it
                        C-r                             (isearch-backward)              Search interactively for a string as you type it


                                M-/                     (tree-search)                   Search this node and subnodes for a string.

                                M-}                     (tree-search-next)              Go to next     match in Info sub-tree
                                M-{                     (tree-search-previous)          Go to previous match in Info sub-tree


     JUMP TO NODE CROSS REFERENCES (underlined links to nodes)
*               TAB                                     (move-to-next-xref)             Move to the next     cross reference
                BackTab         M-TAB                   (move-to-prev-xref)             Move to the previous cross reference  (Shift-tab)


     SELECT A NODE (hyperlink)
*               RET                                     (select-reference-this-line)    Select reference or menu item appearing on this line

*               1 .. 9                                  (menu-digit)                    Select this     menu item (link) # in this node's menu (this page's menu)
*               0                                       (last-menu-item)                Select the last menu item (link)   in this node's menu (this page's menu)

                <                                       (first-node)                    Select the first node in this file
                >                                       (last-node)                     Select the last  node in this file


*               d                                       (dir-node)                      Select the 'dir' node (in all files?)   the Info main menu - "This is the top of the INFO tree."

*               t                                       (top-node)                      Select the 'Top' node in this file      Generally the table of contents
*               u                                       ( up-node)                      Select the 'Up'  node in this file      i.e. go from Section 2.1, to Section 2.


*               n                                       (next-node)                     Select the Next node                    i.e. section 2.1 -> section 2.2
*               p                                       (prev-node)                     Select the Prev node


*               g <name>                                (goto-node)                     Read a node name and select it
*               m <item>                                (menu-item)                     Read a menu item and select its node    ???


                        C-x b                           (select-visited-node)           Select a node which has been previously visited in a visible window (c-x=Window, back)



     MOVE TO ANOTHER NODE (in the tree)
*               [                                       (global-prev-node)              Move backwards or up   through node structure (tree within this file)
*               ]                                       (global-next-node)              Move forwards  or down through node structure (tree within this file)

*               l                                       (history-node)                  last - Select the most recently selected node

     GET NODE INFORMATION
                =                                       (display-file-info)             Show full file name of node being displayed
                O                                       (goto-invocation-node)          Find the node describing program invocation


     READ IN NEW MENUS
                G <menus>                               (menu-sequence)                 Read a list of menus starting from dir and follow them  ???


     INDEX
*               i                                       (index-search)                  Look up a string in the index for this file (Search for a specified string in the index 
                                                                                                (if there is an index), and select the node referenced by the first entry found.

                ,                                       (next-index-match)              Go to the next matching index item from the last 'i' command

*               I                                       (virtual-index)                 List all matches of a string in the index

                        C-x f                           (all-files)                     Show all matching files


     FOOTNOTES
*               f                                       (xref-item)                     Read a footnote or cross reference and select its node
                r                                       (xref-item)                     Read a footnote or cross reference and select its node

                                M-C-f                   (show-footnotes)                Show the footnotes associated with this node in another window

     NUMERIC 
                        C-u                             (universal-argument)            Start (or multiply by 4) the current numeric argument
                                M--                     (add-digit-to-numeric-arg)      Add this digit to the current numeric argument
                                M-0 .. M-9              (add-digit-to-numeric-arg)      Add this digit to the current numeric argument


     MISC
                                M-x                     (execute-command)               Read a command name in the echo area and execute it     ?? pwd and ls don't work


#####################################################################################################################################################
The following text commands can only be invoked via M-x (Alt-x -hwj):

        This is a list of longer commands that can be typed, all prefixed with Alt-x:


        M-x scroll-forward-set-window                   Scroll forward  in this window                          and set default window size
        M-x scroll-backward-set-window                  Scroll backward in this window                          and set default window size

        M-x scroll-forward-page-only-set-window         Scroll forward  in this window  staying within node     and set default window size
        M-x scroll-backward-page-only-set-window        Scroll backward in this window  staying within node     and set default window size

        M-x down-line                                   Scroll down by lines
        M-x   up-line                                   Scroll up   by lines

        M-x scroll-half-screen-down                     Scroll down by half screen size
        M-x scroll-half-screen-up                       Scroll up   by half screen size


        M-x prev-window                                 Select the previous             xwindow

        M-x set-screen-height <number>                  Set the height of the displayed window

        M-x  find-menu                                  Move to the start of this node's menu

        M-x visit-menu                                  Visit as many menu items at once as possible

        M-x man <name of man page>                      Read a manpage reference and select it


        M-x print-node                                  Pipe the contents of this node through INFO_PRINT_COMMAND


        M-x clear-search                                Clear displayed search matches


        M-x describe-key <key combo>                    Print documentation for KEY  (one line of documentation)
        M-x where-is                                    Show what to type to execute a given command
        M-x describe-command                            Read the name of an Info command and describe it


        M-x index-apropos                               Grovel all known info file's indices for a string and build a menu (grep widely, and make a menu of what is found)


        M-x describe-variable                           Explain the use of a     variable
        M-x      set-variable                           Set the value of an Info variable


        M-x info-version                                Display version of Info being run




#####################################################################################################################################################
Commands available in the 'echo' area (i.e. at bottom of screen):

        (M- (meta) = Fn  (not alt) -hwj)


        C-l             (redraw-display)                        Redraw the display

        C-g     Esc     (echo-area-abort)                       Cancel or quit operation
        M-C-g           (echo-area-abort)                       Cancel or quit operation


     MOVE
        C-a     Home    (echo-area-beg-of-line)                 Move to the start of this line
        C-e     End     (echo-area-end-of-line)                 Move to the end   of this line

        C-b     Left    (echo-area-backward)                    Move backward a character
        C-f     Right   (echo-area-forward)                     Move forward  a character

        M-b             (echo-area-backward-word)               Move backward a word
        M-f             (echo-area-forward-word)                Move forward  a word

     COMMAND LINE COMPLETIONS
        M-?     ?       (echo-area-possible-completions)        List possible completions
        M-C-v           (echo-area-scroll-completions-window)   Scroll the completions window
        TAB     SPC     (echo-area-complete)                    Insert completion 
        RET     LFD     (echo-area-newline)                     Accept (or force completion of) this line


     DELETE/YANK
        C-d             (echo-area-delete)                      Delete the character under  the cursor
        C-h     DEL     (echo-area-rubout)                      Delete the character behind the cursor

        M-d             (echo-area-kill-word)                   Kill the word following the cursor
        M-DEL           (echo-area-backward-kill-word)          Kill the word preceding the cursor

        C-k             (echo-area-kill-line)                   Kill to the end       of the line
        C-x DEL         (echo-area-backward-kill-line)          Kill to the beginning of the line

        C-y             (echo-area-yank)                        Yank back the contents of the last kill
        M-y             (echo-area-yank-pop)                    Yank back a previous kill


     INSERT
        C-q             (echo-area-quoted-insert)               Insert next  character verbatim
        M-TAB           (echo-area-tab-insert)                  Insert a TAB character


     TRANSPOSE
        C-t             (echo-area-transpose-chars)             Transpose characters at point (and move ahead by one)

     NUMERIC ARGUMENTS ???
        C-u             (universal-argument)                    Start (or multiply by 4) the current numeric argument
        M--             (add-digit-to-numeric-arg)              Add this digit to the current numeric argument
        M-0 .. M-9      (add-digit-to-numeric-arg)              Add this digit to the current numeric argument

        C-x o           (next-window)                           Select the next window

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.