Summary

Reorganize and improve upon the docs on sections and definitions.

Review Request #11704 — Created July 6, 2021 and submitted July 11, 2021, 2:40 a.m.

Information

Owner

chipx86

Repository

DiffX

Branch

master

Bugs

Depends On

~~11703~~

Blocks

11705

Reviewers

Groups

diffx

People

Description

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.

Testing Done

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.

Commits

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

Summary

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

Issues

Description	From	Last Updated
Maybe specify that keys and values may only be alphanumeric?	david	July 8, 2021, 3:01 p.m.
If spaces are added after, I feel like there's some ambiguity here regarding encodings. For example, perhaps the preamble is …	david	July 8, 2021, 2:55 p.m.

flake8 passed.

JSHint passed.

Depends On:

+	~~11703 - Remove several section spec subsections from the table of contents.~~

docs/spec/section-format.rst (Diff revision 1)

Show all issues

Maybe specify that keys and values may only be alphanumeric?

chipx86 July 7, 2021, 10:58 p.m.

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

chipx86 July 8, 2021, 3:43 p.m.

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.

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?

chipx86 July 7, 2021, 10:58 p.m.

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.

Change Summary:


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.

Commits:

	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.	a926c0c3b673bd04dae0ee979ed79c5c42adcc00
	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

Diff:

Revision 2 (+784 -370)

Show changes

	docs/spec/encodings.rst
	docs/spec/section-format.rst
	docs/spec/sections.rst

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

Status: Closed (submitted)

Change Summary:

Pushed to master (d312907)