How to Add Footnotes and Endnotes

The proper means to do footnotes has proven rather more complex than I expected – and there are surprisingly few resources to help with the issue. As such, I figured that I should write about the means that I have found to add them in DoX CMS. This article explains how you can implement both footnotes and endnotes in the system.

Footnotes

Positioning footnotes at the bottom of the page involves stylesheets that refer to special rules: standard CSS does not include rules that allow you to position content accordingly. You must also add correctly positioned references to them as part of the main content. Fortunately, PrinceXML contains features to do both. In DoX CMS, you can manage this when you use DocRaptor as a compiler.

Please note that footnotes only work with DocRaptor as a result. Other compilers require that you use endnotes. DocRaptor can only be used alongside compatible stylesheets but its use can be enabled in any copy of DoX CMS.

This method must be implemented using elements that can be used inside other pieces of text. In practice, it only works with phrase elements (ph). Footnotes elements (fn) do not work with this method. You must instead use them for endnotes.

Adding footnotes involves three steps:

1. Add a ph element in the position where you will add the reference and write the contents of the footnote inside this element.
2. Use an element class which was added for this purpose such as ‘FNPrince’ on the ph element.
3. Add the required changes to the relevant stylesheets (details below).

The position of the ph element determines where the reference to that footnote is added. This is why you must be able to embed it in other content. Write all the contents of the footnote inside this element.

Because the ph element in question must be identifiable as a footnote, it requires a corresponding element class. First, add a suitable element class to the system and name it appropriately to convey its proper use to all users. Remember to also write a short description to help everyone. When you add ph elements to content to be used as footnotes, apply this element class to them.

Turning such elements into footnotes requires specific additions to the stylesheet that you will use. Because footnotes only work in PDF publications compiled with DocRaptor, it is a good idea to also add rules for processing content with this element class to other stylesheets.

Footnotes and Stylesheets

The main rule related to footnotes is ‘float: footnote’ which is compatible only with DocRaptor in DoX CMS. Its effects are described below alongside other details related to this method. Special thanks to Andreas Jung and his article on using stylesheets to add footnotes for these instructions.

The selector for footnotes must be linked to the correct element class with the inclusion of the expression [doxelementclass=”name”] wherein ‘name’ is the identifier for said element class. Add the rule ‘float: footnote’ to this selector. This rule moves the contents of the specified ph element to the bottom of the page, adds a reference to it in its original position, and adds a corresponding identifier before its contents. Each of these details can be controlled separately.

Since footnotes only work in stylesheets that are compatible with DocRaptor and made for PDF publications, they should still be accounted for in other stylesheets as well. This keeps the rest of the content reusable. The simplest solution to this is to add the rule ‘display: none’ to the element class in other stylesheets. This leaves such content out of publications that cannot use it in the same manner.

Footnotes also let you style all the other associated parts. There is a list of the associated selectors below alongside clarifications on the functions of each. In the case of element classes, ‘name’ must be replaced with the identifier for the appropriate element class.

1. @page {@footnote {}}: PrinceXML lets you add styles related to specific positions on each page. This selector is used to style the position related to footnote content.
2. [doxelementclass= “name”]::footnote-call {}: This selector lets you style the reference that is added in the original position of the ph element. The rule ‘content: counter ()’ lets you set the used symbols if the counter has been defined by then. Additional information on defining counters is available here.
3. [doxelementclass=”princefn”]::footnote-marker {}: This selector lets you style the (number) identifier before the contents of the footnote.

Endnotes

Currently, endnotes require additional development but they have not been a priority compared to the tasks based on requests by users. They are still available, though, under specific conditions and using detailed specifications in the stylesheet.

Endnotes are based on fn elements. They can either be included in the conclusions of topics or in their own topics that are set at the conclusions of main sections or the document itself. References to these elements involve internal links based on xref elements that reference their positions.

The challenges here involve a suitable look for the references and the identifiers before the contents. Because references to fn elements use the variable default-series for the time being, you are only allowed to reference them alongside (1) tables, (2) figures (fig), (3) sections, and (4) other topics. Otherwise, the associated counter will account both for endnotes and any other such elements that you reference.

Additionally, the general format for internal references must be formulated to be compatible with endnotes. Endnotes need not involve only ordinal values but they are the simplest implementation in this respect. In this case, the reference format in the Settings menu should be set to ‘{{Series}} {{Number}}’.

Adding endnotes involves six steps.

1. Change the reference format to match the intended format for references to these elements in the Settings menu.
2. Add one or more fn elements in the proper topic and write the contents of the endnote inside it.
3. Add ID values to all the fn elements that you added.
4. Add an xref element that references one of the fn elements in the position where it must be referenced.
5. Apply a superscript effect to the xref element (or apply an appropriate element class).
6. Add the required changes to the relevant stylesheets (details below).

Instructions for styling references and endnotes are provided below.

Endnotes and Stylesheets

The primary challenge for endnotes is making the associated number identifiers suitable for the task. In practice, this requires abbreviating them by removing all parts other than the number identifiers. It is also possible to position the title of the target element before the element rather than above it which suits an endnote better.

The recommended additions to the stylesheet are shown below and then explained further down.

.anchor-title:not(.dita-table *):not(.dita-fig *) {
	float: left !important;
        vertical-align: super !important;
        font-size: smaller !important;
        padding-right: 10px !important;
}

.dita-fn {
        margin-top: -15px !important;
}

.anchor-title:not(.dita-table *):not(.dita-fig *) span:first-child {
    display: none !important;
}

.Superscript .reference-title span:first-child {
	display: none !important;
}

The first section adjusts the titles of endnotes to lie before them and not above them. It also styles the text itself to look more suitable. You can specify the details of the latter freely. In this instance, the text is smaller and there is a margin of ten pixels between it and the main content. The most relevant rule here is ‘float: left’, though, and it is what repositions the content.

Even though endnotes are div elements with the class ‘.dita-fn’, the titles that references to them add are not inside these elements themselves. Selectors cannot target preceding elements which is why they have been specified by eliminating alternatives instead. This identifier can be used to style said content, though. The second section opts to move said content upwards to push it in line with its title.

The third section hides the part of the reference titles for endnotes that corresponds to the value of the default-series variable. This leaves only the other parts of the reference format visible. Thus, if the reference format is ‘{{Series}} {{Number}}’, only the ordinal value of the reference will show.

The fourth section hides the part of the reference that corresponds to the value of the default-series variable. It thus applies the same change to the references as the previous section applies to the titles. The provided specifications affect all internal links contained by superscript. Alternatively, ‘.Superscript’ can be replaced with reference to an element class ‘[doxelementclass=”name”]’, where you replace ‘name’ with its identifier. This alternative is recommended if other internal links are expected to be used in parts that use superscript. It is also clearer to users. This element class itself can also be styled to use superscript.

As with footnotes, the same specifications can also be used to hide these elements in publications that do not support them. In this instance, there are fewer such situations, though. Thus, you can also add tas to the links to control their visibility in different documents. Currently, links without targets do not show in publications. However, we intend to rectify this soon by adding some form of default anchor to them to help review content.