Support custom table of contents (TOC)

[ronaldtse]

https://github.com/metanorma/bipm-si-brochure/issues/132

The TOC in the BIPM SI Brochure for Appendix 1 is a fake TOC encoded as a normal table. In order to apply identical styling as the main TOC we should encode this as a real TOC as well.

MN should provide a mechanism for encoding a TOC.

[opoudjis]

Well, all it would do would be:

• A table of hyperlinks in HTML
• A Word ToC in Word
• And... I have no idea what in PDF

The ToC directive in Metanorma itself could only be what the header is in Word: a listing of XPaths to include in the given ToC instance. Each rendering format would then have its own specific realisation.

[ronaldtse]

The TOC should be encoded in Metanorma XML, as the first thing. STS has such a primitive.

[Intelligent2013]

* And... I have no idea what in PDF

In PDF (both bookmarks and ToC pages) - similar to HTML, i.e. just hyperlinks to clause's/annex's/figure's/table's titles. Each xslt has own implementation to display it (which title's depth should be displayed, styles for 1st depth title, styles for 2nd depth title, etc.) . I.e. it's not automatically feature as in Word.

[opoudjis]

Encoding the ToC as STS has it, as an explicit listing of hard coded titles and links, is a retrograde and foolish thing to do, and will introduce unacceptable fragility.

The BIPM ToC for Appendx 1 as it stands consists of completely ad hoc truncated titles, which are very clearly being done by hand. If BIPM want an automated table of contents, they can't also require it to be manually populated. That is the kind of retrograde manual formatting Metanorma is supposed to be eliminating, and the current hand-generated table is all the formatting that approach deserves.

The only sensible thing to do for an automated ToC, similar to what Word does, is to add an XPath for the titles or captions to be included in the ToC, which then will be expanded in Presentation XML.

So:

toc:[//annex[@id = 'annex1']/clause/title]

In the general case:

toc:["xpath1":n1,"xpath2":n2,"xpath3":n3,...]

Where xpath is the path to a title or caption to be indexed, and n is the depth to indent that caption in; if n is omitted, it is assumed to be 1. So:

toc:["//annex[@id = 'annex1']/clause/title","//annex[@id = 'annex1']/clause/clause/title":2,"//annex[@id = 'annex1']/clause/clause/clause/title":3]

[opoudjis]

The ToC will be rendered in Metanorma XML as an unordered list of xrefs: that is all a ToC is. It will be contained in a new <toc> tag, and that will be used to produce differential rendering in different target formats.

[opoudjis]

Implemented in Standoc, will need to now implement rendering in HTML and Word.

ToC sample looks like:

            <toc>
              <ul id='_'>
                <li>
                  <xref target='clause1A'>Clause 1A</xref>
                </li>
                <li>
                  <ul id='_'>
                    <li>
                      <xref target='clause1Aa'>Clause 1Aa</xref>
                    </li>
                    <li>
                      <xref target='clause1Ab'>Clause 1Ab</xref>
                    </li>
                  </ul>
                </li>
                <li>
                  <xref target='clause1B'>Clause 1B</xref>
                </li>
                <li>
                  <ul id='_'>
                    <li>
                      <xref target='clause1Ba'>Clause 1Ba</xref>
                    </li>
                  </ul>
                </li>
              </ul>
            </toc>

[opoudjis]

I'm declining to implement this with a distinct Word rendering at this time. Word's native ToC model involves class names instead of XPaths, and has no notion of restricting ToC to a subset of a document, as is being required here. Word ToCs of varying scope will continue to have document-wide scope, and to be catered with as part of the preset content of document introductions.

[opoudjis]

What I have implemented is a generic solution for ToC. It may not be what BIPM have asked for, but it will be needed anyway. Will put on hold until we receive feedback from BIPM at https://github.com/metanorma/bipm-si-brochure/issues/132

[ronaldtse]

Will put on hold until we receive feedback from BIPM

Clarified by BIPM here: https://github.com/metanorma/bipm-si-brochure/issues/132#issuecomment-890490716

[opoudjis]

In light of feedback from BIPM:

• I will implement a toc-title, to stand as an alternative to the title, and to be used for ToCs.
• It will be entered as an attribute to the clause, but it will contain AsciiDoc markup
• It will be temporarily added to the Semantic XML as an element, so that it can be extracted for ToC generation, but it will be deleted once the ToC is generated

[opoudjis]

And because ToC is under development, I will not document this yet in metanorma.org

[opoudjis]

Will also need to extract the title anchors and add them in Presentation XML, so that the title autonumbering is reflected in ToC.

[opoudjis]

Attribute titles are not going to cut it with formatting within the title, nor quotes. I'm going to make the variant titles be special paragraphs, marked up with role [.variant-title,type=...].

Typed clause titles will be removed in Presentation XML. They will be tagged as variant-title, so that they will not get accidentally picked up later.

[opoudjis]

toc macro mentions title instances; e.g. toc:["//clause[@id = 'clause1'\\]/clause/title","//clause[@id = 'clause1'\\]/clause/clause/title:2"]

I'm going to code that, wherever the XPath ends in title, I'll find and use variant-title[@type = 'toc'] instead if present.