Syntax
npsobj_list ::=
<npsobj list = "name"
[ sortkey1 = "sortKey1"
[ sortmodifier1 = sortModifier ]
[ sortkey2 = "sortKey2"
[ sortmodifier2 = sortModifier ]
[ sortkey3 = "sortKey3"
[ sortmodifier3 = sortModifier ]]]]
[ start = "startIndex" ]
[ ( length = "length" ) | ( end = "end" ) ]
[ reverse = "" ] >
content
</npsobj>
sortModifier ::=
"alpha" |
"numeric" |
"ascending" |
"descending" |
"alpha ascending" |
"alpha descending" |
"numeric ascending" |
"numeric descending"
Task
The instruction is frequently used to automatically
generate tables of contents. It creates a list of file or
link contexts by evaluating name.
name stands for an identifier that
yields a context list, for example toclist or
children. Also, the name of a linklist field
or an export variable to which a context list has been
assigned can be specified.
For each list element, content is
evaluated once (however, see
npsobj_break). For the
evaluation of content,
the current context is temporarily set to the respective list element.
Therefore, all names (such as field names) refer to the
current list element as long as the context in the
content part is not changed.
Sorting elements
The context list can be sorted by comparing the values of
sortKey1 in the contexts. If two values are equal, the
values of sortKey2 are compared. If these values are equal
as well, the order of the contexts is determined using
sortKey3. If the contexts remain unsorted because the values
of every sortkey are identical in all contexts then the final order of
the contexts is undefined. If sortkey1 has not been
specified, the context list will be sorted by the sortkeys that have been
specified for the folder containing the respective files.
Using the sortModifier modifier, it is possible to
specify how the values of two sortkeys are to be compared with each
other. alpha sorts by character value, numeric
numerically, i. e. the character sequence is interpreted as a number.
ascending sorts in ascending, descending in
descending order. One of the two keywords of each modifier pair
(alpha/numeric and
ascending/descending) can be combined with each
other (e.g. numeric descending). The default sort mode is
alpha and the default sort direction is
ascending. Thus, the default modifier combination is
alpha ascending.
Selecting elements
If the attribute start is specified and if
startIndex has a value greater than
0, then startIndex is the index of
the first element of the context list to be considered. The
first element has the index 1. If
startIndex has a value less than 0,
then the first element to be considered will be determined
from the end of the context list. If
startIndex equals 0, then the
attribute will be ignored.
The attribute length allows you to specify
the number of elements in the context list. If
length equals 0 (default) then the elements
beginning at start up to the end of the list
will be returned. A value greater than 0, on the other
hand, determines the maximum number of elements to be
returned, beginning at start. If
length is less than 0, then start specifies
the last element in the list whose maximum number of
elements is determined by the absolute value of
length. For example, start="-1"
and length="-2" returns the second last and
the last element of the list.
As an alternative to length, the
end attribute can be specified. If
end is a positive number, then this
number specifies the index of the last element in the
original list to be considered. The first element has the
index 1. If end is a negative value,
then the absolute value of end
specifies the number of elements to be removed from the end
of the list.
The effect of start and length
or end, respectively, is shown in the
following overview. The element selected with
start is colored green.
| Selected elements | start | length | end |
|---|---|---|---|
 |
|||
 |
3 | 2 | |
 |
5 | -2 | |
 |
-3 | 2 | |
 |
-1 | -3 | |
 |
3 | 5 | |
 |
2 | -2 | |
 |
-3 | 5 | |
 |
-4 | -1 |
Legend: 
Not selected element 
First selected element 
Other selected element
If the reverse attribute has been specified, the order of the
elements is reversed. This is done after the elements have been sorted and
before they are truncated using start and length or
end, respectively.
Example
<npsobj list="toclist" start="2" length="3" sortkey1="title" sortmodifier1="ascending">
<!-- This is processed for each element of the list -->
<npsobj insertvalue="anchor" name="self">
<npsobj insertvalue="var" name="title" /><br />
</npsobj>
</npsobj>