Gentoo Info Guide
What is info?
Most of you may be familiar with the man documentation system. While man
is good with quickly looking up items, it lacks structure in linking man pages
together. This is where info comes in. Info pages are made using the
texinfo tools, and can link with other pages, create menus and ease
navigation in general. The next section will look at how info pages are laid
Info pages layout
The main info pages are held in /usr/share/info. Unlike the man
style directory layout, /usr/share/info contains what is largely a
rather extensive collection of files. These files have the following format:
Code Listing 1.1: info file format
pagename is the actual name of the page (example: wget).
[-node] is an optional construct that designates another node level
(generally these are referenced to by the toplevel of the info document in
question). In order to save space these info pages are compressed using the
gzip compression scheme. Additional info pages can be listed with the
INFOPATH environment variable (usually set through the various
/etc/env.d/ files). To get started, it's important to note the
/usr/share/info/dir file. This special file is used when info is
ran with no parameters. It contains a listing of all info pages available for
users to browse. To begin looking at navigating around in info, we'll go ahead
and bring it up with no arguments:
Code Listing 1.2: Starting up info
Now in the next chapter we'll look at dealing with basic info navigation.
Working with info pages
Browsing with menus
Now that info is started, we're given a screen similar to this:
Code Listing 2.1: Sample info screen
File: dir, Node: Top This is the top of the INFO tree
This (the Directory node) gives a menu of major topics.
Typing "q" exits, "?" lists all Info commands, "d" returns here,
"h" gives a primer for first-timers,
"mEmacs<Return>" visits the Emacs manual, etc.
In Emacs, you can click mouse button 2 on a menu item or cross reference
to select it.
User Interface Toolkit
* GDK: (gdk). The General Drawing Kit
* GTK: (gtk). The GIMP Toolkit
GNU programming tools
* Autoconf v2.1: (autoconf). Create source code configuration scripts.
Right now there are a bunch of entries with an asterisk before them. These are
menu items for navigating through different node levels. There are two ways of
selecting menus. We'll look at the first now and the other way later. First
off, we'll go ahead and look at the wget info page. To do so, use the
down arrow key until you reach the area indicated by the blue highlighting:
Code Listing 2.2: Navigating to the wget info menu entry
* GnuTLS: (gnutls). Package for Transport Layer Security.
* Wget: (wget). The non-interactive network downloader.
* certtool: (gnutls)Invoking certtool. Manipulate certificates and keys.
* gnutls-cli: (gnutls)Invoking gnutls-cli. GNU TLS test client.
* gnutls-cli-debug: (gnutls)Invoking gnutls-cli-debug. GNU TLS debug client.
* gnutls-serv: (gnutls)Invoking gnutls-serv. GNU TLS test server.
* srptool: (gnutls)Invoking srptool. Simple SRP password tool.
Once you get to this area, hit the ENTER key to select the menu item.
This will bring up the info page for wget:
Code Listing 2.3: The wget info page
File: wget.info, Node: Top, Next: Overview, Up: (dir)
This manual documents version 1.10.2 of GNU Wget, the freely available
utility for network downloads.
Copyright (C) 1996-2005 Free Software Foundation, Inc.
* Overview:: Features of Wget.
* Invoking:: Wget command-line arguments.
* Recursive Download:: Downloading interlinked pages.
* Following Links:: The available methods of chasing links.
* Time-Stamping:: Mirroring according to time-stamps.
* Startup File:: Wget's initialization file.
Now that we have an info page up, the next section will look at basic
In terms of nodes, this is considered the Top node for the wget page.
Consider the Top node to be the same as the table of contents for that
particular info page. Now to navigate the actual page itself, you have a couple
of different methods. First off is the standard info method. This is using the
SPACE key to move forward a page and the BACKSPACE/DELETE keys to
move back a page. This is the recommended method as it automatically
advances/retreats to the appropriate node in the document. This allows for a
somewhat linear browsing for those used to man pages. Another way is through
the PAGE UP/PAGE DOWN keys. These work, but they will not
advance/retreat like SPACE/BACKSPACE/DELETE will. If you want to skip
entire nodes without using SPACE/BACKSPACE/DELETE, you can also use the
[ (advance backwards) and ] (advance forwards) keys.
As mentioned earlier, there are 2 ways of navigating menus. The other way will
now be described here. The numbers 1-9 can be used to reference to the
first-ninth menu entries in a document. This can be used to quickly peruse
through documents. For example, we'll use 3 to reach the Recursive
Download menu entry. So press 3 and it will bring up the
Recursive Download screen:
Code Listing 2.4: Resulting Recursive Download screen
File: wget.info, Node: Recursive Download, Next: Following Links, Prev: Invoking, Up: Top
3 Recursive Download
GNU Wget is capable of traversing parts of the Web (or a single HTTP or
FTP server), following links and directory structure. We refer to this
as to "recursive retrieval", or "recursion".
Now we're at the Recursive Download screen. Here is a good time to note
a few things. First off the top header section. This header shows the
navigation capable from this particular screen. The page indicated by
Next: can be accessed by pressing the n key, and the page
indicated by Prev: can be accessed by pressing the p key. Please
note that this will only work for the same level. If overused you could round
up in totally unrelated content. It's better to use
SPACE/BACKSPACE/DELETE/[/] to navigate in a linear fashion.
If for some reason you get lost, there are a few ways to get out. First is the
t key. This will take you straight to the toplevel (table of contents)
for the particular info page you're browsing. If you want to return to the last
page you looked out, you can do so with the l key. If you want to go to
the above level, you can do so with the u key. Now that you have some
idea of navigating a page, the next chapter will look at searching for content.
Searching through info
Navigating to other info pages
Now that you can navigate an individual info page, it's important to look at
accessing other info pages. The first obvious way is to go to the info page
through the dir index listing of info pages. To get to the dir
index from deep within a document, simply press the d key. From there
you can search for the appropriate page you want. However, if you know the
actual page, there is an easier way through the Goto node (g key)
command. To go to an info page by name, type g to bring up the prompt
and enter the name of the page in parentheses:
Code Listing 3.1: Going to an info page by name
* Startup File:: Wget's initialization file.
* Examples:: Examples of usage.
* Various:: The stuff that doesn't fit anywhere else.
* Appendices:: Some useful references.
* Copying:: You may give out copies of Wget and of this manual.
--zz-Info: (wget.info.gz)Top, 24 lines --Top-------------------------------
Goto node: (libc)
This will bring up the libc page as shown here:
Code Listing 3.2: Result of the Goto node command
File: libc.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
This is Edition 0.10, last updated 2001-07-06, of `The GNU C Library
Reference Manual', for Version 2.3.x of the GNU C Library.
* Introduction:: Purpose of the GNU C Library.
Now that we know how to go to info pages by name, the next section will look at
searching for pieces of information using the info page's index.
Searching using an index
In this example we'll see how to lookup the printf function of the c
library using the libc info page's index. You should still be at the
libc info page from the last section, and if not, use the Goto node command to
do so. To utilize the index search, hit the i key to bring up the
prompt, then enter your search term. We'll do so for printf below:
Code Listing 3.3: Entering an index search query
* Character Set Handling:: Support for extended character sets.
* Locales:: The country and language can affect the
behavior of library functions.
* Message Translation:: How to make the program speak the user's
--zz-Info: (libc.info.gz)Top, 1291 lines --Top-- Subfile: libc.info-1.gz-----
Index entry: printf
After pressing enter upon completion of our query, we're brought to the
libc definition for printf:
Code Listing 3.4: Result of the index search query
File: libc.info, Node: Formatted Output Functions, Next: Dynamic Output, Prev: Other Output Conversions, Up: Formatted Output
12.12.7 Formatted Output Functions
This section describes how to call `printf' and related functions.
Prototypes for these functions are in the header file `stdio.h'.
Because these functions take a variable number of arguments, you _must_
declare prototypes for them before using them. Of course, the easiest
way to make sure you have all the right prototypes is to just include
We've now successfully performed a search using the libc info page
index. However, sometimes what we want is in the page itself. The next section
will look at performing searches within the page.
Searching using the search command
Starting from the previous location at the Formatted Output Functions
node, we'll look at searching for the sprintf variation of the
printf function. To perform a search, press the s key to
bring up the search prompt, and then enter the query (sprintf in this case):
Code Listing 3.5: Entering a search query
-- Function: int wprintf (const wchar_t *TEMPLATE, ...)
The `wprintf' function prints the optional arguments under the
control of the wide template string TEMPLATE to the stream
`stdout'. It returns the number of wide characters printed, or a
--zz-Info: (libc.info.gz)Formatted Output Functions, 127 lines --Top-- Subfile: libc.info-3.gz--
Search for string : sprintf
Hit ENTER and it will show the result of the query:
Code Listing 3.6: Result of the search query
-- Function: int sprintf (char *S, const char *TEMPLATE, ...)
This is like `printf', except that the output is stored in the
character array S instead of written to a stream. A null
character is written to mark the end of the string.
The `sprintf' function returns the number of characters stored in
the array S, not including the terminating null character.
And we have the function we need.
This concludes the overview of using info to view info pages. As always
comments are both welcome and appreciated. Clicking on the my name (Chris
White) on the right side will send me an email.
Additional Program Resources
In order to make things easier for those that wish to browse info pages through
a more friendly graphical interface, the following are available:
- app-text/info2html - Convert info pages to a browse-able HTML format
- app-text/pinfo - ncurses based info viewer
- app-text/tkinfo - a tcl/tk based info browser
- app-vim/info - a vim based info browser
The KDE browser Konqueror also allows you to browse info pages
through the info: URI.
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.