plasTeX 3.0 — A Python Framework for Processing LaTeX Documents: Navigation and Links

3.1.1 Navigation and Links

The plasTeX.Base.LaTeX.Sectioning.SectionUtils class has a property named links that contains a dictionary of many useful objects that assist in creating navigation bars and breadcrumb trails in the rendered output. This dictionary was modeled after the links described at http://fantasai.tripod.com/qref/Appendix/LinkTypes/ltdef.html. Some of the objects in this dictionary are created automatically, others are created with the help of the linkType attribute on the document nodes, and yet others can be added manually from a configuration file or command-line options. The automatically generated values are listed in the following table.

Name	Purpose
begin	the first section of the document
breadcrumbs	a list containing the entire parentage of the current section (including the current section)
chapter	the current chapter node
child	a list of the subsections
contents	the section that contains the top-level table of contents
document	the document level node
end	the last section of the document
first	the first section of the document
home	the first section of the document
home	the first section of the document
last	the last section of the document
navigator	the section that contains the top-level table of contents
next	the next section in the document
origin	the section that contains the top-level table of contents
parent	the parent node
part	the current part node
prev	the previous section in the document
previous	the previous section in the document
section	the current section
sibling	a list of the section siblings
subsection	the current subsection
start	the first section of the document
toc	the section that contains the top-level table of contents
top	the first section of the document
up	the parent section

Note: The keys in every case are simply strings. Note: Each of the elements in the table above is either a section node or a list of section nodes. Of course, once you have a reference to a node you can acces the attributes and methods of that object for further introspection. An example of accessing these objects from a section instance is shown below.

previousnode = sectionnode.links['prev']
nextnode = sectionnode.links['next']

The next method of populating the links table is semi-automatic and uses the linkType attribute on the Python macro class. There are certain parts of a document that only occur once such as an index, glossary, or bibliography. You can set the linkType attribute on the Python macro class to a string that corresponds to that sections role in the document (i.e. ‘index’ for the index, ‘glossary’ for the glossary, ‘bibliography’ for the bibliography). When a node with a special link type is created, it is inserted into the dictionary of links with the given name. This allows you to have links to indexes, glossaries, etc. appear in the links object only when they are in the current document. The example below shows the theindex environment being configured to show up under the ‘index’ key in the links dictionary.

class theindex(Environment, SectionUtils):
    nodeType = 'index'
    level = Environment.SECTION_LEVEL

Note: These links are actually stored under the ‘links’ key of the owner document’s userdata dictionary (i.e. self.ownerDocument.userdata[’links’]). Other objects can be added to this dictionary manually.

The final way of getting objects into the links dictionary is through a configuration file or command-line options. This method is described fully in section 2.1.4.