diff options
author | Iain McGinniss <iainmcgin@gmail.com> | 2012-10-17 22:18:13 +0100 |
---|---|---|
committer | Iain McGinniss <iainmcgin@gmail.com> | 2012-10-17 22:18:13 +0100 |
commit | 5e2a7881337e008a7de79914646ebe3b4fcd993e (patch) | |
tree | 711beb32aff6e24149cfe0da97f1c8cb9a2fd5fc /README.md | |
download | scala-5e2a7881337e008a7de79914646ebe3b4fcd993e.tar.gz scala-5e2a7881337e008a7de79914646ebe3b4fcd993e.tar.bz2 scala-5e2a7881337e008a7de79914646ebe3b4fcd993e.zip |
preface and lexical syntax chapter converted, other chapters
split into their own files
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000000..4c078b8bae --- /dev/null +++ b/README.md @@ -0,0 +1,94 @@ +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 +---------------------------------- + +### 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. + +### Macro replacements: + +- 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. +- 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` ``. + + +### 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
\ No newline at end of file |