Jekyll generated html in spec/ directory

To avoid confusion, removing artifacts for
currently unsupported targets (pdf/single-page html).

I'd like to bring those back, but in the mean time let's avoid distractions.

Add Travis build.

1 files changed, 238 insertions, 0 deletions

diff --git a/spec/README.md b/spec/README.md
new file mode 100644
index 0000000000..84e9d6abc9
--- /dev/null
+++ b/spec/README.md
@@ -0,0 +1,238 @@
+# Scala Language Reference as Markdown
+
+I'm working towards making this the official Scala Reference.
+I'm migrating the pandoc setup to something that can easily be maintained and viewed as-is on github.
+
+I'd like a lightweight setup that produces an html + mathjax version of the markdown in this repo on every commit. Should be easy with Travis CI. Eventually, we should also generate a pdf, but the main priority is ease of maintenance, readability on github. 
+
+This spec should now also be up to date with the latex one at scala/scala-dist, which will be decommissioned.
+
+Notes to self:
+- http://docs.mathjax.org/en/latest/start.html
+- http://doswa.com/2011/07/20/mathjax-in-markdown.html
+
+# Scala Language Reference as Pandoc Markdown - Original Notes
+
+TODO: this needs to be updated
+
+## Prerequisites
+
+In order to build the scala reference, you will require the following
+software packages:
+
+- Pandoc v1.11.1 or higher (<http://johnmacfarlane.net/pandoc/>)
+  you can install this using cabal:
+
+      ```
+      cabal update
+      cabal install pandoc
+      ```
+
+- TeX-Live (<https://www.tug.org/texlive/>), in order to build the pdf
+version of the specification.
+
+- The luximono font - this does not ship with TeX-Live by default due to
+  license restrictions, but it can be easily installed using
+  the ["getnonfreefonts" script](https://www.tug.org/fonts/getnonfreefonts/).
+  A short guide on using this to get luximono can be found on the 
+  TeX Stackexchange [here](http://tex.stackexchange.com/questions/22157/how-to-use-the-luximono-font-with-tex-live).
+
+- The Heuristica font - this is an extension of the free version of the Adobe
+  Utopia font. This must be installed as a system font for the PDF to
+  build, and you can find the appropriate font package for your system
+  here: <https://code.google.com/p/evristika/>
+
+
+## General Advice for editors
+
+- All files must be saved as UTF-8: ensure your editors are configured
+  appropriately.
+
+- 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.
+
+- 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.
+
+
+## Useful tools
+
+I have found the following tools to be useful for viewing and testing the
+output of the various builds:
+
+- The [Markdown Preview](https://chrome.google.com/webstore/detail/markdown-preview/jmchmkecamhbiokiopfpnfgbidieafmd) extension for Chrome, for viewing
+markdown files locally in the way GitHub renders it 
+(you must enable viewing of local file urls for the extension). This is
+useful for previewing markdown changes before comitting them, though it
+will not render many of the Pandoc specific extensions.
+- The [Readium](https://chrome.google.com/webstore/detail/empty-title/fepbnnnkkadjhjahcafoaglimekefifl) app for Chrome, for viewing epub3
+files. This actually uses MathJAX to render the math elements on demand
+for each page of the ebook.
+- The [UnicodeMath](https://github.com/mvoidex/UnicodeMath) plugin for Sublime 
+Text. This is helpful if you are familiar with LaTeX macros for mathematical 
+symbols, as you may type the macro and have it automatically converted to the 
+equivalent unicode symbol (if it exists). This can be installed through
+the [Package Control](http://wbond.net/sublime_packages/package_control) 
+Sublime Text plugin.
+
+
+## Known issues and outstanding tasks
+
+Please see the issue tracker at <https://github.com/iainmcgin/scala-ref-markdown/issues>.
+
+
+## Fixing known build errors / warnings
+
+### I am seeing `process\_defaultadd: n=-1 tag.data='NGENRE' level=0` every time I build the spec
+
+Apparently this is due to a bug in the bibutils C library which was fixed,
+and occurs if you have built pandoc from source. You must force a recompilation 
+of a few Haskell libraries for the fixed bibutils library to be used. Simply 
+run:
+
+    ```
+    cabal update
+    cabal install --reinstall --force hs-bibutils citeproc-hs pandoc
+    ```
+
+
+## Fixing rendering errors
+
+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.
+
+
+## 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
+reasonable compromise I found 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
+
+ 1. first entry
+ 1. ...
+ 1. last entry
+