Reorganize and improve upon the docs on sections and definitions.
Review Request #11704 — Created July 6, 2021 and submitted
The section definitions were kind of all over the place, but have slowly
been progressing toward a more organized set of definitions on the types
of sections, the rules around headers, and common options.
This change improves this considerably. The "Section and Header Formats"
page is now "Section Definitions" (name may still be in flux), which
starts by providing an overview of sections, then better defines the
format for section headers, and then goes into full detail on the types
Some of that full detail was already there, but is now cleaned up. The
Metadata and Preamble content sections are now better defined. Common
options are now listed separately for container and content sections
here in one place.
This simplifies the Section Hierarchy page (which was formerly "DiffX
Sections"). The preamble and metadata sections can now heavily rely upon
the standard definitions, instead of having to repeat things.
Built the docs and checked through to make sure the links worked, the
text was correct (though this needs a second pair of eyes), and that
there were no new spelling errors.
- Added a more detailed section on option parsing, which provides more explicit rules and examples.
- Added a section on the section order, along with a formal state tree for validating section order.
- Added a note drilling in the indentation logic for content sections, and providing an explanation as to why the order is important.
Revision 2 (+784 -370)
Checks run (2 succeeded)