Additional Topics, Part 1

This tutorial covers some of the topics not covered in the Basic Tutorial. The focus here is on the flexibility offered by the configuration files, especially the XML Template and IPC File. A basic understanding of the topics covered in the Basic Tutorial is assumed.

For a tutorial covering topics more targeted towards formatting through the DOCX Stub and plugin usage, see Additional Topics, Part 2.

Project

The project for this tutorial is Games. The discussion will only focus on the relevant portions of the relevant files, so readers are encouraged to download and extract the entire project before delving into the tutorial.

The document created in the project will contain a couple of trivial lists of board games just for illustration. The baseline version can be created using Games.ipc:

imprint Games.ipc

The output Games.docx will look something like this:

../_images/Games Output.png

The output of the Games example.

Overriding Keywords

The includes system keyword is not only for IIF Files. It can also be used to modify portions of the IPC File in a traceable and repeatable manner.

Using the fact that included files can not override defined keywords, we can define an IPC File snippet that just overrides the keywords that we want, and includes everything else from the original file:

Games0.ipc: Overriding the caption_counter_depth.
1
2
3
caption_counter_depth = 0

includes = ['Games.ipc']

The example show here is used to modify the caption_counter_depth setting. The same technique can be used equally well to modify other System Keywords as well as User-Defined Keywords. Such modification is useful for testing and to create documents that are closely related to each other in terms of most of their configuration.

Games0.ipc and its siblings Games2.ipc, Games3.ipc, and GamesNone.ipc are revisited in the section on Setting the Caption Counter Depth.

Making Lists

Lists are created by setting the list attribute of the <par> tags. List items are just regular paragraphs with some extra styling added on for bullets or numbering. A sample XML Template with list items looks like this:

Games.xml: The content and structure template, with list items emphasized.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
<imprint-template>
<par style="Title"><run>Sample of Board Games</run></par>
<toc>Contents</toc>
<par style="Heading 1">
    <run>
        Gridded Games
    </run>
</par>
<par>
    <run>
        The following images show the boards used by different types of gridded
        games. <figure-ref id="checkers"/> and <figure-ref id="chess"/> show
        checkers and chess, respectively. These are some of the most common
        games played on a static pre-made board. <figure-ref id="tic_tac_toe"/>
        and <figure-ref id="battleship"/> show tic-tac-toe and battleship
        boards. These are no less ubiquitous, but are generally played on
        hand-drawn boards.
    </run>
</par>
<par style="Heading 2">
    <run>
        Board Games
    </run>
</par>
<par><run>This section lists games played on pre-made boards.</run></par>
<par list="numbered"><run>Checkers</run></par>
<figure id="checkers" handler="imprint.handlers.figure.ImageFile" />
<par list="continued"><run>Chess</run></par>
<figure id="chess" handler="imprint.handlers.figure.ImageFile" />
<par style="Heading 2">
    <run>
        Paper Games
    </run>
</par>
<par>
    <run>
        This section lists games played on hand-drawn paper "boards".
        While pre-made board versions of these games exist, they are
        traditionally played on paper. For strictly board-type games, see
        <segment-ref title="Board Games"/>.
    </run>
</par>
<par list="num"><run style="Default Paragraph Font">Tic Tac Toe</run></par>
<table id="tic_tac_toe" handler="imprint.handlers.table.CSVFile" role="figure" />
<par list="cont" style="List Number"><run>Battleship</run></par>
<figure id="battleship" handler="imprint.handlers.figure.ImageFile" />
</imprint-template>

To start a new list, set the list attribute to either numbered or bulleted. Lines 26 and 43 in the example show how this is done. The full word (which is case-insensitive by the way) can be spelled out, or any prefix of it can be used, as in line 43.

To append elements to a list, set list to continued, as in lines 28 and 45. The list will be continued regardless of how many additional paragraphs or other elements are placed between the list items. For example, the figures on line 27, 29 and 46 and table on line 44 do not break up the numbering scheme of the two lists we created:

../_images/Games Output List1.png

The first list of games, with figures between list items.

../_images/Games Output List2.png

The second list of games, emphasizing the restarted numbering.

Additional information is available in the List Styling tutorial.

Adding References

The text Figure12 Reference Inline, Figure34 Reference Inline and Segment1 Reference Inline are dynamically generated reference names, which are automatically derived from the position of the figure or heading in the document outline.

The figure references are created by the <figure-ref> tags on lines 12, 14 and 15:

Games.xml, lines 10-18, emphasizing the <figure-ref>s.
10
11
12
13
14
15
16
17
18
    <run>
        The following images show the boards used by different types of gridded
        games. <figure-ref id="checkers"/> and <figure-ref id="chess"/> show
        checkers and chess, respectively. These are some of the most common
        games played on a static pre-made board. <figure-ref id="tic_tac_toe"/>
        and <figure-ref id="battleship"/> show tic-tac-toe and battleship
        boards. These are no less ubiquitous, but are generally played on
        hand-drawn boards.
    </run>

Each <figure-ref> identifies the figure it refers to by its id attribute. This is how most References are identified.

The text reference on line 40 is greated by a <segment-ref> tag, which points to paragraphs. Since paragraphs do not normally have an id attribute, they can be referenced by title instead:

Games.xml, lines 39-41, emphasizing the <segment-ref>.
39
40
41
        traditionally played on paper. For strictly board-type games, see
        <segment-ref title="Board Games"/>.
    </run>

The title of a <segment-ref> is the full text of the heading or other paragraph that is being pointed to, with all the extra spaces and line-breaks removed:

Games.xml, lines 20-24, emphasizing the heading title that the <segment-ref> refers to.
20
21
22
23
24
<par style="Heading 2">
    <run>
        Board Games
    </run>
</par>

Among builtin tags, <figure> and <par> can be referenced by <figure-ref> and <segment-ref>, respectively. We have not seen <table-ref> tags in the tutorial so far, which reference <table>s. <table-ref> works just like <figure-ref>, but with “Table” in the reference name instead of “Figure”.

Setting the Caption Counter Depth

The formatting of the figure number for <figure-ref> (and table number for <table-ref>) is set by the caption_counter_depth system keyword.

The default caption_counter_depth is 1, meaning that only the top-level heading is considered when counting and naming figures. If we were to change caption_counter_depth to say 2:

Games2.ipc: Overriding the caption_counter_depth, setting the depth to 2.
1
2
3
caption_counter_depth = 2

includes = ['Games.ipc']

We would see two elements in the heading level, and the figure counter would restart with every second-level heading instead of just the top level heading. The references that previously looked like Figure12 Reference Inline and Figure34 Reference Inline now look like Figure212 Reference Inline and Figure234 Reference Inline.

This snippet provides additional illustration for Adding Include Files. We can use a similar technique to remove the heading information from the references entirely, by setting caption_counter_depth to zero:

Games0.ipc: Overriding the caption_counter_depth, setting the depth to 0.
1
2
3
caption_counter_depth = 0

includes = ['Games.ipc']

These references show the figure counter for the whole document: Figure012 Reference Inline and Figure034 Reference Inline.

The cases shown here are well-behaved. In the case where caption_counter_depth is 2, all the references live in a heading at least two deep, when it is zero, there can’t be any problems at all. But if caption_counter_depth is set to a number that is greater than the outline depth of the heading containing the reference, the missing levels are ignored:

Games3.ipc: Overriding the caption_counter_depth, setting the depth to 3.
1
2
3
caption_counter_depth = 3

includes = ['Games.ipc']

In this case, the references will look identical to the ones with caption_counter_depth set to 2.

To turn off the the truncation of captions entirely, and just count references within each nested level of subheading independently, set caption_counter_depth to None:

GamesNone.ipc: Overriding the caption_counter_depth, unsetting the depth entirely.
1
2
3
caption_counter_depth = None

includes = ['Games.ipc']

The result will be identical with the case where caption_counter_depth is 2 for this particular example as well, but in general, the heading portion of the reference will not be constrained (similar to section headings). The counter will restart for any heading that is encountered in the document.

There are plenty of other pathalogical cases out there in terms of missing heading levels. The reader is assured that Imprint handles all of them consistently, and is left with the exercise of verifying that assertion for themselves. For a starting point, see the obscure PathologicalCases project.

Using Roles

Roles allow tags to impersonate each other as reference targets. The most common usage is to turn tables or equations into figures that can be referenced as “Figure 1.3-1”, rather than being treated as a table or equation.

Our sample template creates such a <table> to describe Tic-Tac-Toe:

Games.xml, lines 43-44, emphasizing the <table> tag.
43
44
<par list="num"><run style="Default Paragraph Font">Tic Tac Toe</run></par>
<table id="tic_tac_toe" handler="imprint.handlers.table.CSVFile" role="figure" />

The reference for this table can only be performed through a <figure-ref> tag, rather than the usual <table-ref>:

Games.xml, lines 13-15, emphasizing the unusual <figure-ref> tag.
13
14
15
        checkers and chess, respectively. These are some of the most common
        games played on a static pre-made board. <figure-ref id="tic_tac_toe"/>
        and <figure-ref id="battleship"/> show tic-tac-toe and battleship

Any tag, whether it is normally referenceable or not, can impersonate a role. For example, all it takes for a <latex> equation to become a figure is the addition of an attribute: role="figure". That being said, not all roles are suitable for every tag. For example, the PathologicalCases project has an example of a <table> that plays the role of a heading with role="par". This introduces the problem that <table> should not contain text, and so normally can not be referenced by <segment-ref>’s title attribute.