3.1 Sections

“Sections” in plasTeX refer to any macro that creates a section-like construct in a document including the document environment, \part, \chapter, \section, \subsection, \subsubsection, \paragraph, and \subparagraph. While these are the sectioning macros defined by LaTeX, you are not limited to using just those commands to create sections in your own documents. There are two elements that must exist for a Python macro class to act like a section: 1) the level attribute must be set to a value less than 100, and 2) the class should inherit from plasTeX.Base.LaTeX.Sectioning.SectionUtils.

The level attribute refers to the section level in the document. The values for this attribute are the same values that LaTeX uses for its section levels, namely:

-1 or Node.PART_LEVEL

corresponds to \part

0 or Node.CHAPTER_LEVEL

corresponds to \chapter

1 or Node.SECTION_LEVEL

corresponds to \section

2 or Node.SUBSECTION_LEVEL

corresponds to \subsection

3 or Node.SUBSUBSECTION_LEVEL

corresponds to \subsubsection

4 or Node.PARAGRAPH_LEVEL

corresponds to \paragraph

5 or Node.SUBPARAGRAPH_LEVEL

corresponds to \subparagraph

plasTeX adds the following section related levels:

-sys.maxint or Node.DOCUMENT_LEVEL

corresponds to the document environment and is always the top-level section

6 or Node.SUBSUBPARAGRAPH_LEVEL

this level was added to correspond to the sixth level of headings defined in HTML

100 or Node.ENDSECTIONS_LEVEL

flag that indicates the last possible section nesting level. This is mainly used for internal purposes.

plasTeX uses the level attribute to build the appropriate document structure. If all you need is a proper document structure, the level attribute is the only thing that needs to be set on a macro. However, there are many convenience properties in the plasTeX.Base.LaTeX.Sectioning.SectionUtils class that are used in the rendering process. If you plan on rendering your document, your section classes should inherit from this class. Below is a list of the additional properties and their purpose.

Name

Purpose

allSections

contains a sequential list of all of the sections within and including the current section

documentSections

contains a sequential list of all of the sections within the entire document

links

contains a dictionary contain various amounts of navigation information corresponding mostly to the link types described at http://fantasai.tripod.com/qref/Appendix/LinkTypes/ltdef.html. This includes things like breadcrumb trails, previous and next links, links to the overall table of contents, etc. See section 3.1.1 for more information.

siblings

contains a list of all of the sibling sections

subsections

contains a list of all of the sections within the current section

tableofcontents

contains an object that corresponds to the table of contents for the section. The table of contents is configurable as well. For more information on how to configure the table of contents see section 3.1.2

Note: When first accessed, each of these properties actually navigates the document and builds the returned object. Since these operations can be rather costly, the values are cached. Therefore, if you modify the document after accessing one of these properties you will not see the change reflected.