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?
asked May 29, 2013 at 14:40
6 Answers
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:
- The ability to have a single document for a large system, which contains all the information about that system. (versus 174 man pages)
- Ability to do full-text search across the entire document (v. man -k which only checks keywords)
- 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)
- 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)
- 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.
-
10
man -K foo, with uppercase option, does a global full text search. Tryman -K global-apropos- it finds the pages formanitself, in english, and in local language. Commented Jul 25, 2014 at 16:43 -
4How 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.– AstaraCommented Jun 12, 2018 at 3:06
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.
answered May 29, 2013 at 16:21
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.
answered May 29, 2013 at 15:02
-
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
manformat.– tripleeeCommented May 29, 2013 at 16:49 -
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.– AstaraCommented Jun 12, 2018 at 3:21
(See commands cheat sheet below)
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.
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.
(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.)
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.
Your first goal is to navigate.
But the help given by H is unhelpful. Looks more like the output of some robot.
I copied their help into a Gnote, and hand reorganized it (below). I also noticed that many of the key-strokes were duplicated, with 2 or 3 ways to execute a given command. It looks very much like emacs.
There are commands to climb around the tree, here are some examples:
- up a section, e.g. from section 2.1 to section 2
- right a section, e.g. from Section 2.1 directly to Section 2.2, skipping section 2.1.1
- next section (i.e. move along branch tips from page to page), e.g. from Section 2.1, to Section 2.1.1, and then (assuming there is no Section 2.1.2), onward to Section 2.2
If you're reading and you scroll down line by line, then you'll visit all sections of each booklet.
Important navigation commands - Go to
Last
* l - last i.e. go back. 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!
Parent
* u - up one level. e.g. go from Section 2.1, to Section 2.
Siblings
* n - next node on this level. e.g. section 2 -> section 3 (not 2.1)
* p - previous node on this level. e.g. section 3 -> section 2
Children
* ] - next node in the document, e.g. section 2 -> section 2.1
* [ - previous node in the document, e.g. section 2.1 -> section 2
People
* d - directory (main) node. - This is the top of the INFO tree. Contains links to the families:
Family
* t - top node of this document. - Generally the table of contents
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)
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):
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))
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
answered Nov 30, 2018 at 21:25
From a practical view, info is the most detailed of three levels of reference documentation:
The three levels are usually increasing in detail:
--helpas a common command option – a short usage summary,man– the classic man pages; a quick reference, andinfo– a more detailed, GNU-specific 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 may contain exactly the same information
as the --help output for many commands from GNU coreutils –
for example, ls.
If you compare ls --help and man ls,
you may see that the contents are very similar.
The official info viewers
are info and info in emacs (M-x info).
There are third-party alternatives,
like pinfo for the terminal or konqueror for the GUI:
-
pinfo ls -
konqueror info:ls
G-Man Says 'Reinstate Monica'
23.5k27 gold badges75 silver badges125 bronze badges
answered Jul 29, 2014 at 3:46
-
-
@mikeserv I did not find the sub-answer include feature. ;) Commented Jul 29, 2014 at 12:04
-
2hmmm... very interesting, except that you forget to mention
helpas a command for builtin bash commands, andaproposandwhatisas man with options for there practical use.– user171470Commented May 27, 2016 at 9:08 -
1A 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.– AstaraCommented Jun 12, 2018 at 3:26
-
I love info pages. They are much more tutorial-like than man pages and therefore much easier on beginners. Try
info sedandinfo grepand compare withman sedandman grep. Man pages are much more technical and lack examples most of the times. There are exceptions to what I just described, but it holds true for most of the commands, I would say. Commented Sep 22, 2019 at 21:10
Textinfo, Nroff, Groff, Troff are "PITA"s (pain in the ass) technologies (syntaxes) for just doing what you can do with wayyyy less effort with MARKDOWN. Stick to whatever makes you more productive for the task at hand. (i.e documentation page -> "Markdown" and you are done).
info --vi-keysto make info's keybindings feel more familiar. You can also uselesswith info to make it feel just likeman:info --subnodes -o - $1 | less. You do lose some text formatting this way though.