Don't use mathjax in code examples in the Scala language specification

[s5k6]

I personally find it unfortunate to use mathjax in documents like [1].

• Cut'n'paste from Examples leaves me with

  val x  = mylist match { case x :: xs => (x, xs) }
  val x = x ._1
  val xs = x ._2
  

  dropping dollars and introducing spaces.

• The (potentially intended) distinction between (Scala) variables
  and (documentation) meta-variables is not consistent in the
  document.

• Suggests syntax that does not exist (x₁ gives illegal character
  '\u2081')

• Using mathjax introduces external dependencies, takes longer to load.

---

[1] http://scala-lang.org/files/archive/spec/2.11/04-basic-declarations-and-definitions.html

[SethTisue]

How do you propose that formulas be typeset?

[s5k6]

On 2016-Nov-27, Seth Tisue wrote with possible deletions:

How do you propose that formulas be typeset?

For source code examples, I would use plaintext only. In the following example, I see no benefit in using a mathjax $ sign:

val x$ = mylist match { case x :: xs => (x, xs) }
val x = x$._1
val xs = x$._2

I would even resort to plain text if this does not abstract over variable names any more, with a decent description it should be clear what the variable parts are. E.g., in Section 4.2 Variable Declarations, unicode ‘·’ is already used to denote grammar terminals (this is good)

Dcl            ::=  ‘var’ VarDcl
PatVarDef      ::=  ‘var’ VarDef
VarDcl         ::=  ids ‘:’ Type
VarDef         ::=  PatDef
                 |  ids ‘:’ Type ‘=’ ‘_’

But the following

def $x$: $T$
def $x$_= ($y$: $T$): Unit

I would rewrite as

def x: T
def x_= (y: T): Unit

because it is clear from the context that x, y and T are meta-variables. If really necessary, I would resort to using plain HTML markup, e.g.,

def <em>x</em>: <em>T</em>
def <em>x</em>_= (y: <em>T</em>): Unit

To further make a distinction between the emphasis for “type declaration”, and the meta variables, one could use CSS

code em {
    color: red;
}

and

<p>A <em>type declaration</em> <code>type <em>t</em>[<em>tps</em>]
>: <em>L</em> <: <em>U</em></code> declares <code><em>t</em></code> to be an
abstract type with lower bound type <code><em>L</em></code> and upper bound
type <code><em>U</em></code>.</p>

or even

span.var {
    color: blue;
    font-style: italic;
}

<p>A <em>type declaration</em> <code>type <span
class="var">t</span>[<span class="var">tps</span>]
&gt;: <span class="var">L</span>
&lt;: <span class="var">U</span></code> declares
<span class="var">t</span> to be an abstract type with lower bound
type <span class="var">L</span> and upper bound
type <span class="var">U</span>.</p>

All these approaches would make the document self-contained, load faster, make its structure simpler, avoid the problems of getting the fonts consistent on all platforms (which is not the case now), etc.

[SethTisue]

For source code examples, I would use plaintext only

Pull requests that reduce or eliminate the use of Mathjax in source code examples would be very welcome, I think — that seems like the highest priority part of this.

[heathermiller]

I agree that for source code examples, plain text would be preferable.

However, the specification is something of an academic document, which uses specific notations, and in many cases I think Mathjax is actually the most appropriate way to typeset some things. So I wouldn't support a wholesale replacement of Mathjax... Just where it's unnecessary, like source code examples.

[SethTisue]

I've changed the issue description to just cover the part of this we all seem to agree on.

[SethTisue]

note to first-time contributors: although the spec is published on scala-lang.org, the actual files containing the spec are in the scala/scala repo, at https://github.com/scala/scala/tree/2.13.x/spec

[sake92]

Closed in scala/scala#7432 ? (replaced with KaTeX)
For reference, old version takes 6-7 seconds to load, and new one 1-2 seconds. (section types, one of the most math-heavy sections)