Basic Setup

An overview of the basic features of MiniToc.

Yes, the INI file configuration does seem a bit daunting, but it’s really not all that complicated once you understand what’s going on.

First, this only works with structured FrameMaker files. If you’re not working with structured FM files (XML-sourced or binary FM), this plugin won’t help you in any way. The intent of this plugin is to generate lists of links to sections within a “chapter” file. Rather than creating these links manually and needing to remember to add or delete them as the content changes, this plugin lets you define the “container” for the links, and define the instructions (templates) for how the links are created.

Once the containers are added to the source files and the instructions (in the INI file) are set up, you just run the Build MiniToc command and all of the links are created or updated. The INI file (minitoc.ini) must exist in the same folder as the book or file(s) being processed. On the MiniToc menu is the Edit Local INI File command which will edit (or create) the minitoc.ini file in the current file’s folder.

There are a number of ways to create these lists of links, hence the complexity of the options in the Configuration topic. The following example is one of the simpler ways to create a mini TOC.

The simplest minitoc.ini file will have two sections. The MiniToc section specifies the number of mini TOC groups to process. Each group represents a different type of list of links (mini TOCs). Not all groups will necessarily exist in the same document, but this is the list of all types of mini TOCs you’re creating for this project. If you’re only generating one type of mini TOC, there would be one more section named MiniToc-<groupname>, where <groupname> is the name of the mini TOC group. If we wanted to call the group “TOC1”, the second section would be named MiniToc-TOC1.

[MiniToc] 
Count=1 
1=TOC1 
 
[MiniToc-TOC1] 
TocContainer=ul/@outputclass='toc1' 
DeletePlaceholder=1 
ScopeRootElem=<topic 
XrefFmt=Title_and_Page 
XrefElem=fm-xref 
NumTemplates=1 
1=title.1|li/@outputclass='tocitem'

This INI example is almost identical to the default INI that’s created when you run the Edit Local INI File command with no INI in the current folder. Each property in the group section (MiniToc-TOC1) controls how the mini TOC is created.

The TocContainer property identifies the element to use as the container for the mini TOC to be created. This is the first thing that the process does, it scans the document for elements that match this criteria. This TocContainer says to match on all ul elements, that have an outputclass attribute value of “toc1”. If you had a custom model that uses a unique element for this container, such as minitoc, you could just specify “minitoc” as the value for TocContainer; the attribute value specification is optional.

The DeletePlaceholder property is needed when your container element has a required child element; which is the case when using a ul as the container element. In your source document would be the container element and the placeholder li element (text in the placeholder element is optional).



If you are using this type of structure, set DeletePlaceholder to “1”, otherwise set it to “0” or omit the property entirely.

The ScopeRootElem property defines the scope from which to scan for link targets for this group’s mini TOC. This can specify an element ID, a relative ancestor element, or a relative sibling element. Depending on your structural model and the intent of your mini TOC, any of these methods may be useful. The example above indicates to use the ancestor topic element (element name prefixed with the “<“ character, “<topic”). This means that for the mini TOC created in this container, the links will reference targets that are within the current topic.

The XrefFmt property specifies the Cross-ref format to use for the links in this mini TOC, and the XrefElem property specifies the element name to use for the cross-refs. Both of these values will depend on the formats and elements available in your template and structural model.

The NumTemplates property defines the number of link target matching templates for this group. Each mini TOC group can create one or more different type of links. For example, if you wanted to create a mini TOC that had links to H1 and H2 targets, you’d define two templates in the group, and thus the value of NumTemplates would be “2”. The example above uses just one template, so the value here is “1”.

For each template in a group, you’ll have a sequentially numbered property. This example just has one template, so there will be just a “1” property. The syntax for the templates can be complex, providing the ability to vary the construction of the links. The example uses a rather simple format:

title.1|li/@outputclass='tocitem'

This syntax is a vertical-bar-delimited string, with the first two parameters required. The first parameter is the target paragraph tag for the cross-ref (in this case “title.1”). This is basically like when you manually create a Cross-Reference and define the target based on paragraph tags. The second parameter defines the element container for the cross-ref element (defined by the XrefElem property). This is the element name and optionally and attribute and value. In this example we want the container element to be an li with the outputclass attribute set to “tocitem”.

When you run the Build MiniToc command on a FM file, the process scans for the container elements (TocContainers) and builds mini TOC lists as specified for each group.

If you’re using structured FM (binary) files, you can run this over and over as needed to update the link lists; each time you run it the old links are replaced with new ones. If you’re using XML, you would typically not run this on the source XML files, but on the aggregated FM files that are built from the XML files. This is definitely the case with DITA, and is likely the case for other models as well. Each model and workflow will require a slightly different use of this tool.

Because this tool can be automated, you’ll probably run it from some type of event-driven script. This might be run on document save, or it might be run as part of a publishing workflow. If you’re using DITA-FMx, you can set this up to run during the book-build process.