2.1.4 Document Links
The links section of the configuration is a little different than the others. The options in the links section are not preconfigured, they are all user-specified. The links section includes information to be included in the navigation object available on all sections in a document. By default, the section’s navigation object includes things like the previous and next objects in the document, the child nodes, the sibling nodes, etc. The table below lists all of the navigation objects that are already defined. The names for these items came from the link types defined at http://fantasai.tripod.com/qref/Appendix/LinkTypes/ltdef.html. Of course, it is up to the renderer to actually make use of them.
|
Name |
Description |
|
home |
the first section in the document |
|
start |
same as home |
|
begin |
same as home |
|
first |
same as home |
|
end |
the last section in the document |
|
last |
same as end |
|
next |
the next section in the document |
|
prev |
the previous section in the document |
|
previous |
same as prev |
|
up |
the parent section |
|
top |
the top section in the document |
|
origin |
same as top |
|
parent |
the parent section |
|
child |
a list of the subsections |
|
siblings |
a list of the sibling sections |
|
document |
the document object |
|
part |
the current part object |
|
chapter |
the current chapter object |
|
section |
the current section object |
|
subsection |
the current subsection object |
|
navigator |
the top node in the document object |
|
toc |
the node containing the table of contents |
|
contents |
same as toc |
|
breadcrumbs |
a list of the parent objects of the current node |
Since each of these items references an object that is expected to have a URL and a title, any user-defined fields should contain these as well (although the URL is optional in some items). To create a user-defined field in this object, you need to use two options: one for the title and one for the URL, if one exists. They are specified in the config file as follows:
[links] next-url=http://myhost.com/glossary next-title=The Next Document mylink-title=Another Title
While you can not override a field that is populated by the document, there are times when a field isn’t populated. This occurs, for example, in the prev field at the beginning of the document, or the next field at the end of the document. If you specify a prev or next field in your configuration, those fields will be used when no prev or next is available. This allows you to link to external documents at those points.
- Set document links
Command-Line Options: --link=key optional-url title
specifies links to be included in the navigation object.