Publish "Annex of Appendix of Brochure" documents

[opoudjis]

Follow on from https://github.com/metanorma/metanorma-bipm/issues/98, which is a follow on from https://github.com/metanorma/bipm-si-brochure/issues/71

Not only are we publishing Appendixes to the BIPM Brochure separately, we are now also publishing Annexes to Appendixes to the BIPM Brochure separately.

This means that you will need not only //bibdata/title[@type = 'appendix'] and //bibdata/ext/structuredidentifier/appendix, but also //bibdata/title[@type = 'annex'] and //bibdata/ext/structuredidentifier/annexid. (Note: annexid, not annex, to avoid Xpath ambiguity.)

You will need to ask @ronaldtse where he wants those displayed on the document.

[Intelligent2013]

To do:

1. hierarchy/order to show titles on cover page in PDF (title/@type):

   • main/cover
   • appendix (number from structuredidentifier/appendix)
     • annex (number from structuredidentifier/annexid)
     • part (number from structuredidentifier/part)
       • subpart (number from structuredidentifier/subpart)

2. Adaptive font-size depends on text length.

[Intelligent2013]

@ronaldtse Before each pair of titles we display number with type-of-title prefix, first for French, second for English. Example for Appendix:

What is title prefix should we show for 'Annex' (i,e. 'Annex of Appendix') titles? If we'll show:

Annexe N (in French) Annex N (in English)

then in this case there is a confusion between titles (Appendix vs. Annex) - Annexe in both cases for French.

[Intelligent2013]

@ronaldtse regarding your notices:

The SI Brochure contains Appendix 2. Appendix 2 is the "Mise en pratique". Appendix 2 contains multiple "part documents". Each document is encoded to have a "part number" and a "part title". A "part" inside Appendix 2 can contain Annexes (and the Annexes are published separately). Each Annex can have an "annex ID" and "annex title".

What we need to do on the cover:

1. The "part number" and "part title" is not displayed on the cover.
2. The "annex id" and "annex title" is not displayed on the cover.
3. When the "appendix name" is long, the cover page overflows...

I've updated bipm xslt to

• adaptive font-size depends of length of titles (but I would like to try improve the algorithm...)
• part number and part title display now,
• To display annex id and annex title, you need to add title with type annex, I've added title/@type=annex processing.
• To display Appendix 2 title "Mise en pratique" you need to add title with type appendix.

So my manually updated source xml looks as:

<title language="en" format="text/plain" type="main">The International System of Units</title>
<title language="en" format="text/plain" type="appendix">Mise en pratique</title>
<title language="en" format="text/plain" type="annex">Recommended values of standard frequencies for applications including the practical realization of the metre and secondary representations of the second</title>
<title language="en" format="text/plain" type="part">Rubidium 87 Atom (<stem type="MathML"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>f</mi><mo>≈</mo><mn>6.835</mn><mtext> </mtext><mstyle mathvariant="normal"><mrow><mi>G</mi><mi>H</mi><mi>z</mi></mrow></mstyle></math></stem>)</title>
<title language="fr" format="text/plain" type="main">Le système international d’unités</title>
<title language="fr" format="text/plain" type="appendix">Mise en pratique</title>
<title language="fr" format="text/plain" type="annex">Valeurs recommandées des fréquences étalons destinées à la mise en pratique de la définition du mètre et aux représentations secondaires de la seconde</title>
<title language="fr" format="text/plain" type="part">Rubidium 87 Atom (<stem type="MathML"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>f</mi><mo>≈</mo><mn>6.835</mn><mtext> </mtext><mstyle mathvariant="normal"><mrow><mi>G</mi><mi>H</mi><mi>z</mi></mrow></mstyle></math></stem>)</title>
...
<ext>
...
<part>2.29</part>
<appendix>2</appendix>
<annexid>3</annexid>
</structuredidentifier>
</ext>

and resulted PDF cover page:

Resulted PDF: mep-wgfs-cm4_4-Rb_6-835GHz.presentation.pdf

[ronaldtse]

@Intelligent2013 the current layout is acceptable, will consult BIPM on the French of "Annex" vs "Appendix". Thanks!

[opoudjis]

From memory, they have flipped them around: appendice for annex, annexe for appendix

[opoudjis]

No, I am still on holiday :p I think the xml i am generating is at odds with some of this, but we will find out in a couple of days

[ronaldtse]

@Intelligent2013 1 thing to fix here: "May , 2016" has a space in between.

I have consulted BIPM on the difference between Annex/Appendix in French/English:

We are aware of the somewhat inconsistent nomenclature of the documents related to the SI brochure. The mises en pratiques would probably be better called ‘annexes’ to the SI brochure. The reason that they are called ‘appendices’ is that historically they were much less comprehensive and not stand-alone documents as they are now. The term has been kept for consistency with the past editions.

This situation should be considered when deciding on the structure of the next edition of the SI brochure and its related documents. It would not be a good solution to change the nomenclature of the already published documents now, since it might lead to confusion.

Therefore, although it is not fully satisfactory, we should for the moment stick to the current nomenclature and the XML files should reproduce it.

i.e. BIPM will adapt a new nomenclature for the current "Appendices" in the new edition, meaning that it will be: Level 1 — Brochure Level 2 — Annex / Annexe Level 3 — Appendix / Appendice

For now, we will use: Level 1 — Brochure Level 2 — Annexe 2 (en: Appendix 2) Level 3 — Annexe 1 (en: Annex X)

So it will be "Annexe of Annexe" in French for now.

[ronaldtse]

Can we make this a configurable option @opoudjis ? e.g. :annex-name-fr: Annexe {{ number }}, or just ":bipm-old-hierarchy:"?

[opoudjis]

Pending clarification: BIPM seem to be applying document autonomy, not hierarchical position, as their naming criterion. If so, this becomes a doctype issue.

[ronaldtse]

I have requested further clarification from BIPM:

I’d like to confirm the roles of “Appendix” and “Annex” (in English as representation of the concepts) being the “types of major sections”.

Should we use a hierarchical system in determining the type of a major section? Or is the type of major section dependent on the amount of content inside it?

Option 1: Using a defined hierarchical system, such as that used by ISO/IEC and other SDOs like ITU. In ISO they use Level 1 (major section: “Document") > Level 2 (“Annex") > Level 3 (“Appendix").

This system uses a strict hierarchy:

• only a Document is allowed to have an Annex
• only an Annex is allowed to have an Appendix

Option 2: Using a system where the amount of content (defined by the author) determines the type of major section:

• Any document can contain both Annexes and Appendices
• An Annex can contain an Appendix

This will raise additional questions such as:

• Can an Appendix can contain an Annex?
• Can an Annex contain an Annex?
• Can an Appendix contain an Appendix?

[Intelligent2013]

@ronaldtse

1 thing to fix here: "May , 2016" has a space in between.

Fixed. Comma was related to day, but date is month+year only.

For now, we will use: Level 1 — Brochure Level 2 — Annexe 2 (en: Appendix 2) Level 3 — Annexe 1 (en: Annex X)

So it will be "Annexe of Annexe" in French for now.

So no need to change xslt at this moment. Thank you.

[ronaldtse]

Thanks!

[opoudjis]

Update on the Options query needed, @ronaldtse

[ronaldtse]

@opoudjis we are still waiting for a discussion to happen in the BIPM, no updates on this yet. Completing the main SI Brochure first will bring that discussion forward...

[ronaldtse]

BIPM lead for machine readable Janet Miles has suggested that this change may be done in the next edition (10) of the official SI Brochure. So this is not going to be done right now, but perhaps a few months down the line.