Introduction to series
This is the first article in a series about the markup language RakuDoc. In subsequent articles I will explore some of the interesting aspects of RakuDoc and how to add customisations.
In this first article, I want to discuss how RakuDoc came about, why its design allows for a wide use, and how a reader can easily (for some definitions of 'easily'?) experiment with RakuDoc in a browser using a docker image.
Raku and RakuDoc
The Raku language belongs to the family of Perl variations (and was originally known as Perl 6). The culture surrounding Raku includes as highly recommended several good coding practices, such as extensive unit testing, and documentation.
To facilitate documentation, Raku comes with its own markup language, called RakuDoc. The intention is that documentation can be included inside a program, in a similar way to inline comments, but it can also be used in standalone files to document how to use the software. RakuDoc has also taken into account Donald Knuth's literate coding ideas, although RakuDoc does not develop the fundamental ideas in the same way as others have.
Furthermore, software development has dramatically changed since Knuth: virtually all projects have many dependencies, and libraries are written that are not ever intended to be the final customer-facing product. Consequently, documentation has two distinct faces:
maintainer or code-oriented, meaning that information is given about the algorithm or the purpose of variables. This information is never intended to be available to a user of the software;
developer or text-oriented, meaning that information is given about how to use the software, and the purpose of the external interfaces.
Consequently, the documentation language for Raku needed to be usable inside the code, and also to create manual pages for developers using the software.
The result - RakuDoc - is extensively used inside code modules, but it is also used in stand-alone files. The entire documentation for the Raku language (Raku documents) is written in some 700 RakuDoc files.
Beyond documentation
It is almost certain that readers of this article have used both Markdown and MS Word (or its FOSS equivalent LibreOffice). There are other editor/format systems, but I'll use these two for simplicity.
Markdown dominates the web (and is used for CoderLegion) because it is simple, and converts naturally into HTML.
Word (LibreOffice) dominates the corporate space because (in part) it makes it easy for non-specialists to create documents that have different styles, automatic Tables of Contents, footnotes, and so on.
Expert users, however, find that Markdown is too simple - it does not allow for Tables of Content linked to headings, or footnotes that link back to the source, and custom content blocks. These limitations have been redressed in several ways, but only by creating different flavours of Markdown. A consequence of the ad hoc additions is that each type of functionality has a different syntax.
Word (LibreOffice) by contrast is too complex. It is quite easy to create a glitch, say a bold style that extends too far, or bullets points that have different styling because the line end has been deleted. The only practical way to solve these issues is to delete enough text to eliminate the underlying style marker, and start again.
It is a difficult task to create a Word file programmatically, not least because the underlying format is considered proprietary. LibreOffice files can be created programmatically, and then converted to Word.
RakuDoc is located between these extremes: it was not designed to be rendered as a document is written. The RakuDoc source can be read and easily understood by a human author, and then the source is rendered into a format, such as HTML, pdf or epub format, which is read by the end user.
To handle different styled text, such as bold, underline, RakuDoc text has markers which declaratively indicate how the text should be treated by a renderer. Markdown also uses markers that map closely to an HTML rendering, eg #, *, _. The declarative nature of RakuDoc's markup means that its B<> stands for Basic not bold, and it is left to the renderer as to what that means in say HTML or epub. Furthermore, RakuDoc has a single syntax for the markers, and the possibility to add markers.
In addition to text markers, RakuDoc has blocks that operate on chunks of text. These blocks can be associated with meta data, allowing for different styling, and customisation.
How to experiment with RakuDoc?
To make things easier for experimentation, I have created a docker image docker.io/finanalyst/browser-editor which can be run in a container, and accessed using a browser.
However, for the interested reader, the more generic way is to install Raku and then install the Rakuast::RakuDoc::Render module.
The intention of the browser editor container is for the RakuDoc source to be created and edited in a browser, which also renders the source to HTML on the fly. The edited RakuDoc source can be saved to the container's browser/publication directory, and if the container's directory is bound to a host directory, then the RakuDoc source will be saved on the local host as well.
The following is written assuming a Linux OS and so it should work with, eg., Ubuntu and Apple. I have not tested this with a MS system, and I would be happy to have comments to adapt the following.
Let's start.
We need to have podman installed.
We need an empty directory, say rakudoc-test, eg. mkdir rakudoc-test.
Inside this directory (eg., cd rakudoc-test), we run
podman run -d -v .:/browser/publication --network=host --rm docker.io/finanalyst/browser-editor:latest
Update: I have removed an underdocumented constraint. So, this should now be
podman pull docker.io/finanalyst/browser-editor:latest
podman run -d -v .:/browser/publication --rm docker.io/finanalyst/browser-editor:latest
For Mac users, try
podman pull docker.io/finanalyst/browser-editor:latest
podman run -d -v .:/browser/publication --platform linux/amd64 --rm docker.io/finanalyst/browser-editor:latest
Point a browser at localhost:3000 and the window should look like this 
Edit the rakudoc file, then click on the Save button.
End the container
- run
podman ps and note the name of the container, eg good_person
- run
podman stop good_person
It should pull in the latest version of the browser-editor image, bind the current directory (we are running this inside rakudoc-test) to the container's browser/publication directory, and then return a SHA identity string (don't worry, it can be forgotten). The --network=host is the simplest way to arrange for the container to serve the browser. However, podman developers consider this a possible vulnerability and there is a way to set up a network stack to run the image more safely. For those concerned about safety, the container source can be seen at github browser-editor
About the browser editor
The left-hand panel uses an instance of the Ace editor with a RakuDoc source, and the right-hand panel contains the HTML rendering of that source. The Ace editor allows for the normal editor functions, while the HTML rendering is generated as soon as the editor contents changes. Consequently, when typing it is likely that an invalid RakuDoc source will be created. Once the RakuDoc source is correct, it will be rendered into the right-hand panel. In addition, there are various RakuDoc expressions that are ambiguous, in which case, a warning will be generated that is shown at the bottom of the rendered file.
A small sample RakuDoc file is included to start off. The name of the file can be changed by editing the filename text widget, eg to web-sample.rakudoc. By pressing the Save button, the RakuDoc source is saved to the container's browser\publication\web-sample.rakudoc and if the directories are linked properly, then web-sample.rakudoc will be saved on the local system. Another file rakudociem-ipsum.rakudoc can also be selected. It contains examples of nearly all RakuDoc's features, but it can take a while to render.
Test the system
Just to test the system and to give a flavour of RakuDoc, try adding the following text after the First item line:
=for item :bullet<<\c[turkey]>>
Second item
This should produce a browser window a bit like this 
Some commentary on this new text:
the line =item First item would create a bullet point similar to - First item in Markdown.
However, it is possible to change the bullet item by item by adding meta data to the item block. However, to distinguish between a block without meta data =item First and one with meta data, we use the =for directive.
Item blocks will accept a :bullet option. The contents of the bullet option are then interpreted as the bullet. Raku has several bracketing syntaxes, and the <</>> brackets (or the Unicode equivalents « ») take the contents and treat them as an interpolated string. \c[ ] takes the content as a Unicode symbol name and its interpolated value is the Unicode character. Consequently \c[turkey] is the Unicode icon (U+1F983).
So now add below the last item
=for item2 :bullet<<\c[tulip]>>
sub second item
and now there is a second level item with a new bullet, producing a window like: 
Finally, lets show a bit of customisation. Try adding the following lines before the last line (=end rakudoc)
=config item :bullet<<\c[rose]>>
=item a new item
=item a second item
=item and a third one
The browser window should look something like 
Here the meta option :bullet<<\c[rose]>> in the =config statement is distributed to all the =item blocks implicitly. Consequently, all the following item blocks will have that bullet option automatically.
Future articles will look at the different block types, and some custom blocks that include maps and formula, and different markup formats, such as B<> and C<>.