summaryrefslogtreecommitdiff
path: root/README.md
blob: 757e1a6134bdf63a467fed4ae67c2279ae12e9db (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
Scala Language Reference as Pandoc Markdown - Notes
===================================================

General
-------

- All files must be saved as UTF-8: ensure your editors are configured
  appropriately.
- Use of the appropriate unicode characters instead of the latex modifiers
  for accents, etc. is necessary. For example, é instead of \'e. Make use of
  the fact that the content is unicode, google the necessary characters if
  you don't know how to type them directly.
- Leave two empty lines between each section, regardless of level of nesting.
  Leave two empty lines at the end of every markdown file that forms a part
  of the main specification when compiled.

Conversion from LaTeX - Guidelines
----------------------------------

### Chapter conversion Checklist

1. Convert all `\section{...}`
1. Convert all `\subsection{...}`
1. Convert all `\subsubsection{...}`
1. Convert all `{\em ...}`
1. Convert all `\lstlisting`
1. Convert all `\lstinline`
1. Convert all `\code`
1. Convert all `\sref{sec:...}`
1. Convert all `\begin{itemize}`
1. Convert all `\begin{enumerate}`
1. Convert all `\example`
1. Convert all `\footnote`
1. Convert all `\paragraph`
1. Convert all `\begin{quote}`
1. Delete all `\comment{...}`
1. Convert all single quote pairs
1. Convert all double quote pairs
1. Look for manually defined enumerated lists (1. 2. 3. etc)
1. Remove `%@M` comments
1. Convert all extra macros (`\commadots`, etc)


### Code

Code blocks using the listings package of form

    \begin{lstlisting}
    val x = 1
    val y = x + 1
    x + y
    \end{lstlisting}


can be replaced with pandoc code blocks of form

    ~~~~~~~~~~~~~~{#ref-identifier .scala .numberLines}
    val x = 1
    val y = x + 1
    x + y
    ~~~~~~~~~~~~~~

Where `#ref-identifier` is an identifier that can be used for producing links
to the code block, while `.scala` and `.numberLines` are classes that get 
applied to the code block for formatting purposes. At present we propose to
use the following classes:

- `.scala` for scala code.
- `.grammar` for EBNF grammars.

It is important to note that while math mode is supported in pandoc markdown
using the usual LaTeX convention, i.e. $x^y + z$, this does not work within 
code blocks. In most cases the usages of math mode I have seen within
code blocks are easily replaced with unicode character equivalents. If
a more complex solution is required this will be investigated at a later stage.

#### Inline Code

Inline code, usually `~\lstinline@...some code...@` can be replaced with
the pandoc equivalent of

    `...some code...`{<type>}

where `<type>` is one of the classes representing the language of the
code fragment.

### Definitions

Pandoc supports definition lists, however these do not seem to be a good
semantic match for the numbered definitions in the reference. The only
compromise came up with here was to treat definitions like quotations:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> **Definition**
> Let $C$ be a class with template ...
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


### Macro replacements:

- While MathJAX just support LaTeX style command definition, it is recommended
  to not use this as it will likely cause issues with preparing the document
  for PDF or ebook distribution.
- `\SS` (which I could not find defined within the latex source) seems to be
  closest to `\mathscr{S}`
- `\TYPE` is equivalent to `\boldsymbol{type}'
- As MathJAX has no support for slanted font (latex command \sl), so in all
  instances this should be replaced with \mathit{}
- The macro \U{ABCD} used for unicode character references can be
  replaced with \\uABCD.
- The macro \URange{ABCD}{DCBA} used for unicode character ranges can be
  replaced with \\uABCD-\\uDBCA.
- The macro \commadots can be replaced with ` , … , `.
- There is no adequate replacement for `\textsc{...}` (small caps) in pandoc 
  markdown. While unicode contains a number of small capital letters, it is
  notably missing Q and X as these glyphs are intended for phonetic spelling,
  therefore these cannot be reliably used. For now, the best option is to
  use underscore emphasis and capitalise the text manually, `_LIKE THIS_`.
- `\code{...}` can be replaced with standard in-line verbatim markdown,
  `` `like this` ``.
- `\paragraph` (typically used for a non-numbered header) can be replaced by 
  a hard line break, which is a `\` followed immediately by a newline.
- `\TODO` can be replaced by a markdown comment `<!-- TODO: ... -->`


### Unicode Character replacements

- The unicode left and right single quotation marks (‘ and ’) 
  have been used in place of ` and ', where the quotation marks are intended
  to be paired. These can be typed on a mac using Option+] for a left quote
  and Option+Shift+] for the right quote.
- Similarly for left and right double quotation marks (“ and ”) in
  place of ". These can be typed on a mac using Option+[ and Option+Shift+].

### Enumerations

Latex enumerations can be replaced with markdown ordered lists, which have
syntax

    #. first entry
    #. ...
    #. last entry


Finding rendering errors
------------------------

- MathJAX errors will appear within the rendered DOM as span elements with
  class `mtext` and style attribute `color: red` applied.