toml-lang / toml

Tom's Obvious, Minimal Language
https://toml.io
MIT License
19.45k stars 847 forks source link

Make spec neutral regarding array-of-table naming style #938

Closed ChristianSi closed 1 year ago

ChristianSi commented 1 year ago

This PR is an outcome of https://github.com/toml-lang/toml/discussions/932. Right now the spec only uses the "plural" naming conventions in its array-of-tables examples. However, it is far from clear that this is the only legitimate convention in such cases. Consider as example:

[[planets]]
name = "Mercury"
aphelion = 0.466697
radius = 2440

[[planets]]
name = "Venus"
aphelion = 0.728213
radius = 6052

This might seem unintuitive and perhaps even confusing to the reader or editor of the TOML file, since each [[...]] section header is only followed by a single instance of the described item (a planet, in this case). This can be made clearer by using the "singular" naming convention instead, and prominent TOML users such as Cargo do indeed use the "singular" naming style for arrays of tables (in Cargo: [[bin]], [[example]], [[test]], and [[bench]]).

The spec, however, currently uses the "plural" naming style in all its array-of-table examples, which may give the impression that that's the normal and preferred naming style. This PR makes the spec "neutral" in that regard, by switching one example (the "product[s]" example) to singular style, while leaving the other example (the "fruits" example) in plural style. This should make it clearer that either style is fine.

Why modify the "products" rather than the "fruits" example? I have no strong preference here; I choose the former simply because it's the smaller change (it only has three section headers, while the "fruits" example has six). But I would be happy to adapt the latter instead if that's for some reason preferred.

ChristianSi commented 1 year ago

@pradyunsg @mojombo What do you think? Could you take a took and merge this if it's good?