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

These option names are split on the dash (-) to create a key, before the dash, and a member, after the dash. A dictionary is inserted into the navigation object with the name of the key, and the members are added to that dictionary. The configuration above would create the following Python dictionary.

{
    'next':
        {
            'url':'http://myhost.com/glossary',
            '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: --links=[ key optional-url title ]
specifies links to be included in the navigation object. Since at least two values are needed in the links (key and title, with an optional URL), the values are grouped in square brackets on the command-line ([ ]).