New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
BRs: Formatting for 3.2.2.4.18 / 3.2.2.4.19 is awkward #230
Labels
baseline-requirements
Server Certificate CWG - Baseline Requirements
editorial
Editorial issues, such as incorrect section references, inconsistent title/section names, et c
Comments
sleevi
added
editorial
Editorial issues, such as incorrect section references, inconsistent title/section names, et c
baseline-requirements
Server Certificate CWG - Baseline Requirements
labels
Nov 18, 2020
FYI @castillar @dzacharo |
sleevi
added a commit
to sleevi/cabforum-docs
that referenced
this issue
Nov 24, 2020
There are three typographical/formatting issues in the current generated documents: - Sections 3.2.2.4.18 / 3.2.2.4.19 don't properly appear as numbered lists. - 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 cabforum#230 Closes cabforum#231
sleevi
added a commit
to sleevi/cabforum-docs
that referenced
this issue
Nov 30, 2020
There are three typographical/formatting issues in the current generated documents: - Sections 3.2.2.4.18 / 3.2.2.4.19 don't properly appear as numbered lists. - 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 cabforum#230 Closes cabforum#231
sleevi
added a commit
to sleevi/cabforum-docs
that referenced
this issue
Nov 30, 2020
There are three typographical/formatting issues in the current generated documents: - Sections 3.2.2.4.18 / 3.2.2.4.19 don't properly appear as numbered lists. - 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 cabforum#230 Closes cabforum#231
sleevi
added a commit
to sleevi/cabforum-docs
that referenced
this issue
Nov 30, 2020
There are three typographical/formatting issues in the current generated documents: - Sections 3.2.2.4.18 / 3.2.2.4.19 don't properly appear as numbered lists. - 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 cabforum#230 Closes cabforum#231
sleevi
added a commit
to sleevi/cabforum-docs
that referenced
this issue
Dec 2, 2020
There are three typographical/formatting issues in the current generated documents: - Sections 3.2.2.4.18 / 3.2.2.4.19 don't properly appear as numbered lists. - 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 cabforum#230 Closes cabforum#231
sleevi
added a commit
to sleevi/cabforum-docs
that referenced
this issue
Jan 7, 2021
There are three typographical/formatting issues in the current generated documents: - Sections 3.2.2.4.18 / 3.2.2.4.19 don't properly appear as numbered lists. - 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 cabforum#230 Closes cabforum#231
castillar
pushed a commit
that referenced
this issue
Feb 26, 2021
* Address formatting issues with the BRs There are three typographical/formatting issues in the current generated documents: - Sections 3.2.2.4.18 / 3.2.2.4.19 don't properly appear as numbered lists. - 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 #230 Closes #231 * Convert the EVGs to Pandoc-flavored Markdown This enables GitHub Actions-based integration for the production of the EV Guidelines. * Fixup NSRs * Fix lists * Fix tabs/spaces that were messing up lists * Add internal cross-references Update all occurrences of "Section(s) X.Y.Z" to actually link to the appropriate section within the document. This internal cross-reference is only relevant for HTML and PDF forms (that is, it does not affect the Word doc). This also fixes several bad cross-references: - Section 9.6.1 contains a reference to a pre-BRs 1.3.0 structure Closes #237 - Section 8.1 does not contain the audit schemes (another bad conversion in BRs 1.3.0); they are listed in Section 8.4 Closes #216 * Harmonize section references of the EV Guidelines References to sections within the EVGs are inconsistent, as represented in the form of "(th[e|is])? Section X (herein|of these Guidelines)?". This aligns the EVGs to the BRGs by consistently referring to "Section X" to represent the Section within the current document. * Renumber level 2 and 3 lists of the NSRs This aligns the NSRs to an internally consistent numbering format, which goes Section (always a number), lower-case alphabet, Arabic numeral, Roman numeral. * Update to v2.0.0 action * Fix a bug: name should be id for the step * Update to v2.0.0-rc2 action * Cleanup whitespace and lists This addresses two sets of issues pointed out by aarongable: An inconsistent use of tabs vs spaces and inconsistent breakouts of lists (I'd missed several). This aligns on a common spacing (spaces, the only true spaces) and breaks out the (i) items. * Fix some format issues with lists and whitespace * Update section links As of https://github.com/cabforum/build-guidelines-action/releases/tag/v2.0.0-rc3 section links now include the section number (e.g. "1.1 Section One" becomes "#11-section-one"). This makes it easier to review and maintain links, as any re-organizations will cause the links to break, which the continuous integration will warn on. This change rewrites all of the internal links to use the new style, and bumps the dependency to rc3 (which will hopefully be the last release). * Further style cleanups This linkifies the Appendix sections in both the BRs and the EVGs, and fixes some markdownlint errors for the EVGs, to go along with sleevi#34 for the BRs. * Additional cleanups and markdownlint compliance (#34) * Additional cleanups and markdownlint compliance This commit updates the BR.md doc with the following changes: * Removes all instances of two adjacent spaces, except when used for indentation * Removes all instances of two adjacent blank lines * Fixes all markdownlints, including spaces around lists, spaces around headings, and tags on fenced blocks. It also fixes a few other pieces of miscellany, such as paragraphs which were not sufficiently indented to semantically fall inside the list in which they are intended to fall, and fencing code blocks which should have been fenced. It does not address two markdownlints: There are still multiple H1 headings, and there are a few places where markdown believes that unordered list bullets should be unindented (but doing so would change the semantics of the document). * Harmonize styles further This is a series of small list formatting cleanups to ensure proper display. However, it does renumber Section 8.5.5 of the EVGs to use Arabic numerals for the requirements, aligning with the other requirements in Section 8.5, instead of using capitalized letters for the list. There are no internal references to those requirements, and so this should be safe. * Remove stray footnote During the SC26 cleanup work, there was a stray footnote that got left in which rendered incorrectly, relating to Section 3.2.2.6 and wildcards. This correctly removes it. Although we do support footnotes in the PDF and Docx writers, and we do use them, Section 3.2.2.6 was modified during SC26 to make the normative requirement clearer and part of the text, rather than as a footnote. * More cleanups This aligns the NCSSRs with the style of the EVGs and BRs, which is that lists use single spacing, not double. It aligns the definitions of the NCSSRs with that of the EVGs and BRs, of keeping the colon of a definition as non-emphasized text. * Fix a few stragglers from section references in the BRs We had a few BR Section X or Section X of these Baseline Requirements that I'd missed. * Update artifact name to include SHA-1 This hopefully will make it easier for people to review this PR as it progresses, by being able to determine which commit a converted document was associated with. * More consistency fixes This further aligns the documents to consistently: - Use one space after colons or other punctuation (other than period) - Code-escape ASN.1 field names and values * [WIP] Attempt to enable redline generation * Fix indent in section 8.4 (B) of the EVGs * Update build-draft-docs.yml Update to v2 of the action, and set draft mode for everything but that landed to the SCWG main repository. * Switch to explicit v2.0.0 rather than v2 In hindsight, this avoids any potential breakage in the future if there's an uprev of build-guidelines-action that subtly breaks things. Given that we don't currently regression test the generated files, this seems more likely (such as a break in the template or updated Pandoc minor version), so until we have that in place, I'll use an explicit full version. * Add languages to fenced codeblocks No functional change, but ensures that the fenced blocks have an appropriate syntax/language set. The set of names is adopted from the GitHub/Linguist supported languages. * Incoporate changes from SC39v3 and align other links Co-authored-by: Aaron Gable <aaron@aarongable.com>
castillar
pushed a commit
that referenced
this issue
Feb 26, 2021
* Address formatting issues with the BRs There are three typographical/formatting issues in the current generated documents: - Sections 3.2.2.4.18 / 3.2.2.4.19 don't properly appear as numbered lists. - 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 #230 Closes #231 * Convert the EVGs to Pandoc-flavored Markdown This enables GitHub Actions-based integration for the production of the EV Guidelines. * Fixup NSRs * Fix lists * Fix tabs/spaces that were messing up lists * Add internal cross-references Update all occurrences of "Section(s) X.Y.Z" to actually link to the appropriate section within the document. This internal cross-reference is only relevant for HTML and PDF forms (that is, it does not affect the Word doc). This also fixes several bad cross-references: - Section 9.6.1 contains a reference to a pre-BRs 1.3.0 structure Closes #237 - Section 8.1 does not contain the audit schemes (another bad conversion in BRs 1.3.0); they are listed in Section 8.4 Closes #216 * Harmonize section references of the EV Guidelines References to sections within the EVGs are inconsistent, as represented in the form of "(th[e|is])? Section X (herein|of these Guidelines)?". This aligns the EVGs to the BRGs by consistently referring to "Section X" to represent the Section within the current document. * Renumber level 2 and 3 lists of the NSRs This aligns the NSRs to an internally consistent numbering format, which goes Section (always a number), lower-case alphabet, Arabic numeral, Roman numeral. * Update to v2.0.0 action * Fix a bug: name should be id for the step * Update to v2.0.0-rc2 action * Cleanup whitespace and lists This addresses two sets of issues pointed out by aarongable: An inconsistent use of tabs vs spaces and inconsistent breakouts of lists (I'd missed several). This aligns on a common spacing (spaces, the only true spaces) and breaks out the (i) items. * Fix some format issues with lists and whitespace * Update section links As of https://github.com/cabforum/build-guidelines-action/releases/tag/v2.0.0-rc3 section links now include the section number (e.g. "1.1 Section One" becomes "#11-section-one"). This makes it easier to review and maintain links, as any re-organizations will cause the links to break, which the continuous integration will warn on. This change rewrites all of the internal links to use the new style, and bumps the dependency to rc3 (which will hopefully be the last release). * Further style cleanups This linkifies the Appendix sections in both the BRs and the EVGs, and fixes some markdownlint errors for the EVGs, to go along with sleevi#34 for the BRs. * Additional cleanups and markdownlint compliance (#34) * Additional cleanups and markdownlint compliance This commit updates the BR.md doc with the following changes: * Removes all instances of two adjacent spaces, except when used for indentation * Removes all instances of two adjacent blank lines * Fixes all markdownlints, including spaces around lists, spaces around headings, and tags on fenced blocks. It also fixes a few other pieces of miscellany, such as paragraphs which were not sufficiently indented to semantically fall inside the list in which they are intended to fall, and fencing code blocks which should have been fenced. It does not address two markdownlints: There are still multiple H1 headings, and there are a few places where markdown believes that unordered list bullets should be unindented (but doing so would change the semantics of the document). * Harmonize styles further This is a series of small list formatting cleanups to ensure proper display. However, it does renumber Section 8.5.5 of the EVGs to use Arabic numerals for the requirements, aligning with the other requirements in Section 8.5, instead of using capitalized letters for the list. There are no internal references to those requirements, and so this should be safe. * Remove stray footnote During the SC26 cleanup work, there was a stray footnote that got left in which rendered incorrectly, relating to Section 3.2.2.6 and wildcards. This correctly removes it. Although we do support footnotes in the PDF and Docx writers, and we do use them, Section 3.2.2.6 was modified during SC26 to make the normative requirement clearer and part of the text, rather than as a footnote. * More cleanups This aligns the NCSSRs with the style of the EVGs and BRs, which is that lists use single spacing, not double. It aligns the definitions of the NCSSRs with that of the EVGs and BRs, of keeping the colon of a definition as non-emphasized text. * Fix a few stragglers from section references in the BRs We had a few BR Section X or Section X of these Baseline Requirements that I'd missed. * Update artifact name to include SHA-1 This hopefully will make it easier for people to review this PR as it progresses, by being able to determine which commit a converted document was associated with. * More consistency fixes This further aligns the documents to consistently: - Use one space after colons or other punctuation (other than period) - Code-escape ASN.1 field names and values * [WIP] Attempt to enable redline generation * Fix indent in section 8.4 (B) of the EVGs * Update build-draft-docs.yml Update to v2 of the action, and set draft mode for everything but that landed to the SCWG main repository. * Switch to explicit v2.0.0 rather than v2 In hindsight, this avoids any potential breakage in the future if there's an uprev of build-guidelines-action that subtly breaks things. Given that we don't currently regression test the generated files, this seems more likely (such as a break in the template or updated Pandoc minor version), so until we have that in place, I'll use an explicit full version. * Add languages to fenced codeblocks No functional change, but ensures that the fenced blocks have an appropriate syntax/language set. The set of names is adopted from the GitHub/Linguist supported languages. * Incoporate changes from SC39v3 and align other links Co-authored-by: Aaron Gable <aaron@aarongable.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Labels
baseline-requirements
Server Certificate CWG - Baseline Requirements
editorial
Editorial issues, such as incorrect section references, inconsistent title/section names, et c
Although correct in some variants of the artifacts produced, 3.2.2.4.18/.19 gets awkward in format in that the list removes line breaks in the Word version.
For example, compare this screenshot of the GitHub rendered markdown:
With this screenshot as it appears in the PDF
The text was updated successfully, but these errors were encountered: