- changed status to open
Consider aligning to ISO structure
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.
Comments (22)
-
-
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.
-
reporter 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).
-
Thanks Nat - yes, I think that sounds like a good direction to try.
-
-
assigned issue to
-
assigned issue to
-
- changed milestone to IDA Final
-
have write access now…will attempt to build Bitbucket pipeline
-
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.
-
- attached test.html
<div class="preview-container wiki-content"><!-- loaded via ajax --></div> <div class="mask"></div> </div>
</div> </form>
-
Thank Mark. Please find attached manually generated test.html output from Nat’s pandoc guidance
-
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). -
reporter 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.
-
reporter This repo could help
-
Nat’s document build is hosted at https://bitbucket.org/Nat/directives/src/master/
-
reporter Edmund and I could probably do the editorial pass on the new documents set, if you would like.
-
Yes please
-
That would be great. Thanks @Nat Sakimura
-
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_isoIn 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".
-
need to ensure we take account of changes incorporated as part of merges of PR #190 and PR#188
-
reporter FYI, this version is still using the old toolchain, so applying them to the current drafts should be straight forward.
-
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.
-
- changed status to resolved
addressed by PR #194
- Log in to comment