BIPM SI brochure (French): review

[anermina]

---

Issues:

1. Stem expressions are not generated at all. The first example is shown in the following captures, where alpha and gamma are missing.

Original:

Generated:

Source ADOC:
(Rayons x et stem:[gamma], électrons), Section II (Mesure des radionucléides), Section III (Mesures neutroniques), Section IV (Étalons d’énergie stem:[alpha])

2. Cross-referencing should be fixed. I recall BIPM asked for adding the corresponding pages in cross-references, which is probably the reason why we have them in some places where they are not included in the original document.

However, I can see the word voir is showing in more than one place, due to markup + automatic addition of page numbers. Moreover, BIPM used keyword section in some places, chapitre in the others, while sometimes they didn't use any keyword. So my question is whether we should keep voir and/or section/ chapitre in the markup, or we agreed with BIPM on some standard which will be applied in all cases.

Original:

Generated:

From ADOC source:
_obligatoires_ (voir <<chapter5>>).

Original:

Generated:

From ADOC source:
(voir <<cls-236>>)

When the same ADOC syntax was used in the Introduction, page number was not included. I have already changed markup here because I thought it was wrong before seeing the other cross-references. Please let me know if I should revert the changes.

Original:

Generated:

I changed markup here to:
dans le texte «&nbsp;<<le_bipm_et_la_cdm>>&nbsp;» (page <<le_bipm_et_la_cdm,pagenumber%>>).

Another example where page number is not included in neither original nor generated PDF is shown below.

Original:

Generated:

From source ADOC:
(voir <<scls541>> pour une explication de la notation utilisée ici).

Moreover, should "voir" be italicized or not? Example from Appendix 1 of the original document is below. As far as I could see, "voir" was always italicized in Appendix 1, while that was not the rule in the rest of the brochure.

Original:

Generated:

3. Heading row of the ToC table in Appendix 1 is repeating at each page, probably because there was a blank line between it and the next table row. I removed that blank row. However, we still need word "page" to appear at the beginning of each new page.

Original:

Generated:

Note: I've already changed capital P to small p in "page" and made it boldfaced.

---

Questions/possible issues

1. Should we have the first line in the generated ToC?

Original:

Generated:

2. Do we need to show subsections for annexes in ToC? Do we need to add a dot after annex number?

Original:

Generated:

3. This was probably agreed with BIPM, but in order to double-check: should this example be a part of the main text, or it should be shown on the right margin, as in the original (ignore the fact that math expressions are not shown in generated PDF):

Original:

Generated:

4. Is there some reason why yellow-highlighted part was excluded?

Original:

Generated:

5. Titles are always boldfaced in our case. However, BIPM uses some kind of referencing in the titles, which applies the style which is generally used for papers of that type. I'm just noticing this as a difference, but don't know if that is a problem for BIPM team.

Original:

Generated:

6. Are we supposed to be using Greek letters for second level of items list?

Original:

Generated:

Note: Markup fixes are applied in #48.

[manuelfuenmayor]

1. Stem expressions are not generated at all. The first example is shown in the following captures, where alpha and gamma are missing.

Confirmed. I'm getting this result on generated PDF.

Moreover, should "voir" be italicized or not? Example from Appendix 1 of the original document is below. As far as I could see, "voir" was always italicized in Appendix 1, while that was not the rule in the rest of the brochure.

I agree, in my view, it should be italicized.

3. This was probably agreed with BIPM, but in order to double-check: should this example be a part of the main text, or it should be shown on the right margin, as in the original (ignore the fact that math expressions are not shown in generated PDF):

This happens because the text is enclosed in an example block. I believe we would have to change it to a note block in order to place it at the right margin. But we need confirmation for that. @ronaldtse?

6. Are we supposed to be using Greek letters for second level of items list?

In my view, this is clearly a bug.

[Intelligent2013]

In Acrobat Reader there is an error after a few seconds after I opened PDF:

PDF is corrupted. @opoudjis could you attach a log of mn2pdf processing, please?

[ronaldtse]

Ping @opoudjis

[opoudjis]

OK:

The Stem rendering issue has been resolved, although I'm not happy with how we ended up resolving it—by having to upgrade Java. We are including STIX in fontist, and that may be a smoother resolution of this issue. I have regenerated the PDF, and @Intelligent2013 confirms he is not getting the errors in opening the PDF.

I am attaching the latest compilation of the PDF.

collection.pdf

[opoudjis]

"2." The intention is that chapître refers to clauses (e.g. Chapître 5), and section to subclauses (e.g. section 2.3.6). If that isn't happening, that's a bug on my side.

[anermina]

"1" is solved.

"2" can be split into several issues and questions:

2.1 Cross-referencing keywords.
chapître should refer to clauses, and section to subclauses. (I confirm it is currently not happening.)

2.2 Adding page numbers in cross-references.
In which cases should the page number be added as a part of the cross-reference? I didn't manage to find a rule in neither original nor generated PDF.

Note: BIPM requested adding page number for "Introduction" section, where it wasn't generated and where I don't see how it can be automatically generated to produce the desired output (due to usage of « » for the title). So I changed markup there to:
dans le texte «&nbsp;<<le_bipm_et_la_cdm>>&nbsp;» (page <<le_bipm_et_la_cdm,pagenumber%>>).

2.3 Source of the word voir.
Should the word voir before the cross-reference be added automatically, or via markup?

2.4 Duplication of the word voir when page numbers are added.
In case page number is added, we currently have repetition of the word voir, as in the following example:
voir 2.3.6, voir p. 30

2.5 Italicizing the word voir.
Should it be italicized? As far as I could see, voir was always italicized in Appendix 1 of the original document, while that was not the rule in the rest of the brochure.

"3" Conclusion remains the same - after changing .adoc source, we lost the word page at the beginning of each new page. For some reason, the first row is not boldfaced now.

The rest of the initially written issues remain the same.

[ronaldtse]

The Stem rendering issue has been resolved, although I'm not happy with how we ended up resolving it—by having to upgrade Java

No one uses Java 8 anymore...

[opoudjis]

No one uses Java 8 anymore...

Given your aspirations to have all this running in an app, this is still your problem. People who are not developers in Java have the default OS version of Java lying around, and OS versions of programming languages are always antiquated...

[ronaldtse]

In fact, we already stopped supporting Mojave a while ago as the single-binary version doesn't support it. Keeping one's computer up to date using system utilities is the responsibility of the user. As application developers we are not expected to keep the execution runtimes updated.

[opoudjis]

2.1 Cross-referencing keywords.
chapître should refer to clauses, and section to subclauses. (I confirm it is currently not happening.)

Was fixed in #40, but I had a typo in the French YAML: fixed now. Thank you @anermina for insisting. :)

The remainder of 2 are PDF issues, but the following are my opinions. I defer to @Intelligent2013 on what is actually achievable:

2.2. Consistency is our default position and our selling point, and SDOs are rarely consistent because they rarely do the level of proofreading that ISO do, let alone that an automated system like ours does. No surprise there is no consistency in the source PDF. The preferable course would be to add page numbers universally. I would not at all be surprised if page numbers only appear for references to Appendix 1, because of BIPM's spectacularly ill-advised "decision" not to insert any section numbering in the appendix. If it does turn out that that is the only reason why page numbers have been used, bludgeoning section numbering into the appendix would be far preferable to perpetuating bad practice.

2.3. voir/see should be inserted automatically, especially because it is an artefact of PDF that is suffixed to what appears in the HTML: there is nowhere we can put the "voir" in source text, when that text must not appear in HTML at all. But you are right that 2.4 requires an exception to be made. With some feeling of revulsion at the kludginess of it all, I am going to introduce markup in xrefs, to signal to the PDF that any voir/see is to be suppressed.

2.5. No opinion. Arbitrary capricious idiosyncrasies in rendering in general should be extirpated with no mercy.

[opoudjis]

And as for your Issues, separately numbered:

1. Should we have the first line in the generated ToC?

No opinion.

2. Do we need to show subsections for annexes in ToC?

I believe @ronaldtse has already extracted the concession from BIPM that we don't: this would have been an idiosyncratic limit to the ToC.

2. Do we need to add a dot after annex number?

Yes, and that needs to be done inline in PDF.

3. This was probably agreed with BIPM, but in order to double-check: should this example be a part of the main text, or it should be shown on the right margin, as in the original

No opinion, I defer to @Intelligent2013

4. Is there some reason why yellow-highlighted part was excluded?

The text was there in sections-a1-fr/a1-decisions.adoc, which is presumably the older document that was chopped up into the various constituent resolutions. You'd have to ask @manuel489, but "see below" tends to be bad news for auto-formatted documents in general, because it's vague, and you don't know where below the referent is going to end up.

5. Titles are always boldfaced in our case. However, BIPM uses some kind of referencing in the titles, which applies the style which is generally used for papers of that type. I'm just noticing this as a difference, but don't know if that is a problem for BIPM team.

It will be unpleasant to fix this, won't do so unless they ask for it.

6. Are we supposed to be using Greek letters for second level of items list?

Specific to PDF, HTML has normal a).

[opoudjis]

Any remaining issues here in my opinion do not involve me, so I am putting this issue on my on-hold list.

[Intelligent2013]

2.2 Adding page numbers in cross-references.
Note: BIPM requested adding page number for "Introduction" section, where it wasn't generated and where I don't see how it can be automatically generated to produce the desired output (due to usage of « » for the title). So I changed markup there to:
dans le texte « <<le_bipm_et_la_cdm>> » (page <<le_bipm_et_la_cdm,pagenumber%>>).

It should be workable solution. The similar markup I've processed yet for ToC in Appendix:

<xref target="cgpm24th2011r1" pagenumber="true">Appendix 1.38.1</xref>

But, because page numbers in ToC are bold, then please add bold markup into adoc for Appendix 1 Toc (00-toc.adoc) for both languages.

2.5 Italicizing the word voir.
Should it be italicized? As far as I could see, voir was always italicized in Appendix 1 of the original document, while that was not the rule in the rest of the brochure.

I've fixed xslt for:

• if voir/see in main text - it isn't italized,
• if voir/see in side notes - it is italized.

1. Should we have the first line in the generated ToC?

I think no, because this section before ToC, removed in xslt.

2. Do we need to add a dot after annex number?

Yes. xslt fixed.

3. This was probably agreed with BIPM, but in order to double-check: should this example be a part of the main text, or it should be shown on the right margin, as in the original

In the original PDF there isn't common approach for examples.
Page 143:

Page 150:

There are a few solutions:

• markup second example as note, then it'll show on the right margin (changes in adoc)
• displays both examples in main text (no need changes)
• display both examples on the right margin (xslt need to change)
• markup both examples as example, but for second add some indication in markup (for show this example on the right margin) (rb need to change).

[anermina]

But you are right that 2.4 requires an exception to be made. With some feeling of revulsion at the kludginess of it all, I am going to introduce markup in xrefs, to signal to the PDF that any voir/see is to be suppressed.

In accordance to metanorma/metanorma-bipm#75 (comment), I added %nosee to the cross-references where duplication of "voir/see" could be seen in the latest generated PDF.

But, because page numbers in ToC are bold, then please add bold markup into adoc for Appendix 1 Toc (00-toc.adoc) for both languages.

Done.

In the original PDF there isn't common approach for examples.

Lets leave these examples as a part of the main text then. In case BIPM says they would prefer them to be shown on the right margin, I'll mark the second example as a note.

Is there some reason why yellow-highlighted part was excluded?
The text was there in sections-a1-fr/a1-decisions.adoc, which is presumably the older document that was chopped up into the various constituent resolutions. You'd have to ask @manuel489, but "see below" tends to be bad news for auto-formatted documents in general, because it's vague, and you don't know where below the referent is going to end up.

@manuel489, could you please check? It seems to me this part of the text was intentionally modified, but it would be good to have a confirmation.

[manuelfuenmayor]

@manuel489, could you please check? It seems to me this part of the text was intentionally modified, but it would be good to have a confirmation.

@anermina, yes, I intentionally removed that piece of text for the same reason that @opoudjis provides above. Basically, "voir ci-dessous" translates "see below", and it's kind of a vague reference. And, at that time, I wasn't sure if such referenced notes were going to be placed in such a way that they were actually "below" (e.g. what if a page-break happens just after the reference calling?). BUT, looking at the generated PDF, they seem to be in the correct position. So I guess we can rollback that change after all?

[manuelfuenmayor]

I have put the text back.

[anermina]

Corrections are made. Closing.