Re-organization of sections in TOML documentation/specification

[Suhoy95]

There is an description issue that key/value pair and table are described to far away from each other, which cause problem of misunderstanding (especially if you do not familiar with hash table)

As it was mentioned, there are top-down and bottom-up approach to describe something (and TOML particularly)

This proposal shows bottom-up approach:

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

Notes:

1. Comparison with Other Formats and Example(s) may be merged and put in the beginning. So regular TOML user will be able to easily get started with it (if they know one of other format).
2. I try to do just restructuring, but this discussion may cause more serious changes. I think that each sentence should be read and accordingly rewritten

The topic was touched in the notes (#701, Points 2, 3, 6) and popped up in #702 PR.

Proof-of-Concept: pdf and the separated PR (#703)

[Suhoy95]

As little crazy doc-writing thing: we may describe each statement of TOML specification inside sets of .toml-files (array of Tables: statement, ABNF, explanation, etc) and then generate appropriate format: Markdown, latex/pdf, HTML, ABNF-file, etc. with good references and Table of Content if it is applicable.

It smells like over-engineering, but makes thing fun.

[pradyunsg]

I'm not sure what the goal here is anymore -- we have toml-lang/toml.io#1 for creating a better user-facing documentation, if that's the intent here.

As for restructuring the sections, I think it could be useful to do. I've dabbled with the idea a couple of times myself, but I'm very wary of making such a change prior to 1.0 -- it's one more thing to do before 1.0, one more thing that could introduce issues (etc) -- I'm very much at a point where I'd much rather release the current spec as 1.0; and iterate on the remaining improvements after that.

As for having segments across multiple .toml files, that'll get "compiled" into formats -- let's not do that; it is very much over-engineering and simpler systems are better than complex one. :)

[ChristianSi]

I'm generally in favor of reorganizing the sections (in fact, I suggested it). But whether that should happen before or after 1.0 I leave to the maintainers' decision.

Indeed I'm very much in favor of getting 1.0 published quickly, which suggests postponing this.

[pradyunsg]

I'm on board for doing this, but as mentioned before I think this is best done as a post 1.0 task. :)

[pradyunsg]

Looking at this and the spec in some detail again, the current spec works pretty well. I don't think there's need for a drastic restructuring as has been proposed in this issue.

Thanks for the suggestion none the less @Suhoy95!