Ballot SC41: Reformat the BRs/EVGs/NCSSRs

[sleevi]

This PR attempts to reformat the BRs, EVGs, and NCSSRs to produce "proper" Pandoc-ified output using the common CA/Browser Forum Template.

This also adds internal cross-references for section references. This helps ensure that Sections are correct (since you have to type out both the number and the section heading), as well as makes it easier to navigate the document.

BRs

• Sections 3.2.2.4.18 / 3.2.2.4.19 don't properly appear as numbered
  lists.

  Closes BRs: Formatting for 3.2.2.4.18 / 3.2.2.4.19 is awkward #230

• Section 4.10.1 is missing a trailing period.

• Section 6.1.6 makes use of <sup> for superscript, which is valid
  for GitHub flavored markdown, but not in general Markdown.

  Although Pandoc supports superscripts via the superscript
  extension, that just leans more into Pandoc-flavored markdown.
  Rather than do that, keep it vanilla markdown by adding a carat
  and whitespace to indicate the superscripting.

  Closes BR 6.1.6: RSA public exponent between 217 and 2257 #231

• Appendix B is incorrectly indented for the ASN.1 sample.

  Closes BRs: Appendix B(2) is incorrectly indented #233

• Section 9.6.1 contains a bad section reference to a (non-existant)
  Section 11.2, when it should be to 7.1.4.2.2.

  Closes BRs: Incorrect cross-reference in Section 9.6.1: CA representations and warranties #237

• Section 3.2.2.4.7 references Section 3.3.1, instead of Section 4.2.1

  Closes BRs: Incorrect cross-reference in Section 3.2.2.4.7 DNS Change #236

• The BRs constantly refer to Section 8.1 as containing the audit
  scheme, when those are actually listed in Section 8.4.

  Closes BR: No audit schemes in Section 8.1 #216

NCSSRs

This attempts to align the NCSSRs with the portions of shared
structure between the BRs and EVGs, namely:

• A common Introduction that defines the scope of the
  document, relevant definitions, and effective dates (presently,
  this at the end of the document)
• Use Title Caps for section headings, rather than ALL CAPS
• Break out sublists within sentences into actual enumerated
  lists (e.g. "foo (i) bar or (ii) baz" now splits bar/baz as items on
  new lines)
• Within lists and sublists, a consistent numbering scheme is
  adopted.

EVGs

Most of these changes are merely formatting:

• Definition lists are aligned with the BRs as to whether or not the
  : is emphasized
• Certificate fields are code escaped, aligning with the BRs.
• The format of 9.2.* is aligned with how the BRs specify profile
  requirements for fields. This does lose some of the indenting
  currently present in the Word doc form (e.g. 9.2.4)
• The formatting of Appendix B is aligned to the Word doc
• Appendix C has section headings added for US/Canada
• Appendix D has section headings added for Japan
• The ASN.1 modules are formatted correctly
• Section references are aligned to a consistent format, where
  previously they used "this Section X", "the Section X",
  "Section X herein", "Section X of these Guidelines", and
  combinations that can result.

[timfromdigicert]

Reviewed everything and still willing to endorse.

The comments would be nice to address and/or fix, but none of them are showstoppers.

[sleevi]

Thanks Tim! I left a few comments on your comments. Taking a step back, it seems like there's some administrivia level questions:

• Did all the fields get aligned to code quotes correctly (matching the BRs)
• Do we clean up references in the EV Guidelines that just read awful for how they reference sections:
  • e.g. "This Section Foo", "Section Foo Herein", "Section Foo", "The Section Foo", "Section Foo of these Guidelines", etc

I held off, but if you're willing to review for consistency (and you think others won't object), we can certainly take a stab at it.

Edit: Went ahead and aligned the language, per your inline comment.

[sleevi]

Thanks @aarongable for the review (on this and the infrastructure). I think that should be everything, and hopefully @timfromdigicert and @dzacharo are still good with this.

[dzacharo]

Should we change "subsection (6)" with "subsection 6." and the various references of (3) (A) (C) to 3. A. C. and similar references, for consistency?

[sleevi]

I am open to pull requests, but given that it’s a significant editorial task to do correctly,, and that we have zero tooling to enforce it, it seemed rather Pyrrhic. There’s always things we “can” do, but my goal with this ballot was to focus on those that are semantically meaningful for display or the markdown directives itself, or which could be consistently searched and replaced.

[dzacharo]

This is a significant formatting improvement, thank you for the effort. The indentation makes things much clearer than the previous state.
I reviewed all three documents and everything looks good. I added a few comments for possible consistency improvements on referenced sub-item numbers which are not critical to fix.

[dzacharo]

Everything looks good.

[BenWilson-Mozilla]

Proposed changes to the NCSSRs look fine.

[aarongable]

Thanks for all of this! The changes to BR.md LGTM.

[aarongable]

Now that this is using v2 of the build guidelines action, do we want to bring in language tags on the code fences again? It's probably not a big deal, I think there were only three or four of them.

[sleevi]

do we want to bring in language tags on the code fences again

If we end up getting other/substantive feedback during the discussion period, I'm totally game to do so!

I'd be a little sad to restart the discussion period, mostly because I'd like to get this done to unblock some of the other changes (like the onion cleanups and other potentially-normative changes). The other part is I'm not sure how long the style would be maintained (see cabforum/build-guidelines-action#18 and cabforum/forum#11 ), so it's not terribly high on the list at the moment.

Since this doesn't (presently) affect presentation, I'm not too excited for it, but let's circle back and see how the discussion period goes. If anything comes up that requires restarting, I'll add that to the list.