5. Skribilo User Manual — Indexes
Contents ↑ Skribilo User Manual

Skribe support indexes. One may accumulate all entries inside one unique index or dispatch them amongst user declared indexes. Indexes may be monolithic or split. They only differ in the way they are rendered by the back-ends. For a split index a sectioning based on the specific (e.g., "the first one") character of index entries is deployed.

5.1 Making indexes

The function make-index declares a new index.

( make-index ident )
ident A string, the name the index (currently unused).
See also default-index , index , the-index , ref , mark .

For instance, the following Skribe expression declares an index named *index1*:


(

define
 *index1* (make-index 
"a new index"
))
Ex. 26: Creation of a new index

This example produces no output but enables entries to be added to that index. In general it is convenient to declare indexes before the call to the document function.

The function default-index returns the default index that pre-exists to all execution.

( default-index )

5.2 Adding entries to an index

The function index adds a new entry into one existing index and sets a mark in the text where the index will point to. It is an error to add an entry into an index that is not already declared.

( index [ :url ] [ :shape ] [ :index ] [ :note ] [ :class "index"] [ :ident ] name )
:ident The node identifier. html lout latex context info xml
:class The node class. html lout latex context info xml
:index The name of the index whose index entry belongs to. A value of #f means that the default-index owns this entry.
:note An optional note added to the index entry. This note will be displayed in the index printing.
:shape An optional shape to be used for rendering the entry.
:url An optional URL that is referenced in the index table instead of the location of the index.
name The name of the entry. This must be a string.
See also make-index , default-index , the-index .

The following expressions add entries to the index *index1*:




[
The identifier ,(

code
 
"Foo"
),(

index
 

:index
 *index1* 
"Foo"
) is a usually

used as an example. When two identifiers have to used, frequently the

second choice is ,(

code
 
"Bar"
),(

index
 

:index
 *index1* 
"Bar"
 

:shape
 (

it
 
"Bar"
)).

When three are needed, some use ,(

code
 
"Baz"
)

,(

index
 

:index
 *index1* 
"Baz"
 

:shape
 (

it
 
"Baz"
)).



This illustrates how to use identifier

,(

index
 

:index
 *index1* 
"Foo"
 

:note
 
"How to use Foo"
)

,(

index
 

:index
 *index1* 
"Foo"
 

:note
 
"How not to use Foo"
)

,(

index
 

:index
 *index1* 
"Fooz"
)

...

]
Ex. 27: Adding entries to an index The identifier Foo is a usually used as an example. When two identifiers have to used, frequently the second choice is Bar . When three are needed, some use Baz . This illustrates how to use identifier ...

There is no output associated with these expressions.

5.3 Printing indexes

The function the-index displays indexes in the produced document.

( the-index [ :column 1] [ :header-limit 50] [ :char-offset 0] [ :split ] [ :class "the-index"] [ :ident ] index... )
:ident The node identifier. html lout latex context info xml
:class The node class. html lout latex context info xml
:split If #t, character based sectioning is deployed. Otherwise all the index entries are displayed one next to the other.
:char-offset The character number to use when split is required. This option may be useful when printing index whose items share a common prefix. The argument can be used to skip this prefix.
:header-limit The number of entries from which an index header is introduced.
:column The number of columns of the index.
index... The indexes to be displayed. If index is provided, the global index default-index is printed.

If the engine custom index-page-ref is true when a index is rendered then, page reference framework is used instead of a direct reference framework.


(the-index *index1*)
Ex. 28: Printing indexes

... produces:

Bar
Baz
Foo
... How to use Foo
... How not to use Foo
Fooz

See the Skribe [ ?mark global index: ./index.skb:127:21: ] for a real life index example.

(made with skribilo)