Apply OGC reference rendering style in references (modified LNCS)

[ronaldtse]

From @ghobona:

OGC has historically used a derivative of the LNCS referencing style for the normative references. See example usage below.

• ISO: ISO 19101-1:2014, Geographic information — Reference model — Part 1: Fundamentals, International Organization for Standardization, 2005

• OGC: OGC 07-036r1, OpenGIS® Geography Markup Language (GML) Encoding Standard, Open Geospatial Consortium, 2016

I refer to it as a derivative because the document number is placed ahead of the title and the year is not placed in brackets.

I tried to create this same effect using the [[[id,label]]] approach of the metanorma-ogc template but failed.

So I ended up using regular anchors. See the file sections/clause_3_references.adoc in the document at the following link:

https://portal.opengeospatial.org/files/?artifact_id=86696

Note that the author-title separator is a colon.

Is it possible to create the same effect using the [[[id,label]]] approach of the metanorma-ogc template?

This is a great question and we've just started working on this area. Basically, a citation is created according to two things:

1. The metadata elements of the cited item.
2. The locality information within that cited item (optional, e.g., "Annex B").
3. The reference rendering style of the document.

We are currently working towards having a customizable way of determining item 3.

In the near term, we can implement this "OGC reference rendering style" (a LNCS-variant) in the code.

In the longer term, we will want to implement the "OGC reference rendering style" as some sort of CSL / CSL-superset definition to ensure all references are correctly rendered.

Thoughts @opoudjis ?

[ronaldtse]

For the record, this is also used by NIST. (We implemented a custom reference rendering style for NIST)

[ronaldtse]

@ghobona I'd like to confirm two things:

1. We're only talking about the "Normative references" section. So it only applies to referencing SDO documents only. Is this correct?

The reason I ask is that a citation style can be very complex and is not something that can be done quickly. For example, ISO 690 (international standard for citations) is nearly 100 pages long.

2. LNCS style does not contain really contain a reference style for a "Standard". They have styles for referencing "Journals", "Books", "Conference proceedings", etc.

Journal:

Author Surname, A.: Title. Publication Title. Volume number, Issue number, Pages Used (Year Published).

Conference proceeding:

Author Surname, A.: Title. Publication Title. p. Pages Used Publisher, City (Year Published).

Book:

Author Surname, A.: Title. Publisher, City (Year Published).

The desired style for OGC given by the two examples we extrapolate the rule for citing Standard documents:

{author}: {document identifier}, {title}, {publisher}, {year}

In this case both {author} and {publisher} are identical.

Is this correct?

[ogcscotts]

I recommend keeping Metanorma on the proper LNCS and OGC will accept that year goes in parentheses (we at OGC need to update our own templates). Yes, author and publisher would be identical. City will always be "Wayland."

[ronaldtse]

@ogcscotts then the "OGC style of citing Standard documents" will be:

{author}: {document identifier}, {title}. {publisher}, {city} ({year})

In the case of standard organizations like ISO and OGC, using the samples given by @ghobona they will be:

• ISO: ISO 19101-1:2014, Geographic information — Reference model — Part 1: Fundamentals. International Organization for Standardization, Geneva (2014)

• OGC: OGC 07-036r1, OpenGIS® Geography Markup Language (GML) Encoding Standard. Open Geospatial Consortium, Wayland (2016)

@ogcscotts question: do we want some qualification for the city name? "Wayland", "Wayland, MA"?There are couple places in the UK with the same name.

(That said, LNCS references often write "Berlin Heidelberg New York" for {city}, which is a concatenation of city names with no understandable delimitation...)

[ogcscotts]

@ronaldtse I'd just stick with "Wayland" as I have seen very few LNCS references with more full location attribution... wait, that sounds like something OGC should do!!!!

[opoudjis]

Let me reiterate what @ronaldtse has said:

• Normative references contain standards.
• Implementing referencing for document classes other than standards is a very very big task. I have made some preliminaries in it for NIST, but it is hard-coded, and fragile.
• It is also unusable in Metanorma, since we have no means of entering bibliographic entries other than standards into the document. We have been working on inserting references into Metanorma via YAML. (We had hoped to use Asciidoctor definition lists, but with only three levels of nesting permitted, they simply will not align to our bibliographic model.)

With all that, we cannot undertake to deliver generic bibliographic rendering to OGC soon. It will take months.

[opoudjis]

As for standards:

• Metanorma by default uses just the title.
• By screenscraping against identifier codes, we can retrieve bibliographic information for standards from ISO, IEC, IETF, ITU, NIST, GB. OGC is not in that list: do you have an online listing of standards publications? If not... that makes things more difficult. https://www.opengeospatial.org/standards is not fit for purpose, since it does not contain dates.
• With the screenscraping, we can retrieve the latest authoritative title and date, and we will have added the publisher. We have not added the city, and we would need to add it in to all our screenscraping gems.
• Screenscraping is by very very very far our preferred course of action for standards citations.
• Without a screen-scrapable source of truth for OGC documents, we would have to allow you to enter a YAML style set of bibliographic attributes. I can try using Asciidoctor definition lists, because bibliographic entries for standards, at least, are relatively simple. This is undocumented, and I'm not yet convinced we will use Asciidoctor definition lists, because of the nesting constraints in Asciidoctor. So I don't think we should go this way. But the following would work, though it is currently undocumented, and will not render much of anything in OGC:

[%bibitem]
=== OpenGIS® Geography Markup Language (GML) Encoding Standard
id:: OGC 07-036r1
date::
type::: published
value::: 2016
contributor::
organization:::
name:::: Open Geospatial Consortium
place:: Wayland

Again: this is experimental, and I would strongly recommend you either provide screen-scrapable source for OGC standards, or else wait until we have implemented generic referencing.

Or else, you can just write the full LNCS citation for OGC standards as its "title"; it will just be treated as a preformatted citation. Which in fact is the least disruptive option of all for OGC:

* [[[id,label]]], OGC: OGC 07-036r1, _OpenGIS® Geography Markup Language (GML) Encoding Standard_, Open Geospatial Consortium, 2016

[opoudjis]

This ticket is being demoted from Urgent to High. Urgent are tickets that will take a day or two to happen; the work in this ticket is months for full LNCS, and even for standards, it may well be weeks.

[opoudjis]

So:

For standards we do not screenscrape (OGC, W3C), treat the entire LNCS citation as the title:

* [[[id,label]]], OGC: OGC 07-036r1, _OpenGIS® Geography Markup Language (GML) Encoding Standard_, Open Geospatial Consortium, 2016

We will not attempt to generate it from scratch.

For the standards we do screenscrape, we will get the year from the screenscrape, and we will perforce need to add places of publication to all our screenscrapes. Where available. We will put dates and places of publication and abbreviation as author, but if and only if that information is available from our screenscraping. If we can't get the city, we won't display it. (We should always be able to get the year, from the sources we have.)

[opoudjis]

The following is the new rendering of standards citations as implemented -- although you will not see places of publication until we have added them to our screenscraper.

<p id="ISO712" class="NormRef">ISO: ISO 712, <i>Cereals and cereal products</i>. <span>International Organization for Standardization</span>, Geneva (2018).</p>

<p id="ISO16634" class="NormRef">ISO/IEC: ISO 16634:-- (all parts), <i>Cereals, pulses, milled cereal products, oilseeds and animal feeding stuffs</i>. <span>International Organization for Standardization</span> and <span>International Electrotechnical Commission</span> (2018&#8211;2019).</p>

I have attempted to degrade gracefully if information is not available.

Again, this code will not be available to you until our next release.

[ronaldtse]

Just a clarification, by "screenscraping" not all the Relaton gems perform screen-scraping. For example, the NIST data source uses a Metanorma-specific JSON bibliographic endpoint provided by NIST. So there's no screen-scraping there.

If there is a JSON bibliographic endpoint for OGC publications, that would be great for all of us 😉

[opoudjis]

Since the proximate issue of standards rendering has been addressed, we are currently not going to proceed with the rest of this ticket for now:

• Standards are most of what is cited in other standards documents.
• Citations of other types of document can be entered as preformatted citations, after the * [[[id,label]]] anchor. Since they are not fetched from online databases, those preformatted citations will be left alone. (This is illustrated in the Rice document for ISO: https://github.com/metanorma/isodoc-rice)
• If you have existing bibliographic databases with other types of document (monographs, journal articles etc), you will want to convert them to Relaton and thence LNCS rendered citations...
• ... but right now, there is no way to incorporate non-standards bibliographic items into Metanorma anyway (although we are currently working on it).
• If and when we do incorporate such bibliographic items, we will want to come up with a stylesheet based approach like CSL, rather than working in code like we currently do with NIST rendering.

I am unassigning this issue from myself, and putting it on hold. If the conditions above are fulfilled, I will revisit it; but you can handle non-standards documents in Metanorma right now by just putting in an entry like this:

* [[[ref13,13]]] [smallcap]#Buckee G.K.# Determination of total nitrogen in barley, malt and beer by Kjeldahl procedures and the Dumas combustion method -- Collaborative trial. _J. Inst. Brew._ 1994, *100* (2) pp 57-64

[ronaldtse]

Now have a definitive form from 690, perhaps this is applicable to all MN flavors, not only OGC. AsciiBib and Relaton YAML, if Metanorma can support them, will be able to handle this.

[opoudjis]

This is an issue that will be in eternal limbo unless some more concrete plan of action is attached to it. ping @ronaldtse

[opoudjis]

This ticket can now be actioned, with the relaton-render gem being used to generate references for ISO 690 in general.

[opoudjis]

Ronald thinks using the existing Springer LNCS stylesheet under CSL is a good idea.

Uhuh.

https://github.com/citation-style-language/styles/blob/6152ccea8b7d7a472910d36524d1bf3557a83bfc/springer-lecture-notes-in-computer-science.csl

https://github.com/inukshuk/csl-ruby

https://github.com/inukshuk/citeproc

https://readthedocs.org/projects/citation-style-language/downloads/pdf/master/

https://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html?highlight=accessed#date-fields

[opoudjis]

Waiting on https://github.com/relaton/relaton-bib/issues/56, to generate citeproc.

[opoudjis]

Ronald thinks using the existing Springer LNCS stylesheet under CSL is a good idea.

As of right now, @ronaldtse, this is an atrociously bad idea.

• Our export to citeproc is lossy
• The citeproc import into CSL is even more lossy
• What little bibliographic data we are getting out through citeproc looks nothing like what we have been generating, using our own renderer which we know works
• e.g. "Fred Johnson, Jackson KG, Nixon RM" vs "Johnson, F., Jackson, Nixon, R.M."

We are going to have to expend significant effort to debug citeproc, just to get back to where we are right now with relaton-render.

If OGC have seen fit to customise LNCS, we would be putting in even more work to get the customised version of LNCS working, when, again, we already have relaton-render.

[ronaldtse]

That was "back then" and we know that the time has changed, luckily, for the better. Now with relaton-render we are now free to pursue more complex and accurate bibliographic rendering (instead of being hostage to citeproc's internal data model that is very limited).

The way forward is definitely to define an "OGC style LNCS" using relaton-render.

[opoudjis]

Which leads me to comment BUT WE HAVE ALREADY DONE THAT.

LNCS is not actually particularly big: https://github.com/citation-style-language/styles/blob/6152ccea8b7d7a472910d36524d1bf3557a83bfc/springer-lecture-notes-in-computer-science.csl

This says all of the following:

2 names: "Doe, J. and T. Williams" 3 names: "Doe, J., S. Smith, and T. Williams"

<name name-as-sort-order="all" sort-separator=", " initialize-with="." delimiter=", " delimiter-precedes-last="always"/>

(OGC have already customised away from this; that's why we generate with LNCS "Johnson, F., Jackson, Nixon, R.M.", and OGC have "Fred Johnson, Jackson KG, Nixon RM". So I need to see their template.)

"NAME (ed./eds.)"

<label form="short" prefix=" " strip-periods="true"/>

"publisher, place"

<text variable="publisher"/> <text variable="publisher-place" prefix=", "/>

Bibliography:

{author}: {title}. {publisher} ({year}).

for journal articles,

{author}: {title}. {journal} {volume}, {page} ({year}).

for conference papers

{author}: {title}. In {editor} {container-title} {page} (publisher). ({year})

We already have:

template:
  standard: "{% if creatornames %}{{ creatornames }} ({{role}}){%else%}{{ publisher_abbrev}}{%endif%} : {{standardidentifier|first}} {{draft}} , <em>{{ title }}</em>. {{ publisher }}{%if place%},{%endif%} {{ place }} ({{date}}). {{uri}}."

and

  one: "{% if nonpersonal[0] %}{{ nonpersonal[0] }}{% else %}{{surname[0] }} {{initials[0]}}{% endif %}"
  two: "{% if nonpersonal[0] %}{{ nonpersonal[0] }}{% else %}{{surname[0] }} {{initials[0]}}{% endif %} , {% if nonpersonal[1] %}{{ nonpersonal[1] }}{% else %}{{surname[1]}} {{ initials[1]}}{% endif %}"
  more: "{% if nonpersonal[0] %}{{ nonpersonal[0] }}{% else %}{{surname[0] }} {{initials[0]}} {% endif %} , {% if nonpersonal[1] %}{{ nonpersonal[1] }}{% else %}{{surname[1]}} {{ initials[1]}} {% endif %} , {% if nonpersonal[2] %}{{ nonpersonal[2] }}{% else %}{{surname[2]}} {{initials[2]}}{% endif %}"

As far as I'm concerned, this ticket was not helpful, although the immaturity of our support of citeproc and bibtex are as much of an issue as anything else. But OGC have clearly customised LNCS quite heavily. All that I should be doing here is expanding the relaton template to the other bibliographic types, following LNCS, but with OGC's treatment of names.