Inspect and Publish GNU Info Manuals Safely

The info(5) format is what GNU info actually reads, and this guide shows you the real file behind a manual before you touch anything shared. It covers finding, inspecting and exporting an Info manual, and testing a directory registration, using GNU Texinfo 7.1 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 does, and it changes how other users find manuals.

1. Confirm the tools and package version

Check the installed reader and the files it can find:

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, though it can be written by hand too. The format manual itself points to the Texinfo manual for the complete language, so treat a hand-written file as a proper format project rather than guessing syntax from one example.

2. Inspect the stored Info file

Read the compressed file without touching 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 can split into numbered files such as find.info-1 and find.info-2, with the top file holding an indirect table pointing at those pieces.

Compression is just an implementation detail of this installed copy. The reader can open find.info.gz directly, while zcat is handy when you need to see the bytes as text. For an uncompressed manual, swap in sed -n '1,35p' /path/to/manual.info instead.

3. Open a manual by name or path

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. For a non-interactive setting, name the file explicitly and select its top node:

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

• -f avoids ambiguity when several manuals share a similar name.
• -n selects a node by name. A first argument without an option is normally a menu item, so info find tests directory discovery while info -f ... tests the file itself: useful for telling apart two different failure modes.

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

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

Do not assume an empty INFOPATH means no manuals exist. GNU Info has its own default search locations, and --where shows which file it actually picked.

4. Export reproducible text

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

-o writes selected output to a file, and --subnodes follows the manual's child nodes recursively. Handy for review, search indexing, or pinning a stable text snapshot to a bug report. None of this touches the installed manual.

For one node only, drop --subnodes. To check where a menu entry goes, start at a known node with -n rather than trusting the interactive reader's current position. Keep exported output in /tmp or another deliberate spot, and remove it once it holds anything that should not sit on a shared machine.

5. Test directory registration before changing it

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, and its --test flag suppresses the actual update, which makes it the right first check for a new path, section or menu entry. Its help text says the Info file and directory file are required unless equivalent options are supplied.

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

That is the first elevated command in this guide. It changes a shared index, not the manual's content, and it should never run against a placeholder path. If an entry ends up wrong, use install-info --delete with the same target and check the directory file afterwards, or regenerate the directory from your distribution's packaging process. Keep a backup of a locally maintained directory file before hand-editing it.

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 installing a manual.
• Editing generated output. Changes to an .info file are normally lost at the next build. Fix the Texinfo source instead.
• Reaching for admin access too early. Locate and export the manual as your normal user, and save sudo for a reviewed change to a shared directory.
• Assuming every manual is one file. Large Info manuals split into numbered parts. Keep the complete set and its indirect table together when copying or packaging them.