Inspect and Publish GNU Info Manuals Safely

You will be able to find an installed GNU Info manual, inspect its actual file, export a node or a whole manual to plain text, and test a directory registration before changing shared documentation. This guide uses GNU Texinfo 7.1, installed from the Debian package info version 7.1-3build2.

Allow about 10 minutes. You need a shell and a readable Info file. The inspection steps need no elevated privileges. Updating a system-wide directory file under /usr/share/info normally needs administrator access and changes how other users find manuals.

Checkpoint 1: confirm the tools and package version

1. Check the installed reader and the files it can locate.

info --version
info --where find

On the tested system, the first command reports info (GNU texinfo) 7.1 and the second prints:

/usr/share/info/find.info.gz

The info(5) format is the readable online-documentation format used by info(1) and Emacs. It is commonly produced from Texinfo source with makeinfo, although the format can also be created from scratch. The format manual deliberately points to the Texinfo manual for the complete language, so treat a hand-written file as a format project rather than guessing at syntax from one example.

Checkpoint 2: inspect the stored Info file

1. Read the compressed file without altering it.

zcat /usr/share/info/find.info.gz | sed -n '1,35p'

You should see metadata such as File: find.info, a top node, a menu, and a generated-by line. A larger manual may be split into numbered files such as find.info-1 and find.info-2; the top file can contain an indirect table pointing to those pieces. Do not edit a generated file to repair links or menus. Fix its Texinfo source and regenerate it with the project build, then install the resulting file.

Compression is an implementation detail of the installed copy. The reader can open find.info.gz directly, while zcat is useful when you need to inspect the bytes as text. If your manual is uncompressed, replace the inspection command with sed -n '1,35p' /path/to/manual.info.

Checkpoint 3: open a manual by name or path

1. Open the installed manual at its top node.

info find

This starts an interactive reader and searches the Info directory for a matching menu entry. In a non-interactive setting, name the file explicitly and select its top node:

info -f /usr/share/info/find.info.gz -n Top

The -f option avoids ambiguity when several manuals have similar names. The -n option selects a node by name. The first argument without an option is normally a menu item, so info find and info -f ... are useful for different failure modes: the first tests directory discovery, and the second tests the file itself.

If discovery fails but the explicit path works, the manual is readable but is not registered in the directory being searched. Check the search path before changing files:

printf '%s\n' "${INFOPATH:-not set}"
info --where find

Do not assume that an empty INFOPATH means no manuals exist. GNU Info has its own default search locations; --where shows which file it selected.

Checkpoint 4: export reproducible text

1. Write the top node and its children to a temporary file.

info -f /usr/share/info/find.info.gz -n Top --subnodes -o /tmp/find-info.txt
sed -n '1,35p' /tmp/find-info.txt

The -o option writes selected output to a file, and --subnodes follows the manual's child nodes recursively. This is useful for review, search indexing, or attaching a stable text snapshot to a bug report. The command does not modify the installed manual.

For one node only, omit --subnodes. To inspect where a menu entry goes, start at a known node with -n rather than relying on the interactive reader's current position. Keep the output in /tmp or another deliberate location, and remove it when it contains material that should not remain on a shared machine.

Checkpoint 5: test directory registration before changing it

1. Preview how install-info would add an Info file to a directory file.

install-info --test \
  --info-file=/usr/share/info/find.info.gz \
  --dir-file=/tmp/info-dir

install-info adds or removes entries in an Info directory file. Its --test option suppresses the update, which makes it the right first check for a new path, section, or menu entry. The command's help text says that the Info file and directory file are required unless equivalent options are supplied.

A real installation might use a command like this, but stop and review the paths first:

sudo install-info \
  --info-file=/path/to/manual.info.gz \
  --dir-file=/usr/share/info/dir

This is the first elevated command in the guide. It changes a shared index, not the manual's content. Do not run it with a placeholder path. If the entry is wrong, use install-info --delete with the same target and review the directory file afterwards, or regenerate the directory from your distribution's packaging process. Keep a backup of a locally maintained directory file before making manual changes.

Common traps

• Confusing the sections. info(5) documents a file format. info(1) is the reader, and install-info(1) manages directory entries.
• Testing only the reader. A direct -f invocation can work while the normal menu lookup fails. Test both the path and the name when you are installing a manual.
• Editing generated output. Changes to an .info file are normally lost at the next build. Correct the Texinfo source instead.
• Using administrator access too early. Locate and export the manual as your normal user. Reserve sudo for a reviewed change to a shared directory.
• Assuming every manual is one file. Large Info manuals can be split into numbered parts. Preserve the complete set and its indirect table when copying or packaging them.