Ordered list styling

[Intelligent2013]

Source issue: https://github.com/metanorma/metanorma-iso/issues/1134#issuecomment-2006950974

Sometimes, the first level ordered list uses the arabic numbering in the original ISO documents. But metanorma-iso creates alphabetic lists.

• ordered list numbering - alphabetic vs. arabic:

  • rendered PDF:

  • production PDF (see page 6 https://github.com/metanorma/mn-samples-iso-private/blob/main/reference-docs/19152-1_2024.pdf):

From https://www.metanorma.org/author/topics/blocks/lists/#general-2:

Questions:

• is there an explicit indication that first level ordered lists should be 'alphabetic'?
• is there a way to redefine the current behavior 'globally' via the document attribute? (in principle, we can specify the type https://www.metanorma.org/author/topics/blocks/lists/#specification-of-list-type, but I don't sure that it's working at all)

The source adoc: https://github.com/metanorma/mn-samples-iso-private/tree/adoc_19152_1_2024

[opoudjis]

I am dealing with this issue right now for IEC in https://github.com/metanorma/metanorma-iec/issues/197

ISO/IEC DIR 2 as I recall it gives the ordering with alphabetic first as its prescription. But I will need to check how rigid that prescription is. The copy I just saw at IEC gives it as an illustration, but is not clear as to whether it is normative.

In this regard, we are hostage to the Word templates: recall that Word documents remain how draft documents are submitted to ISO and IEC. Word HTML makes it very difficult to change the style of ordered lists: it can only be done in CSS, and if the style template hasn't already defined a style for that numbering, a new style has to be defined on the fly. That style also needs to define the numbering of all its nested lists. https://github.com/metanorma/isodoc/issues/247 has been on hold for the past 4 years for that reason.

In fact, while Metanorma allows styles on lists, it explicitly removes them in postprocessing of Presentation XML, because of the difficulties they present with Word.

The IEC Word template does define two numbering styles, an alphabetic-first and an arabic-first. If the Word template for ISO does likewise, I can introduce some sort of styling toggle somewhere. If not, then it becomes a much bigger ask, though a global document default is feasible (I would propagate the variable into the preprocessing of the Word and HTML CSS.)

But I have not done anything for years on this, not only because it is difficult in Word HTML, but also because it is an semantically unmotivated inconsistency, of the kind that is easy to realise in Word, but which Metanorma by design makes hard and undesirable. The fact that one or two documents deviate from an alphabetic-first style is not to me sufficient reason to support it, especially if it is a stylistic quirk with no semantic motivation. These are self-indulgent whims that WYSIWYM is meant to do away with, not encourage...

I will look at the templates and latest ISO/IEC DIR 2 and get back to you.

[opoudjis]

Yes, ISO/IEC DIR 2 does not dictate that list numbering be alphabetic-first, but that's the only illustration it gives in https://www.iso.org/sites/directives/current/part2/index.xhtml#_idTextAnchor329

https://www.iso.org/ISO-house-style.html says that

The default order for a numbered list is a), b), c) for the first level; 1), 2), 3) for the second level; i), ii), iii) for the third level; and a), b), c) for the fourth level.

"Default" of course does not mean "mandated".

There is a split between Word templates.

• The draft template, which is what authors use to generate documents, provides distinct templates for bullet lists and dash lists. However it does not currently even support alphabetic lists: all lists are numbered in arabic, and authors are assumed to be using Word to format the numbers manually.
• What I'd forgotten is how the DIS template, used for publication-ready Word documents, does (stage 40 onwards). The DIS template does not use automated list numbering at all. It inserts numbers to lists as actual text; and we emulate it in our code. That is of course because ISO do not trust Word autonumbering (and I do not blame them). But it means that
  • We can implement any list numbering we want in ISO, in DIS mode.
  • We can completely ignore list numbering in draft template mode, because ISO does.

I think providing this level of flexibility is a mistake, but the DIS structure provides me a way of realising it, without being hostage to Word CSS inflexibility, and that is not the case in general for Word lists.

So I am going to remove the constraints on list numbering which I have put on ISO; I will retain them for ISO, IEC, JIS, as flavours inheriting from ISO, because they do not insert labels manually on lists, so they are still subject to the constraints of Word CSS.

I will implement flexible labelling of lists in ISO Word using the DIS template. I will not implement it in ISO Word using the draft template, because the draft template uses the CSS that forced this constraint to begin with. If I ever do implement a workaround for https://github.com/metanorma/isodoc/issues/247, I will revisit that, but I do not believe that drafts are as important to render nicely.

[Intelligent2013]

@opoudjis thank you!