Uploaded image for project: 'Technical Advisory Board'
  1. Technical Advisory Board
  2. TAB-1301

Ouline sectioning leaves single subdivisions

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: New
    • Priority: Trivial
    • Resolution: Unresolved
    • Affects Version/s: TOSCA Simple Profile in YAML Version 1.0
    • Fix Version/s: None
    • Component/s: None
    • Labels:
      None
    • Environment:

      Style

    • Proposal:
      Hide

      Correct the subsections as suggested with the possible exception of 5.9.1.

      Show
      Correct the subsections as suggested with the possible exception of 5.9.1.

      Description

      The following sections are single subsections following a parent section:

      2.1.1, 2.7.1, 3.4.1, 4.5.1, 5.9.1, 6.2.1, 8.2.1, 11.1.1.

      This happens often enough that I decided perhaps the rules on outlining have changed. To investigate that possibility, I turned to the Chicago Manual of Style, 15th edition, which reads in relevant part:

      *****
      1.73 Number of subheads. When a section of text is subdivided, there should ordinarily be at least two subsections. A single subhead in a chapter or a single B-level subhead under an A-level subhead may be viewed as illogical or asymmetrical. (There are cases, however, when a single subdivision is needed.)
      *****

      To my disappointment, the editors don't offer any advice on "...when a single subdivision is needed."

      In order, I offer the following observations:

      2.1.1 - Does not seem to follow on from 2.1, which is the "hello world" example. Not only is it a different topic, it has no connection to the content of its parent. Suggest 2.2?

      2.7.1 - Reads in part: "The following YAML snippet shows the definition of the custom relationship type used in the previous section."

      If you lose 2.7.1, heading and the first sentence, then the content blends in with the content of 2.7. Yes? Which is consistent with most of your other examples, that is they occur in the same subsection.

      3.4.1 - Required Keynames - looks like a missed editing move. 3.4 TOSCA Metamodel reads (in full) - "This section defines all modelable entities that comprise the TOSCA Version 1.0 Simple Profile specification along with their keynames, grammar and requirements."

      OK, so all the "modelable entities" are contained in 3.4.1 Required Keynames? In other words, there should be 3.4.1 + 3.4.2 and I assume other subsections to capture keynames, grammar and requirements. Yes? Or is this a missed move of the content elsewhere?

      4.5.1 get_attribute - The parent element, 4.5 Attribute Functions reads as though there is more than one attribute function. Except that there is only one and that is get_attribute. Yes?

      So, why not 4.5 Attribute Fuction: get_attribute and you lose 4.5.1 by combining it with the present text, re-cast to say attribute function in the singular?

      BTW, that moves 4.5.1.1, 4.5.1.2, 4.5.1.3 and 4.5.1.4 up in the order.

      5.9.1 tosca.groups.Root - Another plural heading, 5.9 Group Types, when in fact there is only one member of that group.

      Yes, I see the note that future work will add more groups but they aren't there now. This is the only potentially defensible case I have seen.

      6.2.1 Example - An example for 6.2 TOSCA Meta File - to be consistent with other examples, lose the separate heading.

      8.2.1 tosca.capabilities.Container.Docker - another example of a single entity following a plural title, 8.2 Capability Types. And the following subsections should all be at the same level in any event.

      Plus note in 8.2 "This section contains are non-normative Capacity"

      I think you meant: "This section contains non-normative Capacity..." Yes?

      11.1.1 Declarative considerations - Is there some reason to separate the material in 11.1.1 from that in 11.1? If there is, it isn't evident. combine the two for a more coherent presentation.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              patrick Patrick Durusau
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated: