Figure out how to handle section header links, intros, and rules

[ehuss]

There has been some uncertainty about how to handle rule identifiers, introductions, and section headers. We should figure out how these should interact and be formatted.

Section identifiers

In some cases, authors have been adding parent rule names inside a section, with subsequent paragraphs using more specific rule names. For example:

## Template string arguments

r[asm.ts-args]

r[asm.ts-args.syntax]
The assembler template uses the …

I think the intent here is that the asm.ts-args rule name is associated with the section and is not intended as a specific rule.

My intent with rule names was that each rule identifies a specific, narrowly scoped behavior of the language. Then, rule names can be associated with a test that illustrates that behavior. It's not clear to me what the purpose of these parent rule identifiers is, since in this example it does not contain a specific rule (or even any direct text).

A variant of this is this example:

#### Primitive Representation of Field-less Enums

r[layout.repr.primitive.enum]

For [field-less enums], primitive representations set the size and alignment to
be the same as …

Here the author intended layout.repr.primitive.enum to be associated with the section, with the text below to be an introduction. However, this left the following paragraph dangling without a rule. The paragraph reads to me as specifying a specific behavior, so I would expect it to have a rule associated with it and a test.

What is an introduction?

My intention with introductory paragraphs was to be an introduction to a chapter that explains what the chapter is about, without necessarily defining any rules. It may define some terminology, or otherwise set up what is about to come next, but it should not specify any behaviors. My litmus was to be "if is this testable, then it should be a rule, not an introduction".

However, in practice, quite a few "intro" sections have been added which include specific behaviors that are testable. I think we should narrow the meaning of an introduction, and possibly remove the .intro rules entirely. The intro rules will be causing problems with the test coverage, since if they aren't testable, they won't be able to be associated with a test, and if they are, then they aren't really an introduction.

Possible solutions

• Keep as-is.
  • Don't include these "parent" rules in the test report.
    • This causes issues with ensuring that parent rules don't actually have any text associated with them. If it is excluded from the test report, and it has text defining language behavior, then we have inadvertently circumvented our coverage scanning.
• Move section rules to become the ID of the section header (probably using markdown identifiers).
  • This will cause a lot of churn dealing with fragment redirects.
  • Uncertain how this should be rendered. By default, using markdown header IDs will not be rendered.
• Remove .intro rules.
  • Content that is really an introduction can come just after the section header, and doesn't necessarily need a rule identifier.
  • We'll need to be careful to understand which paragraphs have actual testable rules, and which ones do not. That may be hard to interpret.