Spec.: ASCII or Unicode quoting intended in code examples?

[Daniel Barclay]

The README.md file for the Scala language specification says (at least on the 2.13.x branch):

The [U]nicode left and right single quotation marks (‘ and ’) have been used in place of `and ' ...

and the main text and the grammar BNF sections do use those Unicode quotes.

However, the code examples use ASCII ` and ' in text in code comments.

Is the intent:

1. that code examples can (or should) use those ASCII character for quotes, or
   
2. that code examples should use Unicode quotes too? 

(I'm asking because I'm creating a PR to fix a couple of inconsistent pairs of quotes in the text.

If case 1 is intended, I'll add something to the read-me file to try to clarify that; if case 2 is intended, I'll change the quotes in the examples.)

Thanks,
Daniel

[Naftoli Gugenheim]

I wonder if the text is before the PDF was converted to markdown and the ASCII is from then?

--
You received this message because you are subscribed to the Google Groups "scala-internals" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scala-interna...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Simon Schäfer]

---- On Sat, 05 Nov 2016 18:35:42 +0100Daniel Barclay <danielba...@gmail.com> wrote ----

The README.md file for the Scala language specification says (at least on the 2.13.x branch):

The [U]nicode left and right single quotation marks (‘ and ’) have been used in place of `and ' ...

and the main text and the grammar BNF sections do use those Unicode quotes.

However, the code examples use ASCII ` and ' in text in code comments.

Can you give an example where you found this?

Is the intent:

1. that code examples can (or should) use those ASCII character for quotes, or
   
2. that code examples should use Unicode quotes too? 
   

(I'm asking because I'm creating a PR to fix a couple of inconsistent pairs of quotes in the text.

If case 1 is intended, I'll add something to the read-me file to try to clarify that; if case 2 is intended, I'll change the quotes in the examples.)

The combination of ` and ' comes from LaTeX and have no meaning in Markdown.

[Daniel Barclay]

Simon Schäfer wrote:

---- On Sat, 05 Nov 2016 18:35:42 +0100Daniel Barclay <danielba...@gmail.com> wrote ----

The README.md file for the Scala language specification says (at least on the 2.13.x branch):

The [U]nicode left and right single quotation marks (‘ and ’) have been used in place of `and ' ...

and the main text and the grammar BNF sections do use those Unicode quotes.

However, the code examples use ASCII ` and ' in text in code comments.

Can you give an example where you found this?

I see 6 code blocks that have ASCII ` and ' in text in code comments:

In 02-identifiers-names-and-scopes.md:

The following program illustrates different kinds of bindings and
precedences between them.

```scala
package p {                   // `X' bound by package clause
import Console._              // `println' bound by wildcard import
object Y {
  println(s"L4: $X")          // `X' refers to `p.X' here
...

In 04-basic-declarations-and-definitions.md:

The following type parameter clauses are illegal:

```scala
[A >: A]                  // illegal, `A' has itself as bound
...

and two other code blocks.

In 06-expressions.md:

Examples of anonymous functions:

```scala
...
() => { count += 1; count }        // The function which takes an
                                   // empty parameter list $()$,
                                   // increments a non-local variable
                                   // `count' and returns the new value.
...

In  11-annotations.md:

  * ...For instance, the following member definitions are legal:

    ```scala
    type A { type T }
    type B
    @uncheckedStable val x: A with B // volatile type
    val y: x.T                       // OK since `x' is still a path
    ```

(None of the code blocks use the Unicode left and right single quotes in their comments.)

Is the intent:

1. that code examples can (or should) use those ASCII character[s] for quotes, or
   

1. that code examples should use Unicode quotes too? 
   

(I'm asking because I'm creating a PR to fix a couple of inconsistent pairs of quotes in the text.

If case 1 is intended, I'll add something to the read-me file to try to clarify that; if case 2 is intended, I'll change the quotes in the examples.)

The combination of ` and ' comes from LaTeX and have no meaning in Markdown.

No, they didn't seem to be for Markdown.

My theory was that someone was just using those characters to try to represent left and right single quotes in ASCII "manually" (that is, for the reader to see as opening and closing single quotes), and that maybe the code examples intentionally used those rather than actual left and right single quotes because they'd be more likely in actual code comments than non-ASCII Unicode characters might be.

(By the way, what's their meaning in LateX?  Generating paired left and right quotes, or, say, making some font change?)


In any case, what's the current intent (of the authors/maintainers of the specification)?

(Should the read-me text be modified to avoid implying that the examples aren't in the intended form (for code examples)?  Or possibly should the examples be modified to match what the read-me text says?  Or something else?)


Thanks,
Daniel

[Simon Schäfer]

---- On Mon, 07 Nov 2016 00:43:44 +0100Daniel Barclay <danielba...@gmail.com> wrote ----

Seems to be an oversight. There was an automatic conversion from the LaTeX document to Markdown, which seems to have missed the quotation marks in code blocks.

Is the intent:

1. that code examples can (or should) use those ASCII character[s] for quotes, or
   
2. that code examples should use Unicode quotes too? 
   

(I'm asking because I'm creating a PR to fix a couple of inconsistent pairs of quotes in the text.

If case 1 is intended, I'll add something to the read-me file to try to clarify that; if case 2 is intended, I'll change the quotes in the examples.)

The combination of ` and ' comes from LaTeX and have no meaning in Markdown.

No, they didn't seem to be for Markdown.

My theory was that someone was just using those characters to try to represent left and right single quotes in ASCII "manually" (that is, for the reader to see as opening and closing single quotes), and that maybe the code examples intentionally used those rather than actual left and right single quotes because they'd be more likely in actual code comments than non-ASCII Unicode characters might be.

(By the way, what's their meaning in LateX?  Generating paired left and right quotes, or, say, making some font change?)

The meaning is single left and right quotation marks.

In any case, what's the current intent (of the authors/maintainers of the specification)?

(Should the read-me text be modified to avoid implying that the examples aren't in the intended form (for code examples)?  Or possibly should the examples be modified to match what the read-me text says?  Or something else?)

I guess you are the first one who cares. ;) Just replace them with the Unicode ones, then it is consistent everywhere.