From b71a2c1fa077e1bb29f83c5a5a755ff203aae974 Mon Sep 17 00:00:00 2001 From: Iain McGinniss Date: Wed, 31 Jul 2013 12:04:40 +0100 Subject: updated README.md - using newer Pandoc version - added list of useful tools - added link to issue tracker - general layout / markdown fixes --- README.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 78 insertions(+), 16 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 70b7b8bad3..d784e11811 100644 --- a/README.md +++ b/README.md @@ -7,35 +7,103 @@ Prerequisites In order to build the scala reference, you will require the following software packages: -- Pandoc v1.10.1 or higher (http://johnmacfarlane.net/pandoc/) -- TeX-Live (https://www.tug.org/texlive/) +- Pandoc v1.11.1 or higher () + you can install this using cabal: + + ``` + cabal update + cabal install pandoc + ``` + +- TeX-Live (), 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/ + here: 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 . + + +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{...}` @@ -93,6 +161,7 @@ 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 @@ -103,16 +172,15 @@ the pandoc equivalent of where `` 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: +reasonable compromise I found was to treat definitions like quotations: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -> **Definition** -> Let $C$ be a class with template ... -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + > **Definition** + > Let $C$ be a class with template ... ### Macro replacements: @@ -151,6 +219,7 @@ compromise came up with here was to treat definitions like quotations: - 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 @@ -160,10 +229,3 @@ syntax #. ... #. 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. - -- cgit v1.2.3