[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
F.1 Info Format General Layout
This section describes the overall layout of Info manuals.
• Whole | Split vs. nonsplit manuals. | |
• Preamble | ||
• Indirect | ||
• Tag table | ||
• Local variables | ||
• Regular nodes |
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.