Info Documentation – How to Create It

documentationinfo

How can I add man page entries for my own power tools? got me thinking: How would one create an Info page?

Best Answer

To create Info documentation, you first need a texi file.

.texi - Texinfo is a typesetting syntax used for generating documentation in both on-line and printed form (creating filetypes as dvi, html, pdf, etc., and its own hypertext format, info) with a single source file. It is implemented by a computer program released as free software of the same name, created and made available by the GNU Project from the Free Software Foundation.

.info - Info (Generated via makeinfo.) This is a specific format which essentially is a plain text version of the original Texinfo syntax in conjunction with a few control characters to separate nodes and provide navigational elements for menus, cross-references, sections, and so on. The Info format can be viewed with the info program.

makeinfo is a utility that converts a Texinfo file into an Info file; it is part of the texinfo package. texinfo-format-region and texinfo-format-buffer are GNU Emacs functions that do the same.

Here is a texi sample to use as a template:

\input texinfo   @c -*-texinfo-*-
@comment $Id@w{$}
@comment %**start of header
@setfilename sample.info
@include version.texi
@settitle GNU Sample @value{VERSION}
@syncodeindex pg cp
@comment %**end of header
@copying
This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}),
which is an example in the Texinfo documentation.

Copyright @copyright{} 2013 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying

@dircategory Texinfo documentation system
@direntry
* sample: (sample)Invoking sample.
@end direntry

@titlepage
@title GNU Sample
@subtitle for version @value{VERSION}, @value{UPDATED}
@author A.U. Thor (@email{bug-sample@@gnu.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top GNU Sample

This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).
@end ifnottex

@menu
* Invoking sample::
* GNU Free Documentation License::
* Index::
@end menu


@node Invoking sample
@chapter Invoking sample

@pindex sample
@cindex invoking @command{sample}

This is a sample manual.  There is no sample program to
invoke, but if there were, you could see its basic usage
and command line options here.


@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi


@node Index
@unnumbered Index

@printindex cp

@bye

Convert that into Info documentation with:

makeinfo mytool.texi

Listing a New Info File

To add a new Info file to your system, write a menu entry for it in the menu in the dir file in the info directory (/usr/share/info/ on Ubuntu). Also, move the new Info file itself to the info directory. For example, if you were adding documentation for GDB, you would write the following new entry:

* GDB: (gdb).           The source-level C debugger.

The first part of the menu entry is the menu entry name, followed by a colon. The second part is the name of the Info file, in parentheses, followed by a period. The third part is the description.

Conventionally, the name of an Info file has a .info extension. Thus, you might list the name of the file like this:

* GDB: (gdb.info).           The source-level C debugger.

However, Info will look for a file with a .info extension if it does not find the file under the name given in the menu. This means that you can refer to the file gdb.info as gdb, as shown in the first example. This looks better.

Related Question