Chapter 3 - DSDL specification

[pavel-kirienko]

At a first glance it seems to be complete content-wise and the structure is probably the best I could muster without rewriting the whole thing from scratch again. I am going to re-read it again tomorrow and fix the remaining inconsistencies (especially inconsistent term usages) and missed details.

The most important task right now is to ensure that the DSDL specification is complete and all relevant aspects of the language are described unambiguously. I would like you to review the chapter and try and answer the following questions:

• Are all concepts of the language described clearly?
• Are there any terms or definitions that are used consistently? Please disregard their usage in other chapters for now.
• Are there any ambiguous or contradictory requirements or definitions?
• Is it possible to simplify the specification or reduce its verbosity by introducing new or more specific definitions?
• Can the number of forward references be substantially reduced by rearranging the sections?
• Are there sections that should be extended with examples?
• Is there any non-normative text that is not enclosed in shaded blue remark boxes or extracted into footnotes?

If you find bad wording, misspelled words, bad grammar, missing articles (sorry), and similar language-level errors, please ignore them for now unless they are also related to any of the above issues.

Don't look at the diff, it's huge and mostly meaningless; instead, use this prebuilt PDF: UAVCAN_Specification.pdf

After this PR is finished and merged, I am going to introduce a few sweeping changes in the document to fix inconsistent term usage and some formatting issues. The introductory chapter will be expanded with a very brief section on motivation (one or two sentences), and the section listing the document conventions also requires extension (for example, the DSDL chapter uses notation like Container_\<Element> for higher-order type parametrization, but it is not explicitly introduced anywhere yet). Also, I am hoping to bring the total number of pages under 100 (many a reader would be repelled by the three-digit number of pages) by changing the page geometry somewhat.

@kjetilkjeka @thirtytwobits please review.

[pavel-kirienko]

I seem to have either resolved or asked further questions on all of the raised issues except:

• https://github.com/UAVCAN/specification/pull/46#discussion_r277125331 (IEEE 754 constants)
• https://github.com/UAVCAN/specification/pull/46#discussion_r277125886 (mixed normative and non-normative sections)

I will be back to these around Wed/Thu; meanwhile, feel free to review my other changes.

[pavel-kirienko]

The sentence is a little hard to parse. Is this version still correct:

Yes. Fixed in https://github.com/UAVCAN/specification/pull/46/commits/17ef29d15bbadb4e3a8e308a1eed07f96f949195

[pavel-kirienko]

I seem to have resolved all of the outstanding issues. Here is a compiled doc: UAVCAN_Specification.pdf

(this PR is becoming very messy and hard to follow)

[thirtytwobits]

👍

[pavel-kirienko]

:+1:

@thirtytwobits LGTY?

[thirtytwobits]

Yes. LGTM. (sorry)