Re: [niso-sts] How to reference sections from another standard

["Imsieke, Gerrit, le-tex gerrit.imsieke@xxxxxxxxx" <niso-sts-list-service@xxxxxxxxxxxxxxxxxxxxxx>]

On 12/04/2018 15:53, DorothC)e Stadler doro@xxxxxxxxxxx wrote:
> Thank you Gerrit for this very detailed answer, it gave me a lot of food 
> for thought in terms of how to manage our IDs and then resolve them 
> properly, so that is definitely a topic to address asap!
>
> My question was actually much more basic:
> If inside the text of the standard I want to make a reference to a 
> section in another standard (letbs assume for now I have resolved my ID 
> issues), how do I concretely do this?
> <std> is tough to use because itbs quite restricted where I can use it.. 
> I am using a lot of <named-content> inside which I donbt see how I can 
> add <std>.

I remember that I occasionally reverted to surrounding std elements with 
roman elements, for the sole reason that I be able to use std within 
named-content. I think we should allow std within named-content and 
styled-content. This is an issue that we will discuss in the standing 
committee, or maybe Tommie or Debbie can chime in to explain the 
rationale for not allowing std within named-content.
std is a bit of a hybrid element anyway: It is used in lieu of 
mixed-content or element-content within ref, but it can also replace 
ext-link in ordinary paragraphs. Therefore I think it should be allowed 
in almost any element that accepts ext-link as a child and that STS has 
inherited from JATS (which is to say, std should not be allowd below std 
in STS).

> For references to whole standards inside the text, we have decided to 
> use <xref> to point directly at the entry inside the Normative 
> references / Bibliography where we can then manage all the other IDs, 
> title etc. In our case, I donbt find it efficient to have to have 
> bhiddenb reference lists to each and every element from another standard 
> we might be referring to to which to point to like DIN are doing.

The thing is that you sometimes have links to standards (if only to 
previous versions of the same standard) that donbt appear in normative 
reference lists. And deep links to certain tables or sections of another 
standard also donbt appear in the normative reference lists.
Otherwise, using xrefs that point to ref elements is very reasonable.

> If I have the text: bPlease refer to Standard ABC, Section 5b, would it 
> be incorrect to mark it up as:
> <p>Please refer to <xref ref-type=bbibrb rid=b1234b>Standard ABC</xref>, 
> <ext-link ext-link-type=bguidb Xlink:href=bInternal GUID for 
> sectionb>Section 5></ext-link>

Ibd opt for marking up the whole deep link, including the reference to 
its document (whose standard number and year goes into std-ref), in a 
single std element. Also if you linked to a range of sections in another 
standard, or if you linked to bsection 4.2, table 3b of another 
standard, Ibd include the whole set of target IDs in a single 
std/std-id-group.
But NISO STS isnbt quite strict about whether to put a section range, 
mixed section/table links, or even links to multiple parts of a standard 
into a single std or into multiple stds. But the spirit of NISO STS is 
that links to other standards or parts thereof should be encoded as std 
(with appropriate IDs if available) instead of ext-link.

> I guess what I am missing is which tags to use.. and if I am using 
> <ext-link> in the right way here or not.
>
> I saw you made a note saying: donbt use ext-link within std. std is a 
> domain-specific replacement for ext-link.
> Why not? Itbs allowed when looking at the NISO STS..? Or is this more a 
> recommendation that one should do it in a more structured way as you 
> described below?

I think it may sometimes appear as an issue that, as Tommie likes to put 
it, STS is an enabling rather than a prescriptive technology. We need to 
work on it by developing NISO STS further, making it more lenient wrt 
accepting std in more places on the one hand and making it more concise 
wrt documenting best practice for cases such as deep linking in all its 
facets.

One place where we might discuss and establish best (or at least common) 
practice is at STS4i, https://github.com/sts4i, that Ibll briefly 
present during JATS-Con next week.

Gerrit

> Thanks a lot,
> Kind Regards
> DorothC)e
>
>
> ---------------------------------------------
> DorothC)e Stadler
>
> Rathenower Str. 38
> 10559 Berlin
> Tel: +49 1525 840 85 93
> doro@xxxxxxxxxxx <mailto:doro@xxxxxxxxxxx>
>
>
>
> > On 11. Apr 2018, at 21:01, Imsieke, Gerrit, le-tex 
> > gerrit.imsieke@xxxxxxxxx <mailto:gerrit.imsieke@xxxxxxxxx> 
> > <niso-sts-list-service@xxxxxxxxxxxxxxxxxxxxxx 
> > <mailto:niso-sts-list-service@xxxxxxxxxxxxxxxxxxxxxx>> wrote:
> >
> > Hi Doro,
> >
> > In ISO STS, such a link would be encoded as <sts sts-id="{URN}">, 
> > where {URN} is a RFC 5141 URN. Example:
> >
> > <std std-id="iso:std:iso:3745:ed-3:en:clause:A" 
> > type="dated"><std-ref>ISOB 3745:2012</std-ref>, AnnexB A</std>
> >
> > See https://tools.ietf.org/html/rfc5141 for instructions how to form 
> > URNs for these deep links.
> >
> > Unfortunately, RFC 5141 is only defined for certain originators (the 
> > part after the second colon), namely "iso", "iso-iec", "iso-cie", 
> > "iso-astm", "iso-ieee", "iec".
> >
> > Although you can, at least for internal use, extend it to allow an 
> > originator string that identifies other organizations, this flies in 
> > the face of the bUb in URN since it is not guaranteed that any two 
> > users of these privatized schemes will use the same identifier for the 
> > same organization.
> >
> > In addition, many organizations use their own internal document 
> > identifiers for which there is no place in these URNs anyway.
> >
> > Other users might want to use DOIs for identifying published 
> > standards, in order to be able to utilize this established permanent 
> > linking facility.
> >
> > NISO STS addresses this request for multiple links by allowing 
> > multiple std-ids on the std element, grouped in an std-id-group 
> > (http://niso-sts.org/TagLibrary/niso-sts-TL-1-0-html/element/std-id-group.html).
> >
> > However, NISO STS does not assume a particular linking scheme in these 
> > identifiers. The suggestions in 
> > http://niso-sts.org/TagLibrary/niso-sts-TL-1-0-html/attribute/std-id-link-type.html 
> > are 'doi', 'urn', and 'internal-pub-id'.
> >
> > DIN/Beuth are using their established internal document identifiers 
> > for linking. Example:
> >
> > <std><std-id std-id-link-type="internal-pub-id" 
> > std-id-type="dated">d1ca7c3f#sub-a</std-id><std-ref>ISO 
> > 3745:2012</std-ref>, Annex A</std>
> >
> > It is up to the rendering system to create a proper, user-actionable 
> > link then (for example, an HTML link that points to Beuthbs online 
> > platform).
> >
> > In principle, they could have enhanced this link by DOIs, like this:
> >
> > <std><std-id-group>
> > B <std-id std-id-link-type="doi" 
> > std-id-type="dated">https://doi.org/b&/b&#sub-a</std-id>
> > B <std-id std-id-link-type="internal-pub-id" std-id-type="dated">
> > d1ca7c3f#sub-a</std-id>
> > </std-id-group><std-ref>ISO 3745:2012</std-ref>, Annex A</std>
> >
> > There are two issues with this. One is related to DOIs, the other is 
> > related to redundancy.
> >
> > In the example above, the DOI is augmented by a fragment identifier. 
> > This may or may not be forwarded from the DOI resolver to the 
> > publisher, and since fragment identifiers are resolved by the client 
> > (browser), it is not guaranteed that the publisherbs Web server will 
> > serve the document in its entirety so that your client can navigate to 
> > #sub-a, nor is it guaranteed that the rendered document uses the same 
> > ID scheme.
> > Of course this is hypothetical: If a standards publisher creates DOIs 
> > with fragment identifiers, they should make sure to take the user to 
> > the deep link if such a fragment identfier is contained in the DOI.
> > And I think crossrefbs resolver will append the fragment identifier to 
> > the resolved publisher URL, so this should work in practice.
> > A while ago, Bruce Rosenblum checked with someone from Crossref 
> > whether theybd recommend such a fragment identifier approach, and they 
> > did not.
> > The alternative is to register distinct DOIs that will resolve to a 
> > URL that directly points to document fragments on the publisherbs 
> > platform. But this is prohibitively costly. And still, youbd have to 
> > operate a local cache of all deep-linking DOIs because you probably 
> > donbt want to query the central CrossRef server in order to resolve 
> > them, or you donbt want to send the users through CrossRef for 
> > following a link that could also point directly from your platform to 
> > your platform.
> >
> > The other issue is redundancy. Quite often, a link to a certain entity 
> > occurs multiple times in a document. You donbt want to supply IDs for 
> > all the different naming schemes at every single link location. So it 
> > is probably wise to just use identifiers in a single internal scheme.
> > In order to decrease this redundancy, Beuth has maintained, in the 
> > document metadata, a centralized list of all references with their 
> > internal IDs and with their XML formal public identifiers. From within 
> > the document, they just referred to that central, per-document 
> > multi-ID storage with an xref-like mechanism. This is admittedly an 
> > additional level if indirection, but it avoids dangerous redundancy 
> > where errors may be introduced by copying and pasting during document 
> > editing.
> >
> > So Ibd recommend to avoid this redundancy in NISO STS, too. DIN/Beuth 
> > are currently mimicking their old centralization approach by creating 
> > a ref-list in the document frontmatter and storing all the 
> > std-id-groups there, only referring to them from the text by something 
> > like <xref ref-type="bibr" rid="nla-nat-1">EN ISO 3745:2012</xref>.
> > The centralized ref-lists are stored like this, in a NISO STS 
> > compliant manner:
> > b&
> > </std-meta>
> > <notes notes-type="bibl" specific-use="centralized-citations">
> > B <ref-list content-type="invisible-citation-list">
> > B B B <ref id="nla-nat-1">
> > B B B B B <std><std-id-group>
> > B B B B B B B B B <std-id std-id-link-type="internal-pub-id" 
> > std-id-type="dated">d53f90ba</std-id>
> > B B B B B B B B B <std-id std-id-link-type="fpi" std-id-type="dated">+//ISO 
> > 9070/RA::A00007::GE::DIN German Institute for 
> > Standardization::Regulations//DOCUMENT EN ISO 3745:2012-03-00//DE</std-id>
> > B B B B B B B </std-id-group></std>
> > B B B </ref>
> > B B B <ref id="nla-nat-2">
> > b&
> >
> > My recommendation is to roll your own (publisher-internal) ID scheme 
> > that you use for deep links. This can be URLs like the doi.org 
> > <http://doi.org> URLs, but with your own host name in it. One 
> > prerequisite of this ID scheme is that it should be easy to recognize 
> > the ID for the whole document when you see a deep link ID. Another 
> > recommendation is that fragment identifiers in this private ID scheme 
> > should correspond to XML IDs in the documents.
> > Finally, when you have adoptions like DIN EN ISO 3745, you should 
> > assign a distinct document ID to each shell (ISO, CEN, DIN) / language 
> > (de, en, b&) combination. For example, d1ca7c3f#sub-a points to Annex A 
> > in the compound German-language DIN EN ISO document while 
> > d53f90ba#sub-a points to Annex A either in the compound German DIN EN 
> > ISO document or in the German EN ISO document, and d1d1d9e3#sub-a 
> > points to Annex A either in DIN EN ISO 3745 or in the German 
> > translations of EN ISO 3745 or ISO 3745.
> > In these examples, 'd1ca7c3f' is the doc ID of the German-language 
> > edition of DIN EN ISO 3745:2012, 'd53f90ba' corresponds to EN ISO 
> > 3745:2012 (in German), and 'd1d1d9e3' is for ISO 3745:2012 (German 
> > translation).
> > You donbt need to use cryptic IDs like that, you can create your own 
> > URLs with fragment identifiers, or languages encoded by name/value 
> > pairs in the query strings.
> > You only need to run your own resolver when rendering the standards to 
> > HTML or PDF, or when exporting the XML for someone else with their own 
> > naming scheme. The resolver should be able to collate the internal IDs 
> > with the ISO URNs of adopted standards so youbre on the same page with 
> > someone who has also created a nationalized version of a certain ISO 
> > standard. So both of you can tell: This is the German-language version 
> > of the same EN adoption of iso:std:iso:3745:ed-3 that the Finnish guy 
> > refers to in their naming scheme.
> > Such a resolver is typically implemented in Java or XQuery, and it 
> > will use some kind of database.
> >
> > Btw, donbt use ext-link within std. std is a domain-specific 
> > replacement for ext-link.
> >
> > Gerrit
> >
> >
> > On 11/04/2018 12:07, DorothC)e Stadler doro@xxxxxxxxxxx 
> > <mailto:doro@xxxxxxxxxxx> wrote:
> > > Hello,
> > > I am wondering how to correctly reference a specific section from 
> > > another standard. Our national standards have IDs on all sections and 
> > > elements.
> > > Say, for example, I want to make a reference to Section 5 in Standard 
> > > ABC:2017 from my standard, how to best to this?
> > > Should I put the standard reference inside <std> and then use 
> > > <ext-link> to hold the reference to the section?
> > > <std>Standard ABC <ext-link xlink:href=bSection_IDb>Section 
> > > 5--</ext-link></std>
> > > Is there a way to identify that the <ext-link> is a reference to an 
> > > element inside another standard (as opposed to other <ext-link> 
> > > elements in the standard that would point to URLs for example)?
> > > Or is there a better way of doing this?
> > > Is it OK to put just the ID of the section inside the @xlink:href?
> > > Thanks for your help in this!
> > > Greetings from Berlin,
> > > DorothC)e
> > > ---------------------------------------------
> > > DorothC)e Stadler
> > > Rathenower Str. 38
> > > 10559 Berlin
> > > Tel: +49 1525 840 85 93
> > > doro@xxxxxxxxxxx <mailto:doro@xxxxxxxxxxx> <mailto:doro@xxxxxxxxxxx>
> > > You are subscribed as gerrit.imsieke@xxxxxxxxx 
> > > <mailto:gerrit.imsieke@xxxxxxxxx> to NISO STS Discussion by Mulberry 
> > > Technologies, Inc. <http://www.mulberrytech.com/>
> > > EasyUnsubscribe <-sts-list/225679> (by email <>)
> >
> > --
> > Gerrit Imsieke
> > GeschC$ftsfC<hrer / Managing Director
> > le-tex publishing services GmbH
> > Weissenfelser Str. 84, 04229 Leipzig, Germany
> > Phone +49 341 355356 110, Fax +49 341 355356 510
> > gerrit.imsieke@xxxxxxxxx <mailto:gerrit.imsieke@xxxxxxxxx>, 
> > http://www.le-tex.de
> >
> > Registergericht / Commercial Register: Amtsgericht Leipzig
> > Registernummer / Registration Number: HRB 24930
> >
> > GeschC$ftsfC<hrer / Managing Directors:
> > Gerrit Imsieke, Svea Jelonek, Thomas Schmidt
>
> You are subscribed as gerrit.imsieke@xxxxxxxxx to NISO STS Discussion by 
> Mulberry Technologies, Inc. <http://www.mulberrytech.com/>
> EasyUnsubscribe 
> <-sts-list/225679> (by email 
> <>)

--
Gerrit Imsieke
GeschC$ftsfC<hrer / Managing Director
le-tex publishing services GmbH
Weissenfelser Str. 84, 04229 Leipzig, Germany
Phone +49 341 355356 110, Fax +49 341 355356 510
gerrit.imsieke@xxxxxxxxx, http://www.le-tex.de

Registergericht / Commercial Register: Amtsgericht Leipzig
Registernummer / Registration Number: HRB 24930

GeschC$ftsfC<hrer / Managing Directors:
Gerrit Imsieke, Svea Jelonek, Thomas Schmidt