summaryrefslogtreecommitdiff
path: root/spec/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'spec/README.md')
-rw-r--r--spec/README.md39
1 files changed, 39 insertions, 0 deletions
diff --git a/spec/README.md b/spec/README.md
new file mode 100644
index 0000000000..16752c70de
--- /dev/null
+++ b/spec/README.md
@@ -0,0 +1,39 @@
+# Scala Language Reference
+
+First of all, the language specification is meant to be correct, precise and clear.
+
+Second, editing, previewing and generating output for the markdown should be simple and easy.
+
+Third, we'd like to support different output formats. An html page per chapter with MathJax seems like a good start, as it satisfies the second requirement, and enables the first one.
+
+## Editing
+
+We use redcarpet 3.1 and jekyll 2 (currently in alpha) to generate the html. Essentially, this is what github pages use.
+
+## Building
+
+Travis CI builds the spec automatically on every commit and . To preview locally, run `bundle exec jekyll serve -d build/spec/ -s spec/ -w --baseurl=""` and surf to http://0.0.0.0:4000/. Jekyll will rebuild as you edit the markdown, but make sure to restart it when you change `_config.yml`.
+
+## General Advice for editors
+
+- 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`.
+- MathJAX errors will appear within the rendered DOM as span elements with class `mtext` and style attribute `color: red` applied. It is possible to search for this combination in the development tools of the browser of your choice. In chrome, CTRL+F / CMD+F within the inspect element panel allows you to do this.
+
+
+### 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_`.
+
+
+### 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+].