Roll stylesheets into Presentation XML

[opoudjis]

This is a task I am undertaking with no little resentment.

To date, Presentation XML has been dirty. It contains some pre-rendered components, and some components where rendering is done subsequently, by HTML and PDF processing. It was developed as a refactoring of the initial HTML code, fitfully, and there are bits that have not been completely refactored.

At no stage was there much concern for the Presentation XML being consistent or formally valid.

metanorma/metanorma-ogc#472 has unearthed the fact that:

• PDF and HTML are independently adding the same delimiters in the same contexts to block labels; e.g. NOTE + ":<tab/> + content
• Or, PDF is adding a delimiter, and HTML is failing to, because nobody bothered to tell me to do it, the implementation task went only to @Intelligent2013
  • That is, I had implemented NOTE + "<tab/> + content, and @Intelligent2013 had independently updated that to NOTE + ":<tab/> + content, without me being informed.
  • This is a code management (and indeed project management) fail: there is almost never a circumstance where PDF and HTML should be rendering delimiters differently. (And despite what Ronald's impression is, the intended state of Colon missing from NOTE when rendered as HTML metanorma-ogc#472 is to bring HTML in alignment with PDF)
  • The solution to this state of affairs is to have PDF and HTML generation draw from a common source of truth in the Presentation XML, as to what the delimiter should be.
    • And, very much as an edge case (and I am not convinced it is actually happening at all), to allow PDF and HTML to have different delimiters.

The solution to date has been:

• Presentation XML block label contains colon, dash, period, or whatever other punctuation.
  • Almost always these are empty (following ISO).
• HTML adds tab between label and content
• PDF adds punctuation and tab between label and content (because I was not made aware of the punctuation needs.)

With biblio-tag, which has recently been implemented from scratch, the solution is:

• Presentation XML biblio-tag contains comma, period, or whatever other punctuation, and space or tab.
• HTML and PDF just juxtapose the biblio-tag to the reference, without further intermediates.

That's far cleaner and consistent, and I intended to do this for block labels instead.

Instead, Ronald has raised the concern that Presentation XML differentiate content from rendering still, and not fully flatten the code for rendering. He wants the predictable interposition of delimiters to be handled not by XML, but by stylesheet, which can be shared between PDF and HTML, or specific to one format:

• Semantic XML --(isodoc)-> Presentation XML --(stylesheet)--> Presentation XML 1 --(XSL:FO, isodoc)-> HTML, DOC, PDF

So Presentation XML has labels with no delimiters or punctuation in them: the label content is still "clean". The delimiters and punctuation is introduced by the stylesheet.

I think this is a pedantic waste of time. When my workload is increasing, Metanorma uptake is increasing, and there continues to be no additional development resource available to Metanorma, to even raise this as a prospect is not only insane, but irresponsible. And far from being easier to maintain, the additional stylesheets pose a nightmarish burden.

And accordingly, I have implemented this for OGC notes in metanorma/metanorma-ogc#472, with a preprocessing XSLT inserted into Presentation XML.

To generalise this across Metanorma is a major project, and it shall be delayed: it will take up the better part of a week, and needs to be coordinated between @Intelligent2013 and myself.

• Create a separate PR for all of metanorma and for the XSLT stylesheets. There is the risk this will take longer than 1 release cycle.
• Extend the preprocessing XSLT solution from notes to all labelled blocks in OGC, and to biblio-tag
• Overrule all HTML code in OGC for generating blocks, with replacement code that omits tabs (since they will now be provided by the XSLT)
• Have @Intelligent2013 remove all routines in the OGC XSLT that insert tabs and punctuation after labels in blocks.
  • The biblio-tag code is just concatenation, and can be left alone for both HTML and PDF
• Move that OGC override code for HTML generation to isodoc root
• Move the preprocessing XSLT to isodoc
• Implement inheritance of the preprocessing XSLT from isodoc into OGC
  • The inheritance is not going to look like XSLT; it will likely be some sort of meta-XSLT in YAML, with the delimiters also specific locally. I also am not going to put up with *[local-name() = '...'] XPaths in any YAML I handle: I'm going to write a local function to translate XPaths into that.
  • In the case of the config-only gems, the meta-XSLT will be further streamlined: only the delimiter will be exposed as a local config parameter
• For each flavour of Metanorma
  • (And Ronald, THIS IS WHY THERE SHALL NEVER BE MORE THAN 15 FLAVOURS OF METANORMA. Because I routinely have to do coding changes across all of Metanorma, that cannot just be inherited, or indeed, that implement inheritance.)
  • I inherit the preprocessing XSLT from isodoc via the meta-XSLT YAML, with any localisation of delimiters
  • @Intelligent2013 removes the delimiter code from his XSLT
  • I inherit the block processing code without tabs from isodoc
• Once this is ALL done on both sides, we merge the PRs and release

Iterating through each flavour of Metanorma, to implement the OGC stack, might be delegated to someone else; but by that stage, the substantive work has been done, so there likely won't be a point.

This at the moment is going to Medium Priority. Which means it will never get done. If @ronaldtse wants this done, he will need to allocate it a relative priority.

So long as it is not done, OTOH, the delimiters of blocks will continue to be inconsistent between PDF and HTML, and I will not implement a reconciliation between the two in code. That is to perpetuate malpractice. An insane solution involving inherited XSLT is better than implementing delimiters independently in code.