PDF: New document type: Addendum (historic, 1997 and prior)

opoudjis commented 1 month ago

Follow-on from https://github.com/metanorma/metanorma-iso/issues/1150

New document type, Addendum, behaves similarly to Amendment in its bibdata, but unlike Amendment, is a complete document.

This actually already renders OK in PDF, except that I've placed the addendum title in title[@type = 'title-add']

Dummy sample attached.

a1.presentation.xml.zip

Intelligent2013 commented 1 month ago

@opoudjis the addendum cover page has the sentence:

I can construct it by XSLT on-fly, but I need the additional data - formerly publication docidentifier. Could you add it?

Intelligent2013 commented 1 month ago

@opoudjis also, the 1st page contains the sentences:

How to encode it?

opoudjis commented 1 month ago

Ugh. The first will be easier than the second, and I think the second needs to be ad hoc text treated as metadata somehow.

opoudjis commented 1 month ago

DAD, I have to assume, is a former notation for ADD; I am inferring that, because Russian uses Доп. for both DAD and ADD. Googling confirms that; for example, https://dl.acm.org/doi/pdf/10.1145/74674.74679 p. 101 uses DAD to reference ISO addenda, in 1988.

So we have the adhoccery (which I'd rather we didn't support) of a current and a former equivalent notation of the same identifier: ISO 2533:1975/ADD 1:1985 is not an update of ISO 2533/DAD 1, they both are referring to the same thing.

We do have

`:docidentifier-additional:`::
This attribute provides additional primary identifiers for the document, to be used alongside
the native identifier generated from `docnumber` or `docidentifier` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.2].
It is intended for copublished standards with multiple primary identifiers. 
The list of identifiers is comma-delimited, and is specified as TYPE:VALUE; e.g.
`:docidentifier-additional: IDF:IDF 21, RFC:RFC 97`

But that is not semantically the same thing.

I will introduce (with no little disgust) :docidentifier-obsolete: for this, and it will be processed along with ISBN and docidentifier-additional, as extraneous literal strings.

I'm surprised to hear you can generate the associated text: you have everything you need in the i18n?

Intelligent2013 commented 1 month ago

DAD, I have to assume, is a former notation for ADD; I am inferring that, because Russian uses Доп. for both DAD and ADD. Googling confirms that; for example, https://dl.acm.org/doi/pdf/10.1145/74674.74679 p. 101 uses DAD to reference ISO addenda, in 1988.

I assume that DAD means 'Draft ADdendum'. Addendum is Дополнение (ДОП) in Russian, but I don't see the difference between these two identifiers: and don't figure out why the second one mentioned as 'formerly'. May be it's just mistake.

I'm surprised to hear you can generate the associated text: you have everything you need in the i18n?

I mean just hard-coded the associated text into XSLT. Sure, it's does not follow the accepted practice. Initially this task was my, so I thought it was my problem. But if you include it into i18n, it will be more correctly.

opoudjis commented 1 month ago

We have the unfortunate situation here that addenda are supposed to update original documents, and in fact the construction of addenda identifiers assumes that it does, with the document attribute :updates: ---

--- so ISO 2533:1975/ADD 1:1985 updates ISO 2533:1975, and that is encoded expressly as :updates: ISO 2533:1975, that's how we know what to put the "ADD 1:1985" onto when we put the identifier together

--- but we can argue that ISO 2533:1975/ADD 1:1985 also updates its draft ISO 2533:1975/DAD 1. And we don't want to conflate the two relations.

From https://www.relaton.org/model/relations/:

X draftOf Y: X is unpublished, Y may or may not be published
- Inverse Y hasDraft X
X editionOf Y: X is published, Y is a work or a translation, arrangement, abridgement, annotation; Y is not an edition
X updates Y: X is an edition (is published), Y is an edition of the same work
- corrects (no impact on meaning), amends (minor change), revises (major change)
X obsoletes Y: X invalidates Y; X and Y need not be editions of the same work
X derivedFrom Y: X and Y are distinct works, but the content of X derives from Y
- includes adaptedFrom, adoptedFrom (identical, equivalent, nonequivalent), hasSuccessor

In these definitions, which I am not proposing to change, and which are taken from ISO 690,

ISO 123:2003 updates ISO 123:2001
ISO 123/ADD 1 updates ISO 123:2003

"Updates" is valid, because both are published

ISO 123:2003 hasDraft ISO/DIS 123:2002
ISO 123/ADD 1 hasDraft ISO/DAD 1

We can't say they are updates, because updates are defined as being updates of published expressions. And intuitively that makes sense: drafts are realised in publications, they are not updated as publications

ISO 123/ADD 1 updates ISO 123: yes, so long as we consider ISO 123:2000 and ISO 123:2010 editions of the same work, we must also consider ISO 123:2000/ADD 1:2001 and ISO 123:2000/AMD 1:2005 editions of the same work. The difference is that ISO 123:2000/ADD 1:2001 and ISO 123:2000/AMD 1:2005 amend ISO 123:2000, and ISO 123:2010 revises ISO 123:2000

So:

ISO 123:2003 updates (=> revises) ISO 123:2001 ISO 123:2000/ADD 1 updates (=> amends) ISO 123:2000 ISO 123:2003 hasDraft ISO/DIS 123:2002 ISO 123:2000/ADD 1 hasDraft ISO 123:2000/DAD

And we can add hasDraft to updates as a relation between identifiers in bibdata, as we have comparable identifiers elsewhere (part-of, translated-from, adopted-from, annotation-of), in the relation_relations() method.

So to capture the previous draft identifier, we need only add has-draft to relation_relations() for ISO.

opoudjis commented 1 month ago

And, as a result of all this, I can provide you @Intelligent2013 with i18n text for how to describe the relation of a document to its has-draft predecessor if specified:

... but TBH, I'm challenged about how to fit all those bits together. I guess we can come up with the text of

Technical Committee ISO/TC 20, Aircraft and space vehicles

But we haven't hitherto internationalised it.

But do you actually have access to a rendering of "Addendum 1 to Internatiational Standard ISO 2533-1975"? This sounds like a long format pubid-iso, and a horrible legacy format at that...

opoudjis commented 1 month ago

The "this addendum is based on" is a piece of document history metadata, but expressed as a block, not just a document attribute line. We don't have document history in ISO, though we do in other flavours. I think we should treat this as a prefatory clause of type document-history, rather than as an attempt at machine readable data in a table --- that clause clearly is not machine readable.

OK, this is messy, but I know how to do it now...

Intelligent2013 commented 1 month ago

But we haven't hitherto internationalised it.

I think the document author is responsible for the TC translation. For instance, in https://github.com/metanorma/mn-samples-iso/blob/main/sources/international-standard/rice-2023/document-en.adoc?plain=1:

:technical-committee-number: 34
:secretariat: SAC
:technical-committee: Food products
:subcommittee-number: 4
:subcommittee: Cereals and pulses

then in https://github.com/metanorma/mn-samples-iso/blob/main/sources/international-standard/rice-2023/sections-en/00-foreword.adoc?plain=1:

This document was prepared by Technical Committee ISO/TC
{technical-committee-number}, _{technical-committee}_, Subcommittee SC
{subcommittee-number}, _{subcommittee}_.

But do you actually have access to a rendering of "Addendum 1 to Internatiational Standard ISO 2533-1975"?

The original PDFs here: https://github.com/metanorma/iso-2533/tree/main/reference-docs.

opoudjis commented 1 month ago

i18n of (formerly ID) is localization-string formerly_id: "(formerly %)"

i18n of ... was developed by... is localization-string was_developed_by: "%1 was developed by %2"

But given the instrumental case after было разработано, I think you're right, we should just insert both paragraphs as text...

opoudjis commented 1 month ago

@opoudjis also, the 1st page contains the sentences:

How to encode it?

I would treat this as an initial admonition. It has already been encoded in the existing documents as a foreword. In my opinion not worth changing that encoding.

opoudjis commented 1 month ago

This document was prepared by Technical Committee ISO/TC
{technical-committee-number}, _{technical-committee}_, Subcommittee SC
{subcommittee-number}, _{subcommittee}_.

I think now you are right that this should be supplied by the author, and I am putting it in a separate preface clause, of type "provenance".

opoudjis commented 1 month ago

Over to you @Intelligent2013. I have added support for has-draft identifiers, but use the provenance preface clause instead.

Intelligent2013 commented 1 month ago

Hmm, the generated Presentation XML doesn't contain the element <metanorma-extension> at all. Ok, I'll add:

<metanorma-extension>
        <presentation-metadata>
            <name>document-scheme</name>
            <value>1979</value>
        </presentation-metadata>
</metanorma-extension>

manually for testing purposes.

Intelligent2013 commented 1 month ago

And the docidentifier doesn't contain the /Add... suffix. For testing purposes, I'll add <clause ... type="provenance"> into a1.presentation.xml manually.

Intelligent2013 commented 1 month ago

XSLT updated for the provenance preface rendering.

Hmm, the generated Presentation XML doesn't contain the element <metanorma-extension> at all.

Looks like I have to reinstall the Metanorma locally.

metanorma / metanorma-iso

PDF: New document type: Addendum (historic, 1997 and prior) #1219