Icing on the code

Technology and the code that drives it is becoming more important to our society and technological evolution.As more and more people learn how to program (and move onto the harder discipline of software engineering) it becomes more important to stand out from the multitude. This is where presenting your work becomes important both as an expression of you and for others to learn from. And thus we have syntax highlighters that make the code more presentable and at the same time single out the actual syntax of the language.

Disclaimers

Moodle™ is a registered trademark of ‘Martin Dougiamas’ – moodle.com/trademarks

WordPress™ is a registered trademark, please see: wordpressfoundation.org/trademark-policy

Other names / logos can be trademarks of their respective owners. Please review their website for details.

I am independent from the organisations listed above and am in no way writing for or endorsed by them.

All code ‘shown’ in the images is my own.

So what does a syntax highlighter do?

Essentially it takes the code you want to describe and transforms its appearance. This can be within an integrated development environment or a web page. For the web page, you may have placed the code within a post or page etc. that will be published by a supporting environment like Moodle or WordPress. I will be covering the web page within Moodle and WordPress aspect here.

As code has lots of symbols then from an HTML point of view it needs to be at least placed within ‘pre’ tags. I believe that for XHTML then there is a secondary requirement of being within a ‘code’ tag that is within the ‘pre’ tag. There are lots of syntax highlighters out there, but for the purposes of this article I’m going to concentrate on one by Alex Gorbachev – github.com/syntaxhighlighter/syntaxhighlighter – for the main reasons that I’m familiar with it and it is also in my Shoelace theme – moodle.org/plugins/theme_shoelace.

And so to illustrate what it does, here is some code in a label in Shoelace:

Syntax Highlighting before and afterWhere we can see the transformation. Keywords have been singled out and line numbers added.

How it works

All syntax highlighters work subtlety different and you’ll need to consult their documentation. With Alex’s you have to specify what ‘brush’ to use in the class of the ‘pre’ tag, where the ‘brush’ is the name of the language. For example, for Java we would type ‘<pre class=”brush:java”>’ and for C we would have ‘<pre class=”brush:c”>. Then the highlighter uses that to select the right set of rules pertaining to the given language. Then the highlighter uses that to select the right set of rules pertaining to the given language, for example:

The highlighting process can at times not be perfect and will need fixing. For the ‘C program’ I will illustrate shortly I had to change the ‘<’ and ‘>’ symbols to ‘&lt;’ and ‘&gt;’ respectively in order not to get a repeat of the line ‘#include <stdio.h>’ at the bottom of the text.

WordPress

Life is about learning and Moodle is not the only content management platform out there, but it is more learning specific. So as a ‘marketing front end’ to the ‘learning front end’ what about WordPress? From it you can write about your software development courses and illustrate your work. For example we can describe ‘unions in C’ with the following program:

Unions in Cwhich in concept you could then go on to describe a course that you had created around ‘C programming’.

This has been presented using a custom filter I wrote:

WordPress syntax highlighting filter plugin

that when it sees a ‘pre’ tag with a brush class then it loads the highlighter. This is my first WordPress plug-in, so may not be complete.

What does this mean for learning?

I believe that it will enhance the overall presentation of your courses. Software engineering seems to have the ‘dull’ social attribute pinned to it. It is not seen as exciting or dare I say ‘cool’. But it is challenging, rewarding, creative and as each person has their own style, even artistic. When you understand code there can be a beauty to how someone has written and crafted that code.

Learning how to be a software engineer with the programming element needs to be an exciting and enjoyable thing to do. Thus by syntax highlighting your examples, this is just one way of achieving that goal.

Some of my code

In Moodle before the introduction of the FontAwesome icon font you could not easily change the colour of the icons. Even today, not all of the icons are FontAwesome ones, not because they don’t have a replacement specified but because of the JavaScript icon loading mechanism does not support the new icon system functionality – yet. This can be evident on the block hide/show and docking icons. So as a theme can override the icons and one form of those icons is in SVG (Scaleable Vector Graphics) format, which so happens to be a text based format, I thought that PHP code could be used to manipulate the icon’s colour. This idea was further reinforced by the code I had already written to undertake this task via ‘Grunt’ which is a ‘Node.js’ command line tool, but this is really a developer tool and not user friendly. To cut a long and technical story short, here is a snippet of the code I wrote and wish to show off:

Shoelace SVG Colour Code
It first sees if the ‘iconcolour’ setting has been set by the user. Then if so sees if it has changed from the colour the icons are already. If so then it will load each SVG file that the theme has overridden and replace with the new if the colour is not white or already the new colour, finally saving it. Lastly a ‘Purge all caches’ is done so that when loading the page the new version of the icon is used and it’s local file cache updated.

So, ignoring the technical complexities, you can see how the syntax highlighting aids the readability of the code to the user.

What about accessibility?

In writing this post, the needs of accessibility have sprung to mind. Looking at how the highlighter transforms the code within the ‘pre’ tags into a multi-hierarchical markup table then I can envisage that this may present an issue to screen readers. To be honest, I don’t know the correct answer to this. Perhaps screen readers should prevent the highlighter from running? Do they read and transform the markup before any JavaScript operates and changes it? Should content creators provide alternatives? Do you know? If so, please do say in the comments.

Summary

We have learnt about syntax highlighters, their purpose, how they work and how they can be applied within a given context. What do you think? Are they good or bad? Are they worth using? What more needs to be done? Are there alternatives to the problem of describing code?

Gareth Barnard

Gareth Barnard

Developer at HRDNZ
Gareth is a developer of numerous Moodle Themes including Essential (the most popular Moodle Theme ever), Shoelace, and other modules such as course formats.
Gareth Barnard

Latest posts by Gareth Barnard (see all)

blank

Gareth Barnard

Gareth is a developer of numerous Moodle Themes including Essential (the most popular Moodle Theme ever), Shoelace, and other modules such as course formats.

One thought on “Icing on the code

  • 26th October 2018 at 6:28 pm
    Permalink

    Very interesting post !
    The only tie I use a syntax highlighter is when I’m using the Terminal / Command Line Interface on a linux server – but it is sooooo useful then 🙂

    Reply

Add a reply or comment...