text.info - Accessing info document ¶This module provides some basic functionalities to extract information
from info files, a documentation format defined by
texinfo system (https://www.gnu.org/software/texinfo/).
It is used in REPL toplevel commands infoand doc
(see Working in REPL).
It focuses mainly to handle Gauche documents, so it may not handle
all features used in texinfo.
{text.info}
An object for opened info file(s), returned by open-info-document.
All slots are private.
{text.info}
An object for each info node. It keeps the node’s content, as well
as links to neighboring nodes. Its instance should be considered
immutable object.
A node can be obtained from an <info-document> object by
info-get-node.
<info-node>: name ¶A string name of the info node. Every info document has at least
"Top" node.
<info-node>: next ¶The string name of the next node. You can visit all nodes in
the document following the next link.
It may be #f if the node is the last one of the document.
<info-node>: prev ¶The string name of the previous node. It’s a reverse link
of the next node. The previous node of "Top" is
"(dir)" by convention, which is a special node
that lists all info documents installed on the system (it is not
included in the info document itself.)
<info-node>: up ¶If the node is a subnode, this contains the name of the upper node
(a chapter name for sections, a section name for subsections, etc.)
It is #f for "Top" node.
<info-node>: file ¶An <info-document> object of the info document this node is contained.
<info-node>: content ¶A string content of the node.
{text.info}
Open the named info document and returns an <info-document> instance.
The argument is a pathname to a master info file, usually with
.info suffix. Depending on the installation, info files
may be compressed with gzip or bzip2, having extensions
.gz or .bz2 after .info; you don’t need to
specify those extensions. The procedure searches possible compression
options.
A large info document may be splitted into multiple info files,
each with a suffix .info-1, .info-2 etc. Those are
automatically read, so you only need to give the path to the master file.
If it can’t find the named document, or can’t recognize its format, an error is thrown.
{text.info}
The info-doc argument is an <info-document> instance.
Returns an <info-node> instance with the string name node-name,
or #f if no node with the given name is found.
{text.info}
Read the node named index-node-name in the info document
info-doc, and adds its menu entries into the index table.
It is particularly useful to give the index page of the info doc,
so that you’ll be able to lookup particular term (e.g. function name)
quickly. Typical info document has a node called Index.
Large documents, such as programming language reference
(Gauche Users’ Reference is one of them) may have multiple
index pages for different categories. You can call this procedure
multiple times to add more than one index pages.
The optional key-modifier argument is a procedure applied to
the entry-name (string) to obtain a key (string) in the index table.
Sometimes the index uses different entry name
from the actual name; e.g. Gauche’s class index lists class names without
surrounding < and >, since using the actual name makes all
class names being listed below < subheading, which isn’t very useful.
You can pass (^e #"<~|e|>") as key-modifier to recover the actual
class name to be used as the key.
If there are more than one entries per key, both are saved in the
index table. See info-index-ref below.
{text.info}
Lookup index with the given key. Returns a list of
(node-name line-number).
You can use pass node-name to info-node-get to obtain the
info node contaning the definition, then pass the node and
line-number to info-extract-definition
to obtain the definition as a text.
{text.info}
Returns a list of keys (strings) in the index.
{text.info}
Returns the content of the index
as ((key (node line) ...) ...).
{text.info}
This is used in info-index-add!, but it is generally
useful to parse a menu in an info node. It searches
the * Menu: line, then gathers menu entry names and
associated node names. Some menus such as index page also
lists line numbers for each entry.
Returns a list of menu entries. Each menu entry is the following form:
(<entry-name> <node-name> [<line-number>])
{text.info}
Extract one definition from the node’s content. Assumes the definition
begins from the specified line; then we go forward to find the end of
the definition. The end of definition is when we see the end of content,
or we see a line begins with less than or equal to 3 whitespaces.
(Except the ’defunx’-type multi entry).
Returns a string describing the definition. If no definition is found, an empty string is returned.
A typical idiom is to add index node using info-index-add!,
and get the node name and line number of the definition of a specific
item with info-index-ref, then
then use this procedure to extract the definition.