Configuring the INI file

Generates link lists based on instructions in a minitoc.ini file. It is important to set up this file properly.

This plugin relies on the instructions defined in a minitoc.ini file in the same folder as the book or file being processed. This INI file defines at least two sections. First is the MiniToc section, which defines one or more MiniToc group sections. Each MiniToc group defines all of the properties for a link list that will be created if a matching condition is found. There will also be a section for each group defined in the MiniToc section.

The following MiniToc section defines two groups, “H1” and “H2” (for lack of better names). The H1 group creates a list of links to all level 1 headings in a document and the H2 group creates a list of links to all level 2 headings within a document. The Count property indicates the number of groups, and each group is identified by sequential numbers starting from 1.

[MiniToc] 
Count=2 
1=H1 
2=H2

Each group defined in the MiniToc section requires an INI section to specify the properties of each list and the scope to consider when creating the list. These sections are named MiniToc-<groupname>. For example, to support the groups defined by the MiniToc section above, there would be two sections, MiniToc-H1 and MiniToc-H2.

Each MiniToc group section defines a number of properties depending on how the link lists are to be created. The following example lists all of the possible properties in an MiniToc group section. Items in square brackets are optional. These properties are described in detail below.

[MiniToc-<groupname>] 
TocContainer=<elemname>[/@<attrname>='<attrval>'] 
DeletePlaceholder=0 
ScopeRootElem=<elem-id> or <relative-elemname>  
XrefFmt=[<xref-fmtname>] 
XrefElem=[<xref-elemname>] 
NumTemplates=<num> 
<N>=<targetParaTag>|<tocElem[/attr]>[|<xref-fmtname>[|<xref-elemname>]]
TocContainer

Specifies the container element to match in the structured file where the mini TOC list will be created. This value can be just an element name or can be the element name with an attribute and attribute value. A mini TOC may be created for each instance of this TocContainer match in a document.

To insert a mini TOC into each section element that has the outputclass attribute set to “minitoc” use the following entry:

TocContainer=section/@outputclass='minitoc'
DeletePlaceholder

If set to “1”, deletes the first child element of the of the “TocContainer” element. This is used for cases where the container element requires a child element, such as a ul/li structure. An li element would be added while authoring as a placeholder, but it would be deleted when the list is generated. If this property is not included, the default value is “0”.

ScopeRootElem

Defines the scope to scan for TOC link targets (based on the defined “templates” described below). This value can be an element ID, or it can specify an element name relative to the matching TocContainer. To specify a relative element name, precede the element name with a “<” or “>“, where “<” says to look “up” for an ancestor element, and “>” says to look “down” for a following sibling or sibling’s descendant. If ScopeRootElem is missing or empty, the entire document is assumed to be the scope.

If using this plugin with DITA-FMx, to set the TOC link scope to be all content within the “current” topic, use the following entry (remember that this is run on the “Book” app files so each topic will be wrapped in an fm-ditafile element):

ScopeRootElem=<fm-ditafile

If the ScopeRootElem specifies an element that is the child of an fm-ditafile element, the scope will be set to the fm-ditafile element.

XrefFmt

The name of the Cross-Ref format to be used for the links in this mini TOC. This property is optional, and may be omitted if the format name is specified in the target matching template.

XrefElem

The name of the element to be used for the links in this mini TOC. This property is optional, and may be omitted if the element name is specified in the target matching template.

NumTemplates

Each MiniToc group section defines one or more link target matching templates. This property specifies the number of templates in this group.

<N>[.<COL>]

For most mini TOCs, each target-matching template is identified by sequential numbers starting with “1”. An alternate format of two sequential numbers (<N>.<COL>) is used for creating a mini TOC formatted as a table. For both formats, the value of this property is a vertical bar delimited string of the following format:

<targetParaTag>|<tocElem[/attr]>[|<xrefFmt>[|<xrefElem>]]

Where:

  • <targetParaTag> is the name of the paragraph tag that contains the content to be linked by the cross-reference.

    There may be situations where the target paragraph tag may be one of many based on the content hierarchy. If this is the case, you can use a special syntax that sets the target tag based on the first paragraph tag of the ScopeRootElem range.

    #R1,T1#R2,T2#R3,T3

    In this example, if “R1” is the first paragraph tag name, “T1” is used as the target tag. If “R2” is the first paragraph tag name, “T2” is used as the target tag. And so on. If none of the “#” tag names match the first paragraph tag, the template fails and processing proceeds to the next (if any) template. No space is allowed in this syntax other than where used in a tag name. Due to this syntax structure, paragraph tags that include the “#” or “,” characters will likely not work properly.

  • <tocElem[/attr]> is the element (and optional attribute='value') to use as the container for the TOC entry (the cross-ref elem is created within this element).

  • <xrefFmt> defines the cross-ref format to use for the cross-ref. This is optional as long as it’s defined by the XrefFmt property which is used for all cross-refs that don't define it here.

  • <xrefElem> defines the cross-ref element to use for the cross-ref. This is optional as long as it’s defined in the XrefElem property which is used for all cross-refs that don't define it here.

If you’re creating a mini TOC table, use the <N>.<COL> format, where <N> is a sequential numeric value starting with “1” for each row in the table, and <COL> is a sequential numeric value starting with “1”, which identifies the column number for the template. If your toc-table has two columns, you’d have two entries, “1.1” and “1.2”. Other than this alternate format, the value of this property is the same as other mini TOC structures. You just define a separate template for each table column as <N>.1, <N>.2, and so on.

TargetProximity

When using the <N>.<COL> format (described above), the <N>.2 (and greater) targets are scanned within a specified proximity to the <N>.1 target. By default, this proximity value is 4, but if you’d like to specify a value greater or less than this default, set that value in the TargetProximity property.

The following MiniToc group sections are examples for the groups defined by the MiniToc section above. This will create mini TOCs for each level 1 and level 2 heading in the file, each with one level of links to the child headings below the current heading.

[MiniToc-H1] 
TocContainer=section/@outputclass='minitoc' 
ScopeRootElem=<fm-ditafile 
XrefFmt=title.1TOC 
XrefElem=fm-xref 
NumTemplates=1 
1=title.1|p/@outputclass='toc-level1' 
 
[MiniToc-H2] 
TocContainer=section/@outputclass='minitoc' 
ScopeRootElem=<fm-ditafile 
XrefFmt=title.1TOC 
XrefElem=fm-xref 
NumTemplates=1 
1=title.2|p/@outputclass='toc-level2'

If you wanted to build a single list of links at the top of a file that linked to both levels of headings, you’d create a single MiniToc group section that uses two matching templates.

[MiniToc-H0] 
TocContainer=section/@outputclass='minitoc' 
ScopeRootElem=<fm-ditafile 
;XrefFmt=title.1TOC 
XrefElem=fm-xref 
NumTemplates=2 
1=title.1|p/@outputclass='toc-level1'|title.1TOC 
2=title.2|p/@outputclass='toc-level2'|title.2TOC
Note: While this plugin creates valid structure, the cross-references generated are not likely to be valid for the model you’re using (they don’t have the needed @href or other attributes). Because of this, you should probably not use the “xref” element or an element that expects certain attributes.

When each tocElem element is added to the list, the value “fmx-minitoc” is added to the @class attribute for that element. This is done so that subsequent processing will delete the list items before adding the items again. If your data model does not include a @class attribute, you’ll see this as an invalid attribute.

While the “TocContainer” element should be added to the source document during the authoring process, it is assumed that the mini TOC list is created as part of a publishing process and not generated in the source file. However, for some documents this may be fine.