Tags:
create new tag
, view all tags
%SECTION{summary}%This page is intended to provide the information needed to create a file readable by the info viewer program in any plain text editor which allows entry of arbitrary hex characters. Actually, the only required character is \x1f ("^_", the ASCII unit separator).

Most of the necessary information can be gleaned by looking at the samples on this page:

The Quotes from texinfo.info are worth reading for some insights they provide.

Once I came realized that most of the information was easily discernible from the samples, I didn't spend much time trying to dress up the rest of the text on this page.

See:

Contents

Beginning of a .info File

The beginning of info.info, as it appears in Nedit, showing:

  • 4 lines of information for the dir (??) entry,
  • one complete node, and
  • the beginning of a second node.

<us> is the character string which Nedit uses to display the ASCII "unit separator" character (/x1f, "^_").

<sample>

INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Info: (info).         How to use the documentation browsing system.
END-INFO-DIR-ENTRY

<us> 
File: info.info,  Node: Top,  Next: Getting Started,  Up: (dir)

Info: An Introduction
*********************

The GNU Project distributes most of its on-line manuals in the "Info
format", which you read using an "Info reader".  You are probably 
using an Info reader to read this now.

If you are new to the Info reader and want to learn how to use it,
type the command `h' now.  It brings you to a programmed instruction
sequence.

To read about expert-level Info commands, type `n' twice.  This
brings you to `Info for Experts', skipping over the `Getting Started'
chapter.

* Menu:

* Getting Started::             Getting started using an Info reader.
* Expert Info::                 Info commands for experts.
* Creating an Info File::       How to make your own Info file.
* Index::                       An index of topics, commands, and variables.


<us>  
File: info.info,  Node: Getting Started,  Next: Expert Info,  Prev: Top,  Up: Top

Getting Started
***************
</sample>

Overview

See the Sample from a .info File.

An info file is a plain text file divided into multiple "nodes" delimited by a `^_' character (the ASCII "unit separator" character, \x1f, which shows up as <us> in Nedit) followed by a newline (linefeed — \x0a, \n, ^J) or formfeed (\x0c, \f, ^L) (neither of which show up in Nedit except by starting a new line).

The first four lines of the file apparently generate (somehow) an entry in the main "systemwide" info directory (file /usr/info/dir).

A node is the basic unit of information in an info file. A node can be one or more pages (screens) in length.

The header (first line) of a node includes the file name, node name, and links to the Next, Previous and Up (parent) nodes. The standalone info viewer displays these all in the header, Emacs' info mode has an alternate means to display the file and node name.

A node contains the text to be displayed and may contain various types of links to other nodes, possibly arranged to look like a menu, index, table of content, or "cross references" (arbitrary links).

Links may be to nodes within the same (info) file or to a different info file. A link to a different file contains the file name in parenthesis before the node name, e.g., "(info_file)Node_Name".

In the stand-alone info reader program (not the Emacs info "mode") the header line includes the names of the file and the node.

The mode line that appears at the bottom of an Info window (starts typically with "-----Info:" or "--zz-Info:") is not contained in the .info file but is apparently generated.

See also Quotes from texinfo.info.

First Four Lines

The first four lines apparently set an entry in the system wide file /usr/info/dir file that is the top level directory for info. Run info and look for the entry labeled "* Info: (info)." under the heading "Texinfo documentation system". Some related points:

  • I assume (I know wink ) that the dir file is generated automatically, but I don't yet know how.
  • I'm guessing that there can be more than one set of those 4 lines within a single file, see the 5 entries for the texinfo file just prior to the entry for info, and see the 2 entries for info-stnd after the entry. This is also based on things I read in the info documentation (a statement like ~"the nodes can be arranged in a directed graph of any form, cyclic, acyclic, closed, open") and a similar hint (or the same hint) that you can even have more than one independent graph in the same node. (I don't know if my use of the words graph, cyclic, acyclic, etc. are anywhere close to correct, I really never had much exposure to such "graphs".)

See also Quotes from texinfo.info.

A Node

After the first four lines of a file, leave a blank line, then start a node with the ASCII unit separator character (/x1f, "^_"), shown in Nedit as <us>.

The header (first line) of a node includes the file name, node name, and links to the Next, Previous and Up (parent) nodes. The standalone info viewer displays these all in the header, Emacs' info mode has an alternate means to display the file and node name.

A node contains the text to be displayed and may contain various types of links to other nodes, possibly arranged to look like a menu, index, table of content, or "cross references" (arbitrary links).

Links may be to nodes within the same (info) file or to a different info file. A link to a different file contains the file name in parenthesis before the node name, e.g., "(info_file)Node_Name".

Cross References

"A cross reference can be placed anywhere in the text, unlike a menu item which must go at the front of a line. A cross reference looks like a menu item except that it has `*note' instead of `*'. It cannot be terminated by a `)', because `)''s are so often part of node names. If you wish to enclose a cross reference in parentheses, terminate it with a period first. Here are two examples of cross references pointers:"

*Note details: commands.  (See *note 3: Full Proof.)

You cannot necessarily expect the target node of a cross reference "to have `Next', `Previous' or `Up' links pointing back to where you came from. In general, the `l' (el) command is the only way to get back there."

Cross References

A cross reference (link) consists of three parts:

  • label: arbitrary text displayed for the convenience of the reader (optional, see examples below)
  • target: the destination node
  • comment: more (optional) arbitrary text

A cross reference "cannot be terminated by a ")", because ")"'s are often part of node names. If you wish to enclose a cross reference in parentheses, terminate it with a period first. Here are two examples of cross references pointers:"

Examples

*Note <label>: [(<file>)]<target>.        <comment>

A short form, if the label is the same as the target node:

*note [(<file>)]<target>::        <comment>

Menus

<some of the following lines may be direct quotes from one of the info files>

  • Any node may have a menu (a list of subnodes).
  • A menu begins with a line starting with "* Menu:". The rest of the line is a comment.
  • After the starting line, every line that begins with a `* ' lists a single topic.

* <label>: <node_name>

  • The label is what the user must type after m to select the node.
  • The node name may be terminated with a tab, comma, newline, or period.
  • If the label and node name are the same, omit the node_name and end the label with "::"
  • "It is considerate to choose the topic names so that they differ from each other very near the beginning--this allows the user to type short abbreviations. In a long menu, it is a good idea to capitalize the beginning of each item name which is the minimum acceptable abbreviation for it (a long menu is more than 5 or so entries).

Index

<very similar to a menu, but later>

Tags Tables for Info Files

You can speed up the access to nodes of a large Info file by giving it a tags table. Unlike the tags table for a program, the tags table for an Info file lives inside the file itself and is used automatically whenever Info reads in the file.

To make a tags table, go to a node in the file using Emacs Info mode and type `M-x Info-tagify'. Then you must use `C-x C-s' to save the file. Info files produced by the `makeinfo' command that is part of the Texinfo package always have tags tables to begin with.

Once the Info file has a tags table, you must make certain it is up to date. If you edit an Info file directly (as opposed to editing its Texinfo source), and, as a result of deletion of text, any node moves back more than a thousand characters in the file from the position recorded in the tags table, Info will no longer be able to find that node. To update the tags table, use the `Info-tagify' command again.

An Info file tags table appears at the end of the file and looks like this:

     ^_^L
     Tag Table:
     File: info, Node: Cross-refs^?21419
     File: info,  Node: Tags^?22145
     ^_
     End Tag Table

Note that it contains one line per node, and this line contains the beginning of the node's header (ending just after the node name), a `DEL' character, and the character position in the file of the beginning of the node.

Sample Partial Tag Table

Tag Table:
Node: Top1397
Node: Getting Started2264
Node: Help-Small-Screen3070
Node: Help4908
Node: Help-P6424
Node: Help-^L7617
Ref: Help-^L-Footnote-112415
Node: Advanced28113
Node: Info Search30912
Node: Add34472
Ref: Add-Footnote-137864
Node: Emacs Info Variables46028
Node: Creating an Info File49100
Node: Index49787
 
End Tag Table

Adding a New Node to Info

    • The Node, Next, Previous, and Up keywords "may appear in any order, anywhere in the header line, but the recommended order is the one in this sentence."
    • Each keyword must be followed by a colon, spaces and/or tabs, and then the appropriate name. The Node must be in this file, any other node name may be in another file, specified by the file name (less the .info suffix) in parenthesis.
    • The name may be terminated with a tab, a comma, or a newline hmm, can the header be multiple lines, or is newline only valid to terminate the last name on the line — and does whoever originally wrote this think they wrote unambiguously??.
    • Node names may contain spaces.
    • The case of letters in the names is insignificant.
  • ends with either a `^_', `^L' ("formfeed"), or the end of file.

An example header line: File: info.info,  Node: Cross-refs,  Next: Tags,  Prev: Menus,  Up: Expert Info

Notes:

  1. A node can be in the current file or any other (info?) file. If the node is in another file, the file name (less the .info suffix?) is included in parenthesis before the node name. (E.g., "(info)Add")
  2. "If the file name starts with "./", then it is relative to the current directory; otherwise, it is relative starting from the standard directory for Info files of your site." What is that, typically? Hmm, maybe on this knoppix 3.2 installation it is /usr/info?
  3. "The name `(FILENAME)Top' can be abbreviated to just `(FILENAME)'. By convention, the name `Top' is used for the "highest" node in any single file--the node whose `Up' points out of the file."
  4. "The `Directory' node is `(dir)', it points to a file `dir' which holds a large menu listing all the Info documents installed on your site. The `Top' node of a document file listed in the `Directory' should have an `Up: (dir)' in it."
  5. "The node name `*' is special: it refers to the entire file. Thus, `g*' shows you the whole current file. The use of the node `*' is to make it possible to make old-fashioned, unstructured files into nodes of the tree."
  6. In the header, "the `Node:' name, in which a node states its own name, must not contain a file name, since when Info searches for a node, it does not expect a file name to be there. The `Next', `Previous' and `Up' names may include file names. In this node, since the `Up' node is in the same file, it was not necessary to use one. (1) If you end a node with a formfeed, "be sure that there is a `^_' after it to start the" next node, "since `^L' cannot start a node. A nicer way to make a node boundary be a page boundary as well is to put a `^L' right after the `^_'." not quite sure what they mean by a node boundary being the same as a page boundary — may have to experiment

"Note that the nodes in the" info(?) "file have a file name in the header line. The file names are ignored by Info, but they serve as comments to help identify the node for the user."

Quotes from texinfo.info

This quotation, from texinfo.info, provides some useful background:

Info files are divided into pieces called "nodes", each of which contains the discussion of one topic. Each node has a name, and contains both text for the user to read and pointers to other nodes, which are identified by their names. The Info program displays one node at a time, and provides commands with which the user can move to other related nodes.

Each node of an Info file may have any number of child nodes that describe subtopics of the node's topic. The names of child nodes are listed in a "menu" within the parent node; this allows you to use certain Info commands to move to one of the child nodes. Generally, a Info file is organized like a book. If a node is at the logical leve of a chapter, its child nodes are at the level of sections; likewise, the child nodes of sections are at the level of subsections.

All the children of any one parent are linked together in bidirectional chain of `Next' and `Previous' pointers. The `Next' pointer provides a link to the next section, and the `Previous' pointer provides a link to the previous section. This means that all the nodes that are at the level of sections within a chapter are linked together. Normally the order in this chain is the same as the order of the children in the parent's menu. Each child node records the parent node name as its `Up' pointer. The last child has no `Next' pointer, and th first child has the parent both as its `Previous' and as its `Up' pointer.(1) (*note Info Files-Footnote-1::)

The book-like structuring of an Info file into nodes that correspond to chapters, sections, and the like is a matter of convention, not requirement. The `Up', `Previous', and `Next' pointers of a node can point to any other nodes, and a menu can contain any other nodes. Thus, the node structure can be any directed graph. But it is usually more comprehensible to follow a structure that corresponds to the structure of chapters and sections in a printed book or report.

Some other quotations, from somewhere in the info, texinfo, or info-stnd files:

The nodes listed in a node's menu are called its "subnodes", and it is their superior. They should each have an `Up:' pointing at the superior. It is often useful to arrange all or most of the subnodes in a sequence of `Next' and `Previous' pointers so that someone who wants to see them all need not keep revisiting the Menu.

The Info Directory is simply the menu of the node `(dir)Top'--that is, node `Top' in file `.../info/dir'. You can put new entries in that menu just like any other menu. The Info Directory is not the same as the file directory called `info'. It happens that many of Info's files live in that file directory, but they do not have to; and files in that directory are not automatically listed in the Info Directory node.

Also, although the Info node graph is claimed to be a "hierarchy", in fact it can be any directed graph. Shared structures and pointer cycles are perfectly possible, and can be used if they are appropriate to the meaning to be expressed. There is no need for all the nodes in a file to form a connected structure. In fact, this file has two connected components. You are in one of them, which is under the node `Top'; the other contains the node `Help' which the `h' command goes to. In fact, since there is no garbage collector, nothing terrible happens if a substructure is not pointed to, but such a substructure is rather useless since nobody can ever find out that it exists.

Checking an Info File

If you put the wrong name of a node in a link, the problem is not detected until someone attempts to use the link.

In Emacs info mode there is a command (M-x Info-validate), which will confirm that all links to nodes internal to the current file are valid. (It does not check links to nodes in other files, originally because such a check would be slow.)

Creating an Info File from a Texinfo File

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

*Note Overview of Texinfo: (texinfo)Top, to learn how to write a Texinfo file.

*Note Creating an Info File: (texinfo)Creating an Info File, to learn how to create an Info file from a Texinfo file.

*Note Installing an Info File: (texinfo)Installing an Info File, to learn how to install an Info file after you have created one.

Contributors

  • () RandyKramer - 21 Dec 2003
  • If you edit this page: add your name here; move this to the next line; and if you've used a comment marker (your initials in parenthesis), include it before your WikiName.

Revision Comment

%SECTION{last_revision}%
  • %DATE% —

Page Ratings

Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r3 - 2003-12-26 - RandyKramer
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by PerlCopyright 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding WikiLearn? WebBottomBar">Send feedback
See TWiki's New Look