manpagez: man pages & more
info texinfo
Home | html | info | man
[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

F.1 Info Format General Layout

This section describes the overall layout of Info manuals.

Info Format: A Whole Manual

To begin, an Info manual is either nonsplit (contained wholly within a single file) or split (across several files).

The syntax for a nonsplit manual is:

    <nonsplit info file> =
<preamble>
<node>*
<tag table>
(<local variables>)?

When split, there is a main file, which contains only pointers to the nodes given in other subfiles. The main file looks like this:

    <split info main file> =
<preamble>
<indirect table>
<tag table>
(<local variables>)?

The subfiles in a split manual have the following syntax:

    <split info subfile> =
<preamble>
<node>*

Info Format: Preamble

The <preamble> is text at the beginning of all output files. It is not intended to be visible by default in an Info viewer, but may be displayed upon user request.

    <preamble> =
<identification>       # "This is FILENAME, produced by ..."
<copying text>         # Expansion of @copying text.
<dir entries>          # Derived from @dircategory and @direntry.

These pieces are:

<identification line>

An arbitrary string beginning the output file, followed by a blank line.

<copying text>

The expansion of an @copying environment, if the manual has one (see section @copying: Declare Copying Permissions).

<dir entries>

The result of any @dircategory and @direntry commands present in the manual (see section Installing Info Directory Files).

Info Format: Indirect Tag Table

The indirect table is written to the main file in the case of split output only. It specifies the starting byte position of each split output file (as a decimal integer):

    <indirect table> =
^_
Indirect:
(<filename>: <bytepos>)*

The number of preamble bytes written to each output file is included in the positions. Neither the preamble nor the size of the top-level output file is included.

The first actual node of content will be pointed to by the first entry.

Unfortunately, Info-creating programs such as makeinfo have not always implemented these rules perfectly, due to various bugs and oversights. Therefore, robust Info viewers should fall back to searching “nearby” the given position for a node, instead of just giving up if the position is not perfectly at a node beginning.

As an example, suppose split output is generated for the GDB manual. The top-level file ‘gdb.info’ will contain something like this:

^_
Indirect:
gdb.info-1: 1878
gdb.info-2: 295733
...

This tells Info viewers that the first node of the manual occurs at byte 1878 (i.e., after the preamble) of the file ‘gdb.info-1’. The first node written to ‘gdb.info-2’ would start at byte 295733 if the subsequent ‘gdb.info-*’ files (not including ‘gdb.info’ files were appended to ‘gdb.info-1’, including their preambles.

Info Format: Tag Table

The tag table specifies the starting byte position of each node and anchor in the file. It is written in the main output file only, not (in the case of split output) any subfiles.

    <tag table> =
^_
Tag Table:
<lparen>Indirect<rparen> # this line appears in split output only
(Node|Ref): <nodeid>^?<bytepos>
^_
End Tag Table

The ‘(Indirect)’ line is the next line after ‘Tag Table:’ in the case of split output only.

Each following line defines an identifier as either an anchor or a node, as specific. It is an error to define the same identifier both ways. For example, ‘Node: Top^?1647’ says that the node named ‘Top’ starts at byte 1647 while ‘Ref: Overview-Footnote-1^?30045’ says that the anchor named ‘Overview-Footnote-1’ starts at byte 30045.

In the case of nonsplit output, the byte positions simply refer to the location in the output file. In the case of split output, the byte positions refer to an imaginary file created by concatenating all the split files (but not the top-level file). See the previous section.

Here is an example:

^_
Tag Table:
Node: Top^_89
Node: Ch1^_292
^_
End Tag Table

This specifies a manual with two nodes, ‘Top’ and ‘Ch1’, at byte positions 89 and 292 respectively. Because the ‘(Indirect)’ line is not present, the manual is not split.

Info Format: Local Variables

The local variables section is optional and is currently used to give the encoding information. It may be augmented in the future.

    <local variables> =
^_
Local Variables:
coding: <encoding>
End:

See section @documentencoding enc: Set Input Encoding.

Info Format: Regular Nodes

Regular nodes look like this:

    <node> =
^_
File: <fn>, Node: <id1>, (Next: <id2>, )? (Prev: <id3>, )? Up: <id4>

<general text, until the next ^_ or end-of-file>

The Next and Prev pointers are optional. The Up pointer may technically also be absent, although this is most likely the case of a wrongly-structured Info manual. At least one space must be present after each colon and comma, but any number of spaces are ignored.

This <node> defines <id1> in file <fn>, which is typically just ‘manualname’ or perhaps ‘manualname.info’. Each of the other references <id2>, <id3>, and <id4> must be defined with either ‘Node’ or ‘Ref’ in the <tag table>.

Conventionally the nodes are arranged to form a tree, but this is not a requirement of the format. Each pointer can refer to any defined identifier.

Identifiers cannot include periods, commas, colons or parentheses (including @-commands which produce any of these); these can confuse Info readers. See section @node Line Requirements.

The <general text> of the node can include the special constructs described next.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated on October 2, 2013 using texi2html 5.0.

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.