Footnotes Related to Tables in PDF Documents

Post here questions and problems related to editing and publishing DITA content.
pjporter88
Posts: 4
Joined: Sat Oct 16, 2021 8:36 pm

Footnotes Related to Tables in PDF Documents

Post by pjporter88 »

Hello,

I have been reviewing how to style footnotes in PDF output using DITA to HTML5 with CSS. It only seems to cover "typical" cases of footnotes that get collected and placed at the bottom of the page, where a separator line could be added.

We have a use case where we often have footnotes inside the cells of tables and want the footnotes placed in small font immediately underneath the table instead of at the bottom of the page, so that the footnotes are "connected" to the table. Alternatively, perhaps the footnotes could go inside an html footer element for that table.? I know there is no footer for tables in DITA though.

Is this possible? If so, how might that be done?

Thank you!
Pat
julien_lacour
Posts: 306
Joined: Wed Oct 16, 2019 3:47 pm

Re: Footnotes Related to Tables in PDF Documents

Post by julien_lacour »

Hello Pat,

If you want to move table footnotes follow these instructions:
  1. Create a publishing template file (.opt) in a new folder from your project. Then create an xslt folder inside it.
  2. In the newly created folder, create an XSLT style-sheet (for example merged2mergedExtension.xsl) with the following content:

    Code: Select all

        <?xml version="1.0" encoding="UTF-8"?>
        <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
          xmlns:xs="http://www.w3.org/2001/XMLSchema"
          exclude-result-prefixes="xs"
          version="2.0">
    
          <!-- Match only top level tables (i.e tables that are not nested in other tables),
            that have footnotes. -->
          <xsl:template match="
              *[contains(@class, 'topic/table')]
              [not(ancestor::*[contains(@class, 'topic/table')])]
              [//*[contains(@class, 'topic/fn')]]">
            <xsl:next-match>
              <xsl:with-param name="top-level-table" select="." tunnel="yes"/>
            </xsl:next-match>
    
            <!-- Create a list with all the footnotes from the current table. -->
            <ol class="- topic/ol " outputclass="table-fn-container">
              <xsl:for-each select=".//*[contains(@class, 'topic/fn')]">
                <li class="- topic/li " id="{generate-id(.)}" outputclass="table-fn">
                  <xsl:apply-templates select="node()"/>
                </li>
              </xsl:for-each>
            </ol>
          </xsl:template>
    
          <!-- Match the footnotes in table entries, replace them with a link. -->
          <xsl:template match="*[contains(@class, 'topic/entry')]//*[contains(@class, 'topic/fn')]">
            <xsl:param name="top-level-table" tunnel="yes"/>
            <!-- Determine the footnote number. -->
            <xsl:variable name="fn-number" select="
                index-of($top-level-table//*[contains(@class, 'topic/fn')], .)"/>
            <xref type="fn" class="- topic/xref " href="#{generate-id(.)}"
              outputclass="table-fn-call">
              <xsl:value-of select="$fn-number"/>
            </xref>
          </xsl:template>
    
        </xsl:stylesheet>
    
  3. Open the .opt file and set the XSLT style-sheet created in the previous step with the com.oxygenxml.pdf.css.xsl.merged2html5 XSLT extension point:

    Code: Select all

        <publishing-template>
          ...
          <pdf>
            ...        
            <xslt>
              <extension
                id="com.oxygenxml.pdf.css.xsl.merged2merged"
                file="xslt/merged2mergedExtension.xsl"/>
            </xslt>
    
  4. Create a css folder in the publishing template directory. In this directory, save a custom CSS file with rules that style the glossary structure. For example:

    Code: Select all

        /* Customize footnote calls, inside the table. */
        *[outputclass ~= 'table-fn-call'] {
          color: black;
          text-decoration: none;
          font-size: smaller;
          vertical-align: super;
          line-height: none;
        }
    
        /* Hide the "on page .." text that follows xrefs. */
        *[outputclass ~= 'table-fn-call']:after {
          display: none;
        }
    
        /* Customize the list containing all the table footnotes. */
        *[outputclass ~= 'table-fn-container'] {
          border-top: 1pt solid black;
        }
    
        /* Customize footnotes display, below the table. */
        *[outputclass ~= 'table-fn'] {
          font-size: 1em;
        }
        *[outputclass ~= 'table-fn']::marker {
          font-size: 1em;
        }
    
  5. Open the template descriptor file associated with your publishing template (the .opt file) and reference your custom CSS file in the resources element:

    Code: Select all

        <publishing-template>
          ...
          <pdf>
            ...                
            <resources>            
              <css file="css/custom.css"/>
            </resources> 
    
  6. Edit the DITA Map PDF - based on HTML5 & CSS transformation scenario.
  7. In the Templates tab, click the Choose Custom Publishing Template link and select your template.
  8. Click OK to save the changes and run the transformation scenario.
Feel free to change the values from the CSS in order to obtain the desired output.

Regards,
Julien
pjporter88
Posts: 4
Joined: Sat Oct 16, 2021 8:36 pm

Re: Footnotes Related to Tables in PDF Documents

Post by pjporter88 »

Thank you Julien!
Can't wait to implement this.
Very much appreciated!
Pat
patjporter
Posts: 53
Joined: Sat May 22, 2021 6:04 pm

Re: Footnotes Related to Tables in PDF Documents

Post by patjporter »

Hi Julien,
When I implemented the code above, it worked great...but I am getting this format on the footnote markers:
image.png
image.png (18.36 KiB) Viewed 478 times
I tried adding to the custom css that you gave me above the following:

Code: Select all

    *[outputclass ~= 'table-fn']::marker {      
    font-size: 1em;
    content: "(" counter(footnote) ")";
    }
But this caused my transform to crash. Here what is in the styles.css:

Code: Select all

/*footnotes-style-parentheses*/
@media print {
  *[class~="topic/fn"]::footnote-call,
  *[class~="topic/fn"]::footnote-marker {
    content: "(" counter(footnote) ")";
  }
}
Maybe the two are conflicting with each other, or maybe the change that I made in custom.css is incorrect?

Can you help me understand how to make the two have the same format, basically like this: (1)(4)

Thank you!
Pat
patjporter
Posts: 53
Joined: Sat May 22, 2021 6:04 pm

Re: Footnotes Related to Tables in PDF Documents

Post by patjporter »

Also please notice that footnotes that are second, third, etc. instances of a footnote in a table are structured as <xref> to the original <fn> element to avoid duplication with a type="fn" but they are showing up formatted as hyperlinks because they are xrefs. Is there a way to prevent <xref type="fn"> from displaying as a hyperlink in blue with the underline?

Code: Select all

<entry> <p>Production - Pre CoA<fn id="fn-1">DAY / VMC is required for flight outside
              the normal operational envelope, i.e., airstarts, electrical checks, flight control
              shutoff checks, cabin pressure low checks, stalls, spoiler control, engine handling on
              non-FADEC, engines, operation above Vmo / Mmo, and alternate gear extension. </fn>
              </p> <p>Completion - Pre-Approach Validations<xref
              href="Chapter-209Runway---Weather-Requirements.dita#ID-000012f8/fn-1" type="fn"/></p> </entry>
Thank you!
Pat
patjporter
Posts: 53
Joined: Sat May 22, 2021 6:04 pm

Re: Footnotes Related to Tables in PDF Documents

Post by patjporter »

Apologies for continuing to add to this post...but I discovered a problem. I structured my footnotes according to this reference:
https://www.oxygenxml.com/dita/1.3/spec ... se/fn.html
But, when I add an id attribute to the first instance of a fn, it does not put the footnote call in the table entry:

Code: Select all

<row>
            <entry>Production - Pre CoA<fn id="001">DAY / VMC is required for flight outside the
              normal operational envelope, i.e., airstarts, electrical checks, flight control
              shutoff checks, cabin pressure low checks, stalls, spoiler control, engine handling on
              non-FADEC, engines, operation above Vmo / Mmo, and alternate gear
              extension.</fn></entry>
            <entry>1000/3</entry>
            <entry> 1000/3 or IFR Cir<fn>Use of IFR Cir Min requires prior validation of a properly
              functioning aircraft instrument approach system.</fn><fn>If the forecast arrival
              weather is less than 1000/3, the proper functioning of the aircraft instruments should
              be verified after takeoff. If they function correctly, then the flight can continue
              using IFR Cir Minimums.</fn></entry>
            <entry>Required</entry>
          </row>
image.png
image.png (11.24 KiB) Viewed 448 times
When I deleted the @id from the first fn element, the number 1 published. When I added back it, it did not.
Is this by chance a known issue and is there a workaround, like adding an outputclass that the html will recognize as a class?
Thank you,
Pat
chrispitude
Posts: 585
Joined: Thu May 02, 2019 2:32 pm

Re: Footnotes Related to Tables in PDF Documents

Post by chrispitude »

Hi Pat,

From Darwin Information Typing Architecture (DITA) Version 1.3 > 3.2.2.16 <fn>:
A footnote that specifies an @id attribute is a use-by-reference footnote. Upon output, it does not appear anywhere unless it has been referenced using an <xref> with the @type attribute set to "fn".
This definitely takes some getting used to. It confuses our writers too.

I need to try this footnotes-under-table technique - this is something our writers have asked about!
patjporter
Posts: 53
Joined: Sat May 22, 2021 6:04 pm

Re: Footnotes Related to Tables in PDF Documents

Post by patjporter »

Interesting…so you have to write the fn, then you have to reference it…seems redundant, but I understand,
We actually use a different extend-script based process through FrameMaker for our flight manuals written in DITA that publishes the use-by reference.
Thanks for clearing that up!
Pat
patjporter
Posts: 53
Joined: Sat May 22, 2021 6:04 pm

Re: Footnotes Related to Tables in PDF Documents

Post by patjporter »

Would you be able to help with the formatting questions?
Thanks!
Pat
patjporter
Posts: 53
Joined: Sat May 22, 2021 6:04 pm

Re: Footnotes Related to Tables in PDF Documents

Post by patjporter »

So I updated my footnotes to add cross-references for the <fn> elements that had id attributes set on them. When I ran it using the default transform I got this (a single instance):
image.png
image.png (8.84 KiB) Viewed 417 times
When I ran it with the code that Julien provided above to place the footnotes under the table rather than at the bottom of the page, I got this...they are duplicated:
image.png
image.png (85.62 KiB) Viewed 417 times
What I was aiming for is two things:
(a) Footnotes directly under the table (Julien's code does this).
(b) Formatted like all the other footnotes (not hyperlinks and surrounded by parentheses ( ) in both the callouts and the footnotes under the table. (I am getting first instance non-hyperlink, all xrefs are hyperlinks, and no parentheses).
Perhaps Julien may have the opportunity to assist and modify the code he provided above...I am having too much difficulty trying to figure it out.
Thank you!
Pat
julien_lacour
Posts: 306
Joined: Wed Oct 16, 2019 3:47 pm

Re: Footnotes Related to Tables in PDF Documents

Post by julien_lacour »

Hi Pat,

For the formatting part, you should try the following CSS:

Code: Select all

/* Customize footnote calls, inside the table. */
*[outputclass ~= 'table-fn-call'] {
  color: black;
  text-decoration: none;
  font-size: smaller;
  vertical-align: super;
  line-height: none;
}

/* Hide the "on page .." text that follows xrefs. */
*[outputclass ~= 'table-fn-call']:after {
  display: none;
}

/* Customize the list containing all the table footnotes. */
*[outputclass ~= 'table-fn-container'] {
  border-top: 1pt solid black;
  counter-reset: table-footnote;
}

/* Customize footnotes display, below the table. */
*[outputclass ~= 'table-fn'] {
  font-size: 1em;
  counter-increment: table-footnote;
}
*[outputclass ~= 'table-fn']::marker {
  font-size: 1em;
  content: "(" counter(table-footnote) ")";
}
Regards,
Julien
patjporter
Posts: 53
Joined: Sat May 22, 2021 6:04 pm

Re: Footnotes Related to Tables in PDF Documents

Post by patjporter »

Hi Julien, thank you. In the XSLT you provided, the footnote calls in tables are being formatted as hyperlinks with the text decoration (blue, underline). Will this css entry override that?
When I deleted that part of the XSLT you provided (the part that converted the footnote calls to links), I now get the footnotes both under the table and at the bottom of the page, so I broke something.
Tried to fix on thing, broke another.
Pat
Dan
Posts: 500
Joined: Mon Feb 03, 2003 10:56 am

Re: Footnotes Related to Tables in PDF Documents

Post by Dan »

Hello Pat,

I changed the stylesheet to:
1. Preserve the original ID on the LI generated for a footnote, so that the XREFs that point to the footnote still work.
2. Remove the footnotes with ID once they are copied as LIs in OLs. This avoids getting them in the footer of the page.
3. Replace footnotes without ID with XREFs that point to the generated LIs.

So this is the stylesheet - the second template is critical, please do not remove it.

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xs="http://www.w3.org/2001/XMLSchema" exclude-result-prefixes="xs" version="2.0">

  <!--
    Match only top level tables (i.e tables that are not nested in other tables), that have footnotes.
  -->
  <xsl:template match="
      *[contains(@class, 'topic/table')]
      [not(ancestor::*[contains(@class, 'topic/table')])]
      [//*[contains(@class, 'topic/fn')]]">
    <xsl:next-match>
      <xsl:with-param name="top-level-table" select="." tunnel="yes"/>
    </xsl:next-match>
    <!-- Create a list with all the footnotes from the current table. -->
    <ol class="- topic/ol " outputclass="table-fn-container">
      <xsl:for-each select=".//*[contains(@class, 'topic/fn')]">
        <!-- Try to preserve the footnote ID, if available, so that the xrefs will have a target. -->
        <li class="- topic/li " id="{if(@id) then @id else generate-id(.)}" outputclass="table-fn">
          <xsl:apply-templates select="node()"/>
        </li>
      </xsl:for-each>
    </ol>
  </xsl:template>

  <!-- 
    The footnotes having an ID must be ignored, they are accessible only 
    through existing xrefs (xrefs added already in the merged.xml file).
    
    The above template already made a copy of these footnotes in the OL element
    so is not a problem if we do not generate markup for them in the cell. -->
  <xsl:template match="*[contains(@class, 'topic/entry')]//*[contains(@class, 'topic/fn')][@id]"/>

  <!-- 
    These are footnotes without ID. They are also copied in the OL element, 
    but have no xrefs pointing to them (because have no ID), so we generate xrefs. 
  -->
  <xsl:template match="*[contains(@class, 'topic/entry')]//*[contains(@class, 'topic/fn')][not(@id)]">
    <xsl:param name="top-level-table" tunnel="yes"/>

    <!-- Determine the footnote number as the index from the table, in normal document order. -->
    <xsl:variable name="fn-number" select="
        index-of($top-level-table//*[contains(@class, 'topic/fn')], .)"/>

    <xref type="fn" class="- topic/xref " href="#{generate-id(.)}" outputclass="table-fn-call">
      <!-- Generate an extra <sup>, identical to what DITA-OT generates for other xrefs. -->
      <sup class="+ topic/ph hi-d/sup ">
        <xsl:value-of select="$fn-number"/>
      </sup>
    </xref>
  </xsl:template>
</xsl:stylesheet>
Now, in the CSS, I changed the selectors that added "(" and ")" to the footnote calls (xrefs now) to match the pattern of the structure generated by DITA-OT for xrefs that point to footnotes.
Here is the CSS, the part referring to the footnotes:

Code: Select all

/* Customize footnote calls, inside the table. */
*[outputclass ~= 'table-fn-call'] {
  color: black;
  text-decoration: none;
  font-size: smaller;
  vertical-align: super;
  line-height: none;
}

/* Hide the "on page .." text that follows xrefs. */
*[outputclass ~= 'table-fn-call']:after {
  display: none;
}

/* Customize the list containing all the table footnotes. */
*[outputclass ~= 'table-fn-container'] {
  border-top: 1pt solid black;
  counter-reset: table-footnote;
}

/* Customize footnotes display, below the table. */
*[outputclass ~= 'table-fn'] {
  font-size: 8pt;
  counter-increment: table-footnote;
}
*[outputclass ~= 'table-fn']::marker {
  font-size: 8pt;
  content: "(" counter(table-footnote) ")";
}

/* Customize xrefs pointing to footnotes with IDs. */
*[class ~= "topic/table"] *[class ~= "topic/xref"][type = 'fn'] {
  color: unset;
  text-decoration: none;
}
*[class ~= "topic/table"] *[class ~= "topic/xref"][type = 'fn']:after {
  content: none;
}
*[class ~= "topic/table"] *[class ~= "topic/xref"][type = 'fn'] *[class ~= "hi-d/sup"]:before {
  content: "(";
}
*[class ~= "topic/table"] *[class ~= "topic/xref"][type = 'fn'] *[class ~= "hi-d/sup"]:after {
  content: ")";
}
IMPORTANT: Please test this customization on various example, to make sure there are no missing footnotes and that the links are working!

Many regards,
Dan
Post Reply