Clarify if basic strings must be wrapped in double-quotes specifically

[JoeUX]

I'm inferring from the spec's examples that basic strings must be wrapped in double quotes, but it never says so explicitly. Rather it just says "quotation marks" for basic strings and basic multi-line strings, while it says "single quotes" for literal strings.

"Quotation marks" and "single quotes" are not good contrast objects. If basic strings must be wrapped in double quotes, the spec should just say so. "Double quotes" and "single quotes" are the natural contrast objects, and the two types of quotes are normally distinguished in web development. Also, "quotation marks" is a cumbersome way to say quotes or double quotes.

(I didn't do a PR because I wasn't 100% certain that double quotes were required.)

[abelbraaksma]

I agree it's best to stick to a single way of describing quotation marks. Perhaps we ought to add a line in the main section where we put the definitions of used terms, and ideally interlink there on each use of the agreed upon term: https://github.com/toml-lang/toml/blob/master/README.md#user-content-spec

[ChristianSi]

Generally replacing "quotation mark" with "double quote" would be fine with me. However, considering that the ABNF is unambiguous, I would not consider it as overly important.

[eksortso]

Despite the clarity of the ABNF, it would be good to have some sort of glossary in the spec, preferably near the beginning. If there was a quick lookup for certain terms, then it would make writing a more explicit specification simpler, because then certain concepts would become clear a little sooner.

We can gather up all the talk about "tables" between the three different syntaxes for creating them under a single "table" entry, because no matter how it's defined, a table's a table's a table. We've seen quite a few tickets ask if that was the case. So it makes sense to say: a table is this, and here are ways to define them.

Similarly, we can draw distinctions between the definition of a table, which can be done in only one place in the document, and merely a reference to a table in a dotted key, which implies its creation but allows its key/value pairs to go elsewhere, depending on the syntax used. (I'm being a little pedantic here, but I'm trying to illustrate the things that we could write about in a glossary entry.)

This is just three terms, and important ones, I would say. But a glossary would make glomming onto TOML and its (somewhat ironic) intricacies a whole lot easier for newer folks. Imagine how much easier the specification would flow once these concepts are collected in one place, and how many fewer questions we'd see about our favorite obvious and minimal language.

[abelbraaksma]

Imagine how much easier the specification would flow once these concepts are collected in one place, and how many fewer questions we'd see about our favorite obvious and minimal language.

I couldn't agree more. Perhaps instead of "glossary", let's call it "definitions", and just hyperlink the usages of the terms used in the body of the text. Though this could go into vNext, it's currently pretty stable and clear, I think.

[JoeUX]

@ChristianSi Not everyone knows ABNF, and my thinking is that if you're going to have a natural language specification (e.g. an English language spec) it should be as clear as natural language allows.

Since "quote" and "quotation mark" are ambiguous in a universe where several quote glyphs exist, and slightly misleading when only one specific quote glyph is accepted, I'd just specify the glyph that is required and crack on to the harder stuff.

[ChristianSi]

@JoeUX Fair enough, but even "double quotes" is ambiguous. "Quoted", “quoted”, „quoted“, «quoted» are all different kinds of double quotes that are allowed in English or some other languages – and there are more. So, to be really unambiguous, we would have to write "ASCII double quotes" and "ASCII singles quotes". Which is of course possible, but here the reduction of ambiguity is accompanied by a certain reduction of readability.

But I take it, you mean writing something like "double quotes ("...")" and "single quotes ('...')" when these terms are mentioned for the first time? That would be fine with me.

[abelbraaksma]

Which is of course possible, but here the reduction of ambiguity is accompanied by a certain reduction of readability

That's why the proper place would be where we define what a newline is, so we can simply specify the actual Unicode code point once, and leave the text as is. Something like:

• where this spec uses the term "quotes" or "quotation marks" without further specification, it means either single or double quotes. A single quote is the Unicode codepoint xyz, a double quote zyx.

[pradyunsg]

There's 2 parts to this issue, as far as I can tell:

• the use of "quotation marks" is a bit ambiguous -- I think adding a (") should be sufficient to address this ambiguity. Nice catch @JoeUX! ^>^

• a discussion closer to Re-organization of sections in TOML documentation/specification  #704, that I'd prefer to revisit then.