Explain nested nature of dotted key notation

[Suhoy95]

Issue #701 point 9

Signed-off-by: Ilya Sukhoplyuev suhoy@gramend.ru
(Gramend R&D and Innopolis University, SNE master)

[Suhoy95]

I guess I have got the idea of the example

[Suhoy95]

I am not sure that we should keep this paragraph. It seems redundant

[ChristianSi]

I agree that the current remarks on dotted keys might be confusing, but I'm not quite convinced that this PR is the best way to resolve the potential confusion.

A deeper problem in the spec is that the "Keys" section comes quite early in the document, while the "Table" section is defined much later. But in order to understand what a key is, you need at least an implicit understanding of what a table is – though, of course, you cannot understand tables without at least a vague understanding of key/value pairs (which are defined even earlier than keys).

The "Key/Value Pair" section starts with: "The primary building block of a TOML document is the key/value pair."

I'm not sure that's correct. Arguably tables (and arrays of tables) are the highest, the primary structure in a TOML document, key/value pairs are second, and keys as well as values are third.

So key/value pairs are conceptually in the middle, which makes it a bit strange that the spec starts with them. A more principled approach would be to proceed either top down or bottom up. Assuming a top-down approach, the sections in the spec should be reordered as follows:

1. Preliminaries (unchanged):

   Example
   Spec
   Comment

2. Block-level structures and their immediate constituents:

   Table
   Array of Tables
   Key/Value Pair
   Keys (better rename to "Key" for consistency with other headings)

3. Value types:

   String
   Integer
   Float
   Boolean
   Offset Date-Time
   Local Date-Time
   Local Date
   Local Time
   Array
   Inline Table

4. Concluding sections (unchanged):

   Filename Extension
   MIME Type
   Comparison with Other Formats
   Get Involved
   Wiki

If we do it like this, the definitions and explanations related to dotted keys could be completely contained in the "Keys" section (or maybe add a new "Dotted Key" section?), while currently they are spread over the "Keys" and "Table" section, with some redundancy between the two. And since Tables are already defined at that point, we could make the remark

Dotted keys define everything to the left of each dot as a table.

immediately when introducing dotted keys. (Currently that remark is in the "Table" section, near the end of the document, while the initial explanation of dotted keys says much more vaguely: "This allows for grouping similar properties together.")

The sketched re-organsation of the spec would be a somewhat bigger change, but I think it's a more principled solution than introducing even more redundancy in the treatment of dotted keys.

[Suhoy95]

@ChristianSi , Yeah I think the similar way.

But I am prefer more nested structure with 1-6 header, it can make it more verbose and intuitive:

0. Preamble
1. Example
2. Spec
    2.0 Comment
    2.1 Basic types
        2.1.0 Boolean
        2.1.1 Integer
        2.1.2 Float
        2.1.3 String (`# it is cool that String comes before Keys`)
    2.2 Table
        2.2.1 Key/Value Pair (`# because it is part of the Table type`)
        2.2.2 Keys syntax (better rename to "Key" for consistency with other headings)
        2.2.3 Inline Table (special syntax)
    2.3 Array
        2.3.0 Array of Tables (special syntax)
    2.4 Date and Time
        2.4.0 Offset Date-Time
        2.4.1 Local Date-Time
        2.4.2 Local Date
        2.4.3 Local Time
3. Environment related points (`# I do not know how to name it better`)
    3.0 Filename Extension
    3.1 MIME Type
4. Comparison with Other Formats
5. Community
    5.0 Get Involved
    5.1 Wiki

As example, I am following the bottom to top, but we can add hint\remarks to point about Table type basis and facilitate understanding.

And yes, current solution is more like short hack to fix it right now, but if we do not hurry, we can refactor this PR when free time will be found

[Suhoy95]

Hey, here is dirty proof-of-concept: toml.pdf

[ChristianSi]

Suhoy95 Yeah, something like that would be fine with me. Not sure how realistic it is that such a big re-organization will happen before 1.0 is released, though.

Also note that the proposal to re-arrange the TOML spec should be made and discussed in a separate (new) issue, as it's not really about the "nested nature of dotted key notation" anymore.

[Suhoy95]

Now, I guess it is duplicated of #706. #706 looks more accurate