Presentation XML caption markup

[opoudjis]

From #610

• Autonumbering will be handled through new attributes, so that the number of an asset (@autonum), and its label (label), are differentiated from its caption (fmt-name, fmt-title; these will incorporate the name and title from the Semantic XML)
• The label is what is used to cross-reference the asset by default, and it typically is the name of the asset class (e.g. Table) followed by its number. It should not be generated by the renderer on the fly, given flavour-specific formatting requirements and i18n complications (e.g. Japanese inserting connectives). However, it is available for reuse in the renderer (e.g. in Tables of Contents), and it can be overridden.
• Delimiters inserted into the caption will also be tagged explicitly, as span class="autonum-delimiter", so that they can be identified and overridden if needed.

Semantic XML:

<table id="A">
<name>Rice yields per capita</name>

Current Presentation XML:

<table id="A">
<name>Table 3.1:&#xa0;Rice yields per capita</name>

Future Presentation XML:

<table id="A">
<name id="N">Rice yields per capita</name>
<autonum id="A0">3.1</autonum>
<label id="A1">Table <semx element="autonum" target="A0">3.1</semx></label>
<fmt-name source="N">
<semx element="label" target="A1">Table <semx element="autonum" target="A0">3.1</semx></semx>
<span class="autonum-delimiter">:&#xa0;</span>
<semx element="name" target="A2">Rice yields per capita</semx></fmt-name>

Every single solitary instance of title and name will be shadowed or replaced by fmt-title and fmt-name, and renderers need to process that, and ignore title, name, autonum, label.

[opoudjis]

This is growing, and I'm scared of where this is going to end up:

• In spans within fmt-name, I am differentiating the following classes (all namespaced with fmt-, as they are specific to Presentation XML:
  • fmt-autonum-delim (punctuation put after the autonum, e.g. "3 ." in clause numbers)
  • dmt-caption-delim (punctuation between the autonum and the name (caption) of the asset—tabs and dashes)
    • fmt-caption-delim is added only if there is a caption: "3.1. <tab/> Introduction". fmt-autonum-delim is added regardless: "3.1 ." They are doing different things.
    • fmt-autonum-delim and fmt-caption-delim often coocur in clause titles
  • fmt-label-delim (punctuation at the end of the name/title, after any user supplied content; used to delimit name/title from content if rendered in the same paragraph: full stop, dash, colon in notes)

So:

EXAMPLE 3 – Spinoza: This is an example

This is:

<example>
<name>Spinoza</name>
<p>
<fmt-name><strong>
EXAMPLE <semx element='autonum'>3</semx> 
<span class="fmt-caption-delim">–</span> 
<semx element='name'>Spinoza</semx>
<span class='fmt-label-delim'>:</span>
</strong></fmt-name> This is an example</p>
</example>

• I am differentiating xref-label, the label to be used for cross-references, from caption-label, the label used on the asset itself. They can be different: a subclause can be titled "3.1" (caption-label), but cross-referenced as "Clause 3.1" (xref-label)
  • There is the complication of containers in cross-references: some cross-references are sensitive to the containers they are contained in (typically clauses). So a note in the same clause is referenced as "Note 1", but a note in another clause is referenced as "Clause 3, Note 1". Frankly, I'd rather not have to deal with that as well, but if I must, it is a variant of xref-label.
  • I would have preferred to make xref-label and caption-label attributes, but they can be styled, e.g. in BSI
  • On the other hand, autonum is only ever text conceptually—any styling of the number is to be found in caption-label, xref-label, fmt-name and fmt-title. But autonum is still referenced from caption-label, xref-label, and we need to know where the source number is, so I am keeping it a separate element
  • When xrefs is autopopulated with text, we need to know what in the text is what: <xref target="A">Table 1</xref> should be telling us that the 1 is the table autonum. So with some reluctance, I'm going to make it:

<xref target="A">
  <span class='fmt-element-name'>Table</span> <semx element='autonum'>1</semx>
</xref>

And that means I'm also adding the span class fmt-element-name.

I won't know the autonum value at the time I am calcluating the cross-references, and I am not convinced of the value of cross-referencing autonum when it is recoverable contextually. I may revisit that decision.

I will post samples soon, but I'm still working through the implications.

[opoudjis]

I will have to deal with multiple numbers in container xrefs after all: I am currently generating:

      <xref target="N1">
         <span class="fmt-element-name">Clause</span>
         <semx element="autonum">2.1</semx>,
         <span class="fmt-element-name">Example</span>
         <semx element="autonum">1</semx>
      </xref>

Clause 2.1, Example 1. If we are going to allow this to be reformatted dynamically, I have to be able to tell the Presentation XML which autonum references the clause, and which the example.

I am going to make autonum be an attribute of the element after all, and make semx[@element = 'autonum'] point to the element ID after all; keeping and tracking a separate id for autonum is pointless. So:

<clause id="A" autonum="2.1">
...
<example id="N1" autonum="1">...</example>
...
</clause>

...

      <xref target="N1">
         <span class="fmt-element-name">Clause</span>
         <semx element="autonum" source="A">2.1</semx>,
         <span class="fmt-element-name">Example</span>
         <semx element="autonum" source="note1">1</semx>
      </xref>

[opoudjis]

fmt-caption-label is not adding value as a separate element, it is replicating the first couple of children of fmt-name. Instead, I will wrap the autonum + autonum-delimiter components at the start of fmt-name in span[@class = 'fmt-caption-label']:

from

                     <fmt-name>
                        <span class="fmt-element-name">Figure</span>
                        <semx element="autonum" source="_">1</semx>
                        <span class="fmt-caption-delim"> — </span>
                        <semx element="name" source="_">Label</semx>
                        <span class="fmt-label-delim"/>
                     </fmt-name>
                     <fmt-caption-label id="_">
                        <span class="fmt-element-name">Figure</span>
                        <semx element="autonum" source="_">1</semx>
                     </fmt-caption-label>
                     <fmt-xref-label>
                        <span class="fmt-element-name">Figure</span>
                        <semx element="autonum" source="_">1</semx>
                     </fmt-xref-label>

to

                     <fmt-name>
                         <span class="fmt-caption-label">
                        <span class="fmt-element-name">Figure</span>
                        <semx element="autonum" source="_">1</semx>
                        </span>
                        <span class="fmt-caption-delim"> — </span>
                        <semx element="name" source="_">Label</semx>
                        <span class="fmt-label-delim"/>
                     </fmt-name>
                      <fmt-xref-label>
                        <span class="fmt-element-name">Figure</span>
                        <semx element="autonum" source="_">1</semx>
                     </fmt-xref-label>

[opoudjis]

Unnumbered figures and sourcecode still need to have "Figure/Sourcecode" in their caption: no idea why I had blocked that...

[opoudjis]

Ah. I do see. We want to avoid captioning in such cases:

<example>
  ...
    <figure>
      <name>Imago</name>
    </figure>
  ...
</example>

If example/figure/name is supplied, we need to transform it to fmt-name (else it will be ignored), but we don't want to prefix it with Figure – . If example/figure/name is not supplied, we don't want to supply fmt-name.

[opoudjis]

Added name processing in Presentation XML for dl, ul, ol, to ensure that any name instances are copied to fmt-name

[opoudjis]

Needed to deal with autonum XML added to xref and contents contents for punctuation localisation: punctuation localisation was naive about preceding and following context in different XML tags. Need to also generalise CJK extending titles to cope with titles now containing XML markup.

[opoudjis]

Obligation parentheses for annex titles appear on their own line: I need to localise them separately, so that CJK does not spuriously use surrounding Roman text as context from previous lines. This needs to be a general caution: punctuation localisation needs to be one line at a time.

[opoudjis]

isodoc done. Next, mn-requirements, which impacts isodoc integration testing.

[opoudjis]

Both the monospace identifier in references to other Modspec requierements, and the full crossreference, were being linked to the requirement; this was mangling cross-references after the refactor. The intent was to hyperlink only the monospace identifier, so that is now behaviour:

<tr>
<th>Included in</th>
<td>
   <xref target="A1">
      Permissions class 1:
      <tt>/2</tt>
   </xref>
</td>
</tr>

becomes

<tr>
<th>Included in</th>
<td>
        <span class="fmt-element-name">Permissions class</span>
        <semx element="autonum" source="A1">1</semx>
        <tt>
           <xref style="id" target="A1">/2</xref>
        </tt>
     </td>
  </tr>

The xref was being inserted around the <tt>/2</tt> from the beginning), and was being stripped in isodoc.

[opoudjis]

Bug fix: if we have multiple abstracts or introductions in the preface, which we move to the right location in the preface in Presentation XML, ensure they are in the right order, not reverse: Abstract1 Abstract2 was ending up as Abstract2 Abstract1. (This has only happened in reality in Plateau, which has two abstracts.)

[opoudjis]

metanorma-plateau done

[opoudjis]

Will test against all local samples directories, and then close this ticket.

[opoudjis]

Testing the local samples directories with the updated PDF stylesheets locally sounds too difficult, TBH, so I'm going to defer testing to Monday's release. I'm going to do a final round of rspec testing, and then move to other tickets for the remainder of the week.

[opoudjis]

Need to intervene in bilingual document markup in metanorma gem.

[opoudjis]

Not done, this has disrupted metanorma collections.

Will also need to document the schema updates for Presentation XML.

[opoudjis]

Prefatory and Final content in collections needs to be compiled to Presentation XML not Semantic XML, as it is merged in with Presentation XML for the collection documents.

[opoudjis]

We want it to be Presentation XML, so we can have fmt-title instead of title.

... But we do not actually want any clause numbering or asset numbering in the Prefatory and Final content! So I will intervene in the compilation to make all clauses (at least) unnumbered.