AsciiDoc weak for technical documents with interleaved content like spec and rationale

I have written many technical documents over the years, including architecture specs (instruction set, control and status registers, microarchitecture), performance tuning guides, many proposals (some of which got built, some not), tutorials, how to write white papers...

Many of these documents had interleaved content type. For example:

• Normative text in the specifications
  • e.g. architectural rules that hardware implementations must follow.
  • e.g. rules that software must follow
• Formal specifications (as opposed to human readable)
• Descriptive text
• Rationale: why the specification did one thing rather than another
  • suggestions for future extensions
• Advice - for both hardware and software implementations.
• Sample code and RTL
• Performance recommendations
• Comparative - e.g. the correspondence between feature X from competitor Y and the current proposal

We often want to all of the different content types distinguished in the text/publication. E.g. by different fonts or colors. Probably not all of the above varieties at the same time, but frequently normative versus rationale, and increasingly formal specifications.

AsciiDoc has only limited sways of indicating such distinctions. E.g. AciiDoc has sidebars. Also, AsciiDoc has "admonitions" : NOTE, TIP, IMPORTANT, CAUTION, WARNING. It is by no means clear whether a rationale should be mapped into a NOTE or a TIP, or something else.

(Formal specifications can be distinguished by code blocks for the formal specification language, although these are usually themselves accompanied by descriptive text.)

(As of yet I do not know how to add my own "admonition" types, or even to do something simple like changing the text displayed beside a NOTE to RATIONALE. at the very least, the name admonition is inappropriate.)

Worse, AsciiDoc sidebars and admonitions are considered to be subservient to the actual document. they do not appear in the Table of Contents (TOC). Section headings inside special text blocks are not processed.

While this may be OK for specification that has only a small amount of rationale text, in early-stage proposals the actual specification is often quite small compared to the discussion and rationale.

IMHO it is essential that at least some of the interleaved descriptive and rationale text appear in the table of contents. Some section/subset trees are entirely descriptive, not normative specification. Indeed, one can argue that the specification should be as small as possible.

Furthermore, often times the interleaved text needs specialized tables. for example, in code optimization guides I have often distinguished descriptions, and compact rules, as well as diagram/fgigures and code examples (HLL/assembly/pseudocode). Many technical publication systems can generate LOF (List of Figures) and LOT (List of Tables) as well as TOC (Table of Contents) - although AFAICT AsciiDoc supports neither LOF nor LOT, only TOC. My technical documents may need in addition "List of Code Tuning Rules", "List of Requirements", "List of Examples", ...

Because AsciiDoc lacks these features we often revert to kludgy workarounds like using NOTEs for RATIONALE. Mixing rationale and description together.