Align the chapter etc. structure to FAPI 1

[Nat Sakimura]

It will make it easier for people to compare. FAPI 1.0 is using the ISO and IEC defined structure. We need to do it before we start creating the FAPI 2 conformance tests.

[Joseph Heenan]

I’m going to have a go at doing this.

[Joseph Heenan]

Initial attempt here: https://bitbucket.org/openid/fapi/pull-requests/305/fapi2-baseline-align-the-chapter-etc

[Joseph Heenan]

The current draft, after the above pull request, still doesn’t align. This is because the expected section 2, ’Normative references’ is at the end of the document, meaning that the main content starts at clause 4, not clause 5 as FAPI1 does and as I think ISO expect.

Xml2rfc seems pretty insistent that the normative references goes at the end of the document. We need to decide what to do about that, the choices I can see:

1. Find someone that understands mmarkdown/xml2rfc better than I do (which given my level of knowledge, shouldn’t be hard)
2. Add a section 2 that just says “see section 9 for normative references”.
3. Try to rearrange the html after generation, either by hand or with some python (probably easiest if we do '2' as well so that the other sections are all correctly numbered)
4. Don’t use the mmarkdown/xml2rfc normative reference handling (I believe this is the approach FAPI1 took, though it introduces it’s own problems and I’m pretty sure the FAPI1 publishing flow involved some manual and error prone steps)
5. Don’t align to ISO

Any suggestions? I guess we could do ‘2’ at least for now if we’re committed to finding a solution.

[Joseph Heenan]

The JARM spec has a similar issue.

[Dave Tonge]

I propose we close this issue, and do a new document with editorial changes when we get round to submitting to ISO

[Joseph Heenan]

https://bitbucket.org/openid/fapi/pull-requests/370 made the change we wanted to make for now.