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.
|