Contents Previous Next navigate

Setting Relative Navigation Links For A Section

Syntax
$navigate%type 1%label 1% ... %type n%label n%$$

Purpose
OMhelp automatically creates navigation links, relative to each section (at the top of each section). The $navigate command determines which navigation links are included, the order of the links, and label for each of the links.

Type
The possible type , and meaning, for the navigation links are specified below. In addition, each type has a default label that is used when the label is empty.

Content
The table of contents section for entire document. The default label for this type is Content.

Prev
The previous section in read order. The default label for this type is Prev.

Next
The next section in read order. The default label for this type is Next.

Across
The group of sections that cross reference entire document; e.g, the search and index sections are in this group. The default label for this type is Index.

Top
The section corresponding to the top of the tree; i.e., the section in the root_file . The default label for this type is Top.

Up
The sections starting at the top of tree and down to the current section. The default label for this type is Up.

Sibling
The group of sections with same parent as the current section. This has the same meaning as Down_up_1; i.e., down one and then up one. The default label for this type is _up_1.

Down
The group of sections directly below the current section; i.e., its children. This has the same meaning as Down_up_0; i.e., down one and then up zero. The default label for this type is _up_0.

Down_up_i
For i between 0 and 9, the type Down_up_i is the group of sections directly below the section i levels up from the current section. The default label for this type is _up_i .

Current
The group of headings and subheadings in the current section. If the corresponding label is _jump_table, a table at the top of the current section is used to link to the headings and sub-headings for this section. The default label for this type is _jump_table.

Example
Suppose that the tree corresponding to a document is
                      A
            B              N    R     W
        C       F         OPQ  STUV  XYZ
       DE     G   J
             HI  KLM
The corresponding read order is  A,  B, ...,  Z. For this example, if the current section is  F
current section  F
previous section  E
next section  G
section above  B
section two levels up  A
sections up from this one  A,  B,  F
siblings  C,  F
children  G,  J

Label
The value label 1 is the label that the user will see for the navigation links corresponding to type 1 . The value label 2 is the label that the user will see for the navigation links corresponding to type 2 and so on. The labels cannot begin with the special character _ with the following exception below:

Default
A default value is specified for each type that is used when the corresponding label is empty; e.g., in the syntax type_i%%type_i+1 ... uses the default value for the i-th label.

_up_i
The label _up_i , where i is a number between 0 and 9, is a special case. In this case, the cross reference tag for the section i levels up from the current section is used for the label. In the case where type is Down_up_i and label is _up_i , the same cross reference link table can be used by many sections. This results in smaller file sizes and less changes when sections are added or moved. (Change result in differences when the output of OMhelp is checked into a source code control system for viewing on the web.)

_jump_table
If type is Current, the label _jump_table is a special case. In this case, a table at the top of the current section is used to link to the headings and sub-headings for this section.


Note that the size of the label corresponding to _up_i will change from section to section. Hence the position of subsequent labels in the navigation command will change. Because the user will often repeatedly select Prev or Next, it is desirable to have their positions the same for all sections. This requires placing them before any labels that will change size between sections.

No Such Section
If Down_up_i is the specified type, and there is no section i levels up, neither the label nor its links will be present on the current section. If _up_i is specified label, and there is not section i levels up, neither the label nor its links will be present on the current section.

Default
The default value for the navigation command is 
 
     $navigate%
          Prev%%
          Next%%
          Across%%
          Up%%
          Down_up_4%%
          Down_up_3%%
          Down_up_2%%
          Down_up_1%%
          Down_up_0%%
          Current
     %%$$
Note that, this is equivalent to 
 
     $navigate%
          Prev%Prev%
          Next%Next%
          Across%Index%
          Up%Up%
          Down_up_4%_up_4%
          Down_up_3%_up_3%
          Down_up_2%_up_2%
          Down_up_1%_up_1%
          Down_up_0%_up_0%
          Current%_jump_table
     %$$

Example
The navigation links for this section were specified with the following command: 
 
     $navigate%
          Content%Contents%
          Prev%Previous%
          Next%Next%
          Across%Across%
          Up%Location%
          Down_up_2%Parents%
          Down_up_1%Siblings%
          Down_up_0%_up_0%
          Current%Headings
     %$$

Root Section
In the special case where a $navigate command appears in the root section section, and does not appear in the current section, the value specified in the root section is used for the current section; i.e., it replaces the default command above.
Input File: omh/navigate.omh