9 Mini tutorials
Smaller, self-contained tasks.
9.1 Syntax highlighting
Neither Pollen nor Racket has its own syntax-highlighting library, but you can use an external syntax highlighter. Two options: Pygments or Highlight.js.
Highlight.js is a JavaScript library, and thus meant to be run in the browser. So it’s fine if your target is HTML, and you don’t mind delegating that work to the browser. It’s also easier to set up.
Pygments is a Python library (though you don’t need to know any Python to use it with Pollen). It runs alongside Pollen (in a separate process) as pages are rendered, so the syntax highlighting can be baked into your compiled files. If you want to target other formats aside from HTML, this is the better choice. It requires a little more setup, but I doubt anyone who’s made it this far will have trouble.
9.1.1 Using Pygments with Pollen
I used Pygments for syntax highlighting in this article made with Pollen. Links to the source are available at the bottom of the article.
Make sure you have pygments already installed. Instructions here. Pretty easy — for instance, on my Mac OS machine, it simply require easy_install pygments at the command line.
The pollen/unstable/pygments helper module provides a function called highlight. To make highlight available in your source file, you can either add the line ◊(require pollen/unstable/pygments) to the source file itself, or put it in "pollen.rkt" and provide it from there.
To invoke Pygments, use highlight by providing a language name like 'python in the brackets (note quote mark at front of name) and then the code you want highlighted between curly braces.
#lang pollen ◊(require pollen/unstable/pygments) ◊highlight['python]{ for x in range(3): print x } When you run this file, you should see something like this, with the parsed syntax marked up into an X-expression:
'(div ((class "highlight")) (table ((class "sourcetable")) (tbody (tr (td ((class "linenos")) (div ((class "linenodiv")) (pre "1\n2"))) (td ((class "code")) (div ((class "source")) (pre (span ((class "k")) "for") " " (span ((class "n")) "x") " " (span ((class "ow")) "in") " " (span ((class "nb")) "range") (span ((class "p")) "(") (span ((class "mi")) "3") (span ((class "p")) "):") "\n " (span ((class "k")) "print") " " (span ((class "n")) "x") "\n")) "\n")))) "\n")
To get highlighting, you’ll still need to add styles to your CSS to change the appearance of the code. If you look at the CSS source in my demo article, I just pasted a Pygments theme at the bottom (that I picked up and then edited with some variable values).
I concede that the last step isn’t convenient. But I haven’t yet figured out how it to make it easier. Larding the Pollen distribution with a bunch of Pygments themes doesn’t make sense. Moreover, even if convenient, they wouldn’t be editable / programmable, which is sort of the point of the whole exercise.
Anyhow, that’s why it’s in the unstable category — it works, but I think it could be done better.
9.1.2 Using Highlight.js with Pollen
Because Highlight.js is browser-based, it doesn’t require any high-level cooperation from Pollen. You just add it to your project like an image or webfont or other linked asset.
Download the Highlight.js library.
Add these lines to the <head> section of your "template.html" (or other template):
<link rel="stylesheet" href="/path/to/styles/default.css">
<script src="/path/to/highlight.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
With these resources loaded, Highlight.js will automatically highlight any code syntax with the markup <pre><code class="language-name">...</code></pre>. So in Pollen markup, you could write that directly like so:
#lang pollen/markup ◊pre{◊code[#:class "python"]{ for x in range(3): print x }} Or if you wanted to match the notation for pollen/unstable/pygments, you could write a highlight function that expands to markup that works for Highlight.js:
#lang pollen/markup ◊(define (highlight lang . xs) `(pre (code ((class ,(format "~a" lang))) ,@xs))) ◊highlight['python]{ for x in range(3): print x }
As above, I concede that it would be more convenient to have Pollen automatically drop the necessary incantations into the <head> of your HTML. But as a matter of policy, I prefer to minimize magic behavior.
9.2 Math typesetting with MathJax
MathJax is a JavaScript library that implements the math-typesetting algorithms of TeX. It’s easy to add MathJax to a Pollen project, and then invoke it with Pollen command notation in your source files.
Download the MathJax library if you want to run the library locally, without a network connection. You can also use a MathJax CDN like cdnjs and just link to the library across the network (I’ll use this option in the example that follows).
Add these lines to the <head> section of your "template.html" (or other template). First, the MathJax library itself:
<script type="text/javascript"
src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
Then, add any configuration options. For instance, this will activate the dollar sign as an inline-equation delimiter:
<script type="text/x-mathjax-config">
MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$']]}});
</script>
Make Pollen tag functions that add the delimiter characters and also a mathjax wrapper tag that will trigger the JavaScript typesetting. For instance, suppose we wanted to denote inline equations with ◊${equation …} and block equations with ◊$${equation …}. Our tag functions could look like this:
#lang pollen ◊(define ($ . xs) `(mathjax ,(apply string-append `("$" ,@xs "$")))) ◊(define ($$ . xs) `(mathjax ,(apply string-append `("$$" ,@xs "$$"))))
Putting it together, here’s a minimal working example in two files (obviously in a larger project, you’d move those tag functions to a "pollen.rkt" file):
<html> <head> <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"> </script> <script type="text/x-mathjax-config"> MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$']]}}); </script> </head> <body> ◊(->html doc) </body> </html>
By the way, there’s no pollen/math module because this task doesn’t seem complicated enough to merit it. What I just described is all you need.