Reorganize and improve upon the docs on sections and definitions.

Review Request #11704 — Created July 6, 2021 and submitted

Information

DiffX
master

Reviewers

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
of sections.

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.

Summary ID
Reorganize and improve upon the docs on sections and definitions.
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 of sections. 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.
14f3c05e3ea39fad6890e9d7947f64f671b82cc5
Description From Last Updated

Maybe specify that keys and values may only be alphanumeric?

daviddavid

If spaces are added after, I feel like there's some ambiguity here regarding encodings. For example, perhaps the preamble is …

daviddavid
chipx86
david
  1. 
      
  2. docs/spec/section-format.rst (Diff revision 1)
     
     
     
     
     
    Show all issues

    Maybe specify that keys and values may only be alphanumeric?

    1. Additional characters for vlaues are permitted (/, ., -, _). The format is covered below this paragraph.

    2. Cleaned this up quite a bit, breaking out option parsing into its own section, expanding valid characters for keys for future compatibility, and adding more explicit parsing rules.

  3. docs/spec/section-format.rst (Diff revision 1)
     
     
     
    Show all issues

    If spaces are added after, I feel like there's some ambiguity here regarding encodings. For example, perhaps the preamble is in big5. Is the indentation 0xa1 0x40 0xa1 0x40 0xa1 0x40 0xa1 0x40 or 0x20 0x20 0x20 0x20?

    1. It's 0x20 0x20 0x20 0x20.

      The important part is ensuring that non-DiffX parsers don't get tripped up by any character in column 0 that might it might interpret as syntax it wants to parse. So the encoded data is indented by ASCII spaces.

      I can add some notes on this and an example.

  4. 
      
chipx86
david
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to master (d312907)