3.1 Sections

“Sections” in plasT_eX 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 L^aT_eX, 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 L^aT_eX 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

plasT_eX 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.

plasT_eX 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.