Consider aligning to ISO structure

[Nat Sakimura]

Comment:

We may want to submit this spec to ISO as well. If so, then adopting ISO structure may make sense.

Proposal:

Give a mandate to editors to restructure the document.

[Joseph Heenan]

Note that the current toolchain (mmark + xml2rfc) can’t generate an an ISO structure compliant document (or at least myself + FAPI WG members couldn’t figure how to do it), so this probably implies changing toolchain with the inference that we also will no longer have an xml format of the document (every OpenID Foundation spec to date that I’m aware of has an xml version published alongside the html one).

The issue was I think that we couldn’t put the normative references section where ISO say it should be.

[Nat Sakimura]

I have created the local toolchain using Pandoc to produce HTML. I have shared it with @Joseph Heenan

The guidance can be found here. https://docs.google.com/document/d/1FGqaUGBLKq5SFtHXHkvYv9WrbnVI1sKtfs9xdqWDDuQ/edit#

It includes the Pandoc commands and template links.

The pandoc command takes the following form:

\$ pandoc -N --toc -c site.css --template=draft-template.html input-filename.md -f markdown -t html -s --embed-resources -o output_filename.html

There is an attempted Bitbucket pipeline but it currently spits an error such as “dirty repository” (apparently, the conversion is working but failing to push it to the HTML repo for publishing).

‌

[Joseph Heenan]

Thanks Nat - yes, I think that sounds like a good direction to try.

[Hodari McClain]

have write access now…will attempt to build Bitbucket pipeline

[Mark Haine]

I spoke with Nat and there is a choice about whether we follow RFC2119 or ISO guidance on documention. Apart from the work to make the changes there does not seem to be a downside to the ISO option and theer is the upside of it being much easier for it to be adopted by ISO in the future if we follow ISO guide.

The question of tooling is separate and I suggested that for eKYC documents we address the document format manually and look at tooling and document templates as a seperate piece of work for the foundation more generally.

[Hodari McClain]

  <div class="preview-container wiki-content"><!-- loaded via ajax --></div>
  <div class="mask"></div>
</div>

</div> </form>

[Hodari McClain]

Thank Mark. Please find attached manually generated test.html output from Nat’s pandoc guidance

[Joseph Heenan]

I suggested that for eKYC documents we address the document format manually

Note that to align with the ISO structure the normative references need to be in a very different place in the document (section 2 in ISO vs last but one section in xml2rfc). This means there’s a lot of error prone edits required if this is done manually as almost all sections need to be renumbered, including all the associated anchors (<a href="#section-5" etc).

[Nat Sakimura]

Regarding the “error-prone edits”, there are not too many internal references, fortunately, so it should not be too hard to do. <a href="#section-5" etc., if I understand correctly, is done by the tool and not manually.

On top of it, we are considering https://bitbucket.org/openid/ekyc-ida/pull-requests/171, right? That will necessitate these numbering changes anyway.

Tooling change is unnecessary, though it should make things easier going forward to ensure some of the mandatory text, etc., is included.

‌

[Nat Sakimura]

This repo could help

https://bitbucket.org/Nat/directives/src/master/

[Mark Haine]

Nat’s document build is hosted at https://bitbucket.org/Nat/directives/src/master/

[Nat Sakimura]

Edmund and I could probably do the editorial pass on the new documents set, if you would like.

[Mark Haine]

Yes please

[Hodari McClain]

That would be great. Thanks @Nat Sakimura

[Mark Haine]

Messages from Nat:

Edmund converted the files to the ISO friendly format. See here: https://edmundjay.bitbucket.io/ekyc/

And the diffs. Mostly de-capitalization and MUST --> shall etc.
https://bitbucket.org/edmundjay/ekyc-ida/branch/issue_1363_iso

In ISO, using capitalization for signaling a specific meaning is disallowed as it does not translate into the languages that does not have equivalent form.

So, things like "Transformed Claim" are turned into "transformed claim".

[Mark Haine]

need to ensure we take account of changes incorporated as part of merges of PR #190 and PR#188

‌

[Nat Sakimura]

FYI, this version is still using the old toolchain, so applying them to the current drafts should be straight forward.

[Hodari McClain]

Thanks Nat/Edmund…did a scrub of PR #192 and edmund’s ida commit and looks like some changes are not incorporated (MAY->can vs. MAY->may, etc.). My recommendation would be to merge PR #192 then do a second pass on edmund’s.

[Mark Haine]

addressed by PR #194