Merge pull request #146 from rgaiacs/syntax-highlighting-example

Syntax highlighting example
carpentries · Nov 16, 2017 · 8fad66a · 8fad66a
2 parents 3928e3f + 1ee9219
commit 8fad66a
Show file tree

Hide file tree

Showing 12 changed files with 163 additions and 76 deletions.
diff --git a/_config.yml b/_config.yml
@@ -74,5 +74,5 @@ exclude:
   - Makefile
   - bin
 
-# Turn off built-in syntax highlighting.
-highlighter: false
+# Turn on built-in syntax highlighting.
+highlighter: rouge
diff --git a/_episodes/02-tooling.md b/_episodes/02-tooling.md
@@ -128,7 +128,7 @@ is translated into:
 </body>
 </html>
 ~~~
-{: .source}
+{: .html}
 
 > ## Back in the Day...
 >

diff --git a/_episodes/04-formatting.md b/_episodes/04-formatting.md
@@ -137,7 +137,7 @@ which is rendered as:
 for thing in collection:
     do_something
 ~~~
-{: .source}
+{: .language-python}
 
 The class specified at the bottom using an opening curly brace and colon,
 the class identifier with a leading dot,
@@ -159,23 +159,70 @@ The [template]({{ site.template_repo }}) provides three styles for code blocks:
 ~~~
 {: .error}
 
-The following styles are all synonyms for `.source`;
-please use them where possible to indicate the type of source being displayed,
-in case we decide to adopt syntax highlighting at some point:
+### Syntax Highlighting
+
+The following styles like `.source`, but include syntax highlighting for the
+specified language.
+Please use them where possible to indicate the type of source being displayed,
+and to make code easier to read.
+
+`.language-bash`: Bash shell commands:
+
+~~~
+echo "Hello World"
+~~~
+{: .language-bash}
+
+`.html`: HTML source:
+
+~~~
+<html>
+<body>
+<em>Hello World</em>
+</body>
+</html>
+~~~
+{: .html}
+
+`.language-make`: Makefiles:
+
+~~~
+all:
+    g++ main.cpp hello.cpp -o hello
+~~~
+{: .language-make}
+
+`.language-matlab`: MATLAB source:
+
+~~~
+disp('Hello, world!')
+~~~
+{: .language-matlab}
+
+`.language-python`: Python source:
+
+~~~
+print("Hello World")
+~~~
+{: .language-python}
+
+`.language-r`: R source:
+
+~~~
+cat("Hello World")
+~~~
+{: .language-r}
+
+`.language-sql`: SQL source:
+
+~~~
+CREATE PROCEDURE HelloWorld AS
+PRINT 'Hello, world!'
+RETURN (0)
+~~~
+{: .language-sql}
 
-*   `.bash`: Bash shell commands
-*   `.make`: Makefiles
-*   `.matlab`: MATLAB source
-*   `.python`: Python source
-*   `.r`: R source
-*   `.sql`: SQL source
 
-> ## Why No Syntax Highlighting?
->
-> We do not use syntax highlighting for code blocks
-> because some learners' systems won't do it,
-> or will do it differently than what they see on screen.
-{: .callout}
 
 ## Special Blockquotes
 

diff --git a/_episodes/05-rmarkdown-example.md b/_episodes/05-rmarkdown-example.md
@@ -33,7 +33,7 @@ each episode written in RMarkdown.
 ~~~
 source("../bin/chunk-options.R")
 ~~~
-{: .r}
+{: .language-r}
 
 The rest of the lesson should be written as a normal RMarkdown file. You can
 include chunk for codes, just like you'd normally do.
@@ -44,7 +44,7 @@ Normal output:
 ~~~
 1 + 1
 ~~~
-{: .r}
+{: .language-r}
 
 
 
@@ -59,7 +59,7 @@ Output with error message:
 ~~~
 x[10]
 ~~~
-{: .r}
+{: .language-r}
 
 
 
@@ -76,7 +76,7 @@ library(ggplot2)
 ggplot(diamonds, aes(x = carat,  y = price, color = cut)) +
     geom_point()
 ~~~
-{: .r}
+{: .language-r}
 
 <img src="../fig/rmd-plot-example-1.png" title="plot of chunk plot-example" alt="plot of chunk plot-example" style="display: block; margin: auto;" />
 
@@ -93,7 +93,7 @@ instructions and solutions. For instance this:
 > ~~~
 > paste("This", "new", "template", "looks", "good")
 > ~~~
-> {: .r}
+> {: .language-r}
 >
 > > ## Solution
 > >
@@ -116,7 +116,7 @@ will generate this:
 > ~~~
 > paste("This", "new", "template", "looks", "good")
 > ~~~
-> {: .r}
+> {: .language-r}
 >
 > > ## Solution
 > >

diff --git a/_episodes/06-style-guide.md b/_episodes/06-style-guide.md
@@ -19,6 +19,7 @@ For example, "to delete the cell press <kbd>D</kbd>" should be write as
 ~~~
 to delete the cell press <kbd>D</kbd>
 ~~~
+{: .html}
 
 The table below covers most of the keyboard key labels.
 
@@ -79,5 +80,6 @@ For example, "press <kbd>Ctrl</kbd>+<kbd>X</kbd> to quit nano" should be write a
 ~~~
 press <kbd>Ctrl</kbd>+<kbd>X</kbd> to quit nano.
 ~~~
+{: .html}
 
 {% include links.md %}
diff --git a/_layouts/base.html b/_layouts/base.html
@@ -12,6 +12,7 @@
     <link rel="stylesheet" type="text/css" href="{{ page.root }}/assets/css/bootstrap.css" />
     <link rel="stylesheet" type="text/css" href="{{ page.root }}/assets/css/bootstrap-theme.css" />
     <link rel="stylesheet" type="text/css" href="{{ page.root }}/assets/css/lesson.css" />
+    <link rel="stylesheet" type="text/css" href="{{ page.root }}/assets/css/syntax.css" />
     {% if site.carpentry == "swc" %}
     <link rel="shortcut icon" type="image/x-icon" href="/favicon-swc.ico" />
     {% elsif site.carpentry == "dc" %}

diff --git a/assets/css/syntax.css b/assets/css/syntax.css
@@ -0,0 +1,69 @@
+.highlight .hll { background-color: #ffffcc }
+.highlight  { background: #f8f8f8; }
+.highlight .c { color: #408080; font-style: italic } /* Comment */
+.highlight .err { border: 1px solid #FF0000 } /* Error */
+.highlight .k { color: #008000; font-weight: bold } /* Keyword */
+.highlight .o { color: #666666 } /* Operator */
+.highlight .ch { color: #408080; font-style: italic } /* Comment.Hashbang */
+.highlight .cm { color: #408080; font-style: italic } /* Comment.Multiline */
+.highlight .cp { color: #BC7A00 } /* Comment.Preproc */
+.highlight .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */
+.highlight .c1 { color: #408080; font-style: italic } /* Comment.Single */
+.highlight .cs { color: #408080; font-style: italic } /* Comment.Special */
+.highlight .gd { color: #A00000 } /* Generic.Deleted */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gr { color: #FF0000 } /* Generic.Error */
+.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.highlight .gi { color: #00A000 } /* Generic.Inserted */
+.highlight .go { color: #888888 } /* Generic.Output */
+.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.highlight .gt { color: #0044DD } /* Generic.Traceback */
+.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
+.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
+.highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
+.highlight .kp { color: #008000 } /* Keyword.Pseudo */
+.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
+.highlight .kt { color: #B00040 } /* Keyword.Type */
+.highlight .m { color: #666666 } /* Literal.Number */
+.highlight .s { color: #BA2121 } /* Literal.String */
+.highlight .na { color: #7D9029 } /* Name.Attribute */
+.highlight .nb { color: #008000 } /* Name.Builtin */
+.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */
+.highlight .no { color: #880000 } /* Name.Constant */
+.highlight .nd { color: #AA22FF } /* Name.Decorator */
+.highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */
+.highlight .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
+.highlight .nf { color: #0000FF } /* Name.Function */
+.highlight .nl { color: #A0A000 } /* Name.Label */
+.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
+.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
+.highlight .nv { color: #19177C } /* Name.Variable */
+.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
+.highlight .w { color: #bbbbbb } /* Text.Whitespace */
+.highlight .mb { color: #666666 } /* Literal.Number.Bin */
+.highlight .mf { color: #666666 } /* Literal.Number.Float */
+.highlight .mh { color: #666666 } /* Literal.Number.Hex */
+.highlight .mi { color: #666666 } /* Literal.Number.Integer */
+.highlight .mo { color: #666666 } /* Literal.Number.Oct */
+.highlight .sa { color: #BA2121 } /* Literal.String.Affix */
+.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
+.highlight .sc { color: #BA2121 } /* Literal.String.Char */
+.highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */
+.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
+.highlight .s2 { color: #BA2121 } /* Literal.String.Double */
+.highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
+.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
+.highlight .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
+.highlight .sx { color: #008000 } /* Literal.String.Other */
+.highlight .sr { color: #BB6688 } /* Literal.String.Regex */
+.highlight .s1 { color: #BA2121 } /* Literal.String.Single */
+.highlight .ss { color: #19177C } /* Literal.String.Symbol */
+.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
+.highlight .fm { color: #0000FF } /* Name.Function.Magic */
+.highlight .vc { color: #19177C } /* Name.Variable.Class */
+.highlight .vg { color: #19177C } /* Name.Variable.Global */
+.highlight .vi { color: #19177C } /* Name.Variable.Instance */
+.highlight .vm { color: #19177C } /* Name.Variable.Magic */
+.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */
diff --git a/bin/chunk-options.R b/bin/chunk-options.R
@@ -37,7 +37,7 @@ opts_chunk$set(tidy = FALSE, results = "markup", comment = NA,
 hook_in <- function(x, options) {
   stringr::str_c("\n\n~~~\n",
                  paste0(x, collapse="\n"),
-                 "\n~~~\n{: .r}\n\n")
+                 "\n~~~\n{: .language-r}\n\n")
 }
 
 hook_out <- function(x, options) {

diff --git a/bin/lesson_check.py b/bin/lesson_check.py
@@ -31,7 +31,6 @@
     '%/LICENSE.md': True,
     '%/README.md': False,
     '%/_extras/discuss.md': True,
-    '%/_extras/figures.md': True,
     '%/_extras/guide.md': True,
     '%/index.md': True,
     '%/reference.md': True,
@@ -72,12 +71,14 @@
     'error',
     'output',
     'source',
-    'bash',
-    'make',
-    'matlab',
-    'python',
-    'r',
-    'sql'
+    'language-bash',
+    'html',
+    'language-make',
+    'language-matlab',
+    'language-python',
+    'language-r',
+    'language-shell',
+    'language-sql'
 }
 
 # What fields are required in teaching episode metadata?
@@ -114,7 +115,6 @@ def main():
     for filename in docs.keys():
         checker = create_checker(args, filename, docs[filename])
         checker.check()
-    check_figures(args.source_dir, args.reporter)
 
     args.reporter.report()
 
@@ -255,38 +255,6 @@ def check_fileset(source_dir, reporter, filenames_present):
                    seen)
 
 
-def check_figures(source_dir, reporter):
-    """Check that all figures are present and referenced."""
-
-    # Get references.
-    try:
-        all_figures_html = os.path.join(source_dir, '_includes', 'all_figures.html')
-        with open(all_figures_html, 'r') as reader:
-            text = reader.read()
-        figures = P_FIGURE_REFS.findall(text)
-        referenced = [os.path.split(f)[1] for f in figures if '/fig/' in f]
-    except FileNotFoundError as e:
-        reporter.add(all_figures_html,
-                     'File not found')
-        return
-
-    # Get actual image files (ignore non-image files).
-    fig_dir_path = os.path.join(source_dir, 'fig')
-    actual = [f for f in os.listdir(fig_dir_path) if os.path.splitext(f)[1] in IMAGE_FILE_SUFFIX]
-
-    # Report differences.
-    unexpected = set(actual) - set(referenced)
-    reporter.check(not unexpected,
-                   None,
-                   'Unexpected image files: {0}',
-                   ', '.join(sorted(unexpected)))
-    missing = set(referenced) - set(actual)
-    reporter.check(not missing,
-                   None,
-                   'Missing image files: {0}',
-                   ', '.join(sorted(missing)))
-
-
 def create_checker(args, filename, info):
     """Create appropriate checker for file."""
 

diff --git a/bin/lesson_initialize.py b/bin/lesson_initialize.py
@@ -242,8 +242,8 @@
   - Makefile
   - bin
 
-# Turn off built-in syntax highlighting.
-highlighter: false
+# Turn on built-in syntax highlighting.
+highlighter: rouge
 '''
 
 ROOT_INDEX_MD = '''\

diff --git a/fig/rmd-plot-example-1.png b/fig/rmd-plot-example-1.png
-Original file line number
+Diff line change
@@ Expand Up / @@ -128,7 +128,7 @@ is translated into: @@
     </body>
     </html>
     ~~~
-    {: .source}
+    {: .html}
     > ## Back in the Day...
     >
@@ Expand Down @@