This continues the series starting with RakuDoc more than ... The images here will be generated using the Docker container described in the first article.
In this article I will be discussing some of the markup codes which can be used in a RakuDoc source.
The next few articles planned will cover
- Block types, such header, formulas, paragraphs, indented paragraphs
- How to include images, and how to customise their placing.
- Some custom block types that are included with the Rakuast::RakuDoc::Renderer, but which are not specified in standard RakuDoc.
- Enumerations of blocks, that is creating numbered headings, items, code etc.
Update of browser editor
The browser editor container has been updated since the last article, and contains a new button. We will give an example of this below. However, it does require that your computer has an internet connection.
As a reminder, the browser can be started (assuming podman is installed) as follows for Ubuntu type distributions:
podman pull docker.io/finanalyst/browser-editor:latest
podman run -d -v .:/browser/publication --rm docker.io/finanalyst/browser-editor:latest
And on Mac silicon
podman pull docker.io/finanalyst/browser-editor:latest
podman run -d -v.:/browser/publication --platform linux/amd64 --rm docker.io/finanalyst/browser-editor:latest
To stop the container
- run podman ps and note the name of the container, eg good_person
- run podman stop good_person
Comparison of styling using other systems
It is very useful for a reader when the author lays out text in a pleasant manner, including spaces between paragraphs, and styling words within paragraphs to draw attention to them.
Practices that at first are considered considerate, become mandatory over time. For example, the very first styling of text came in Roman times, when good practice was to separate the letters making up words with spaces, and then to use punctuation marks. Now it is impossible to eliminate spaces and poor punctuation is a sign of a poor education. Here is an interesting article on punctuation.
Let's consider the ways in which we can highlight a word by making it bolder.
In an MS Word document, an author will highlight the words to be emboldened and then use Ctrl-B or the equivalent on a Mac. This is a quick and easy way of styling, unless the author decides too many bold words exist and wants to restyle to Italic. Then it becomes a hassle to change.
Using MarkDown, it is much easier in that the words to be styled are 'bracketed' using special characters, so ** ... ** are used to embolden, while * ... * are used for italicising. There are a few other characters such as `` for code. But as soon as you need more sophisticated styling, such as pushing the characters up as in exponentiation, or down, it's necessary to use HTML tags. However, the upside is that unlike an WYSIWYG editor, like Word, changing the styling is easy: change the styling character. And yet ... each different type of style, or rather its style character, has to be learnt.
RakuDoc approaches styling in a different way: a number of markup codes are defined in a declarative manner, and all use the same syntax, Upper case letter openercontentcloser e.g., B<a basic term>.
The simplest RakuDoc markup codes enclose text and provide a rendering, and they are:
The aim of the naming system is to provide a hint about the rendering, while leaving it to the renderer to implement the final output format.
The same syntax is used for other types of inline content. Almost all the Latin uppercase letters, and a Greek uppercase letter have been defined for standard RakuDoc. Rather than describing each of the codes, it is probably best just to look at the RakuDoc v2 specification.
However, the Markup syntax is not limited to the specified letters, and any Unicode character with the Uppercase property can be used for customised content. For example, the Rakuast::RakuDoc::Renderer comes with a custom markup for inserting Font Awesome icons into the text. Some examples are given in the documentation for the module.
The aim of these initial articles is to provide an introduction, rather than give an extensive tutorial. The best way to see how the Markup codes work is to try them in the browser.
Try copying the following RakuDoc source into the updated browser:
=begin rakudoc
=TITLE Sample
=head Introduction
This is some B<basic> highlighting showing C<my $new code> with
SomeJ<B<junior>>andH<I<higher>> text.
Here are some FontAwesome icons (ℱ = U+2131):
Train normal size ℱ<fas fa-train> Triple size train ℱ<fas fa-train fa-3x>
An animated spinner ℱ<fas fa-sync fa-spin fa-3x fa-fw>
Click on the C<On line>/C<Off line> switch to see.
Here is an inline image P<https://cdn.esahubble.org/archives/images/screen/potw2552a.jpg>
=end rakudoc
You will get something like
If you scroll the pane to the bottom on the rendered side, you will find some warnings about errors found during the rendering. The simple HTML renderer is designed to be used offline and all the CSS and Javascript are contained inside the file.
However, we now expect online connections with CSS, images and JS libraries delivered using CDNs. So the HTML-Extra renderer uses the Bulma CSS framework and has plugins to pull in FontAwesome and the LeafletMaps library (we will cover this in a future article).
Now click on the Go on line button. It may take some moments to render and pull the image in from the Hubble telescope site.
You should get something like
Attribution: cover image from
Hubble telescope image from
