Hanging paragraphs

Issue #310 wontfix
Nat Sakimura created an issue

There are a bunch of hanging paragraphs.

If we give a number for those, the current numbering changes, too.

What would be the impact to the test suite if we make this change?

Comments (9)

  1. Nat Sakimura reporter

    For example,

    5.2.2 Authorization server

    starts with a hanging paragraph followed by 5.2.2.1 and 5.2.2.2.

    Also, 5.2.3 has a hanging paragraph followed by 5.2.3.1 and 5.2.3.2.

  2. Joseph Heenan

    5.2.2.1 / 5.2.2.2 are entirely new sections since ID2, so not currently referenced at all in the tests - so I suspect it’s okay to do what you’re thinking.

  3. Edmund Jay

    The latest version shows the following hanging paragraphs:

    Baseline Profile

    5.2.2  => 5.2.2.0 or ( 5.2.2.1 and update existing ones)

    5.2.2 is referenced in the conformance suite but existing 5.2.2.1 - 5.2.2.3 are not so they can be renumbered without issue.

    Advanced Profile

    5.1 => 5.1.0 or (5.2.1 and update existing subsections)

    5.1 is not referenced and existing subsections are also not referenced so it could be changed to 5.2.1 without issue.

    5.2.2 => 5.2.2.0  or (5.2.2.1 and update existing)
    5.2.2 and existing 5.2.2.1 are referenced

    5.2.3 => 5.2.3.0 or 5.2.3.1
    5.2.3 is referenced but existing 5.2.3.1 – 5.2.3.2 are not referenced

    8.6 => 8.6.0 or (8.6.1 and update existing subsections)

    Both 8.6 and 8.6.1 are referenced.

    12.1 => 12.1.1 and renumber existing ones, None are currently referenced

    Appendix A => A.1 and renumbered existing subsequent examples , None are currently referenced

    So we need to decide whether to change to #.0 or #.1 subsections.

    Changing to #.0 subsections would not impact anything currently, but the HTML versions be tricky to make since the converted HTML version will need to be edited manually. The standard xml2rfc conversion tools start numbering at 1. The section numbers are currently stripped from the Markdown file before being fed into a Markdown to XML tool which will then convert to HTML. And it would make the spec look strange since some sections would start at 0 and some at 1.

    Changing to #.1 would require updating the referenced sections and existing referenced subsections in the conformance suite. Perhaps adding a draft revision number to the referenced section in the conformance suite would be the best solution since we can update the section numbers and the conformance suite can point to a specific section in a specific revision of the spec?

  4. Log in to comment