Day 14 – Playing around with the new documentation components

After living with RakuDoc v2 for over a year, some things become normal that surprise others when I explain them. Here are a few things I do when documenting my software.

1. Shoving stuff down the file

There are a couple of items needed in a changing document that should be easily managed, probably at the top of the file, but which are best rendered at the bottom. This is easily done using a semantic block with :hidden. Suppose at the top of the document we have the following

=TITLE An important document
=begin AUTHORS :hidden
=item A. Writer
=item A.N. Other
=end AUTHORS

The TITLE contents (An important document) will be rendered, but the contents of the AUTHORS semantic block will not.

A note to those unaccustomed to RakuDoc: if a block name starts immediately after an =, then the contents of the block start on the same line, and end when the first blank line is encountered.

Since AUTHORS is preceded by =begin, the rest of the first line is metadata and the contents start on the next line until the =end AUTHORS line.

The contents of a semantic block, which is identified because the name is all caps, are processed and stored.

The :hidden prevents the contents from being immediately added to the output. Later, eg. at the bottom of the file, we can indicate where the processed string is added to the output using a =place block, for example,

=place semantic:AUTHORS :caption<Credits>

Here =place seems to be a block, but it is considered to be a directive. A directive does not have a =for or =begin form, and can be followed by metadata. In this case, ‘semantic:’ indicates where the place block is getting its data, while :caption contains a string that is used to add the block to the Table of Contents, and to act as a heading in the flow of the text.

A =place can be used to include images (online or local), other rakudoc files, and several other types of data. By the way, it is possible to =place data from the current source file that has not yet been processed. Thus, it is possible to have a =place semantic:SOMENAME before specifying =SOMENAME.

2. Configuration

When writing this source in RakuDoc, which will be included at the end of the article, I will be including a number of examples as code.

RakuDoc allows for code to included without explicitly requiring a =begin code / =end code sequence. All that is needed is to indent the text in a block without any blank lines.

A code block can be marked with the metadata option :lang to indicate which computer language is contained in the block, for example so that a syntax highlighter can be used. A code block without :lang is considered by default to be Raku.

An implicit code block has nothing to ‘hang’ a :lang on, but I want for all the implicit code blocks in this article to be :lang<RakuDoc>. I can do this using the =config directive, eg.

=config code :lang<RakuDoc>

The statement means that all code blocks, which also includes all implicit code blocks, are by default :lang<RakuDoc>.

More generally, a config directive expects a block name followed by one or more metadata options. Then by default each successive block with that name will have that metadata option set to the value in the config directive. The scope of the config directive can be controlled, as explained in the specification.

3. Numbering

One of the really irritating aspects I found in RakuDoc v1 (POD6) was that numbered items or headings was not possible. As you can see this has been overcome. Up to four levels of numbering are automatically supported.

3.1. Headings

This just shows a second level of heading

3.2. Lists

Two sorts of lists (with items and definitions) can also be numbered.

This is a numbered item
1.1. This is a second level item
1.2. And so on

4. Bulleting things

A new addition to RakuDoc v2 is the idea of bulleted lists. For example,
  🐒 Go to the zoo
  🐒 Visit some animals
  🐒 Donate to a conservation charity
This was achieved by attaching a :bullet«\c[monkey]» to an item block, or for this document using a configuration:

=config item :bullet«\c[monkey]»

The metadata option syntax should be considered like Raku pair. So the double brackets around the :bullet are forcing the interpolation semantics of a string, and hence \c[] syntax is creating a Unicode entity. Here is a list of Unicode icons.

5. How to try out these ideas

Installation was covered in the first Advent article this year. Once installed with the zef install . -/precompile-installinstruction, there is a utility called RenderDocs, which zef will put into some bin directory. Try copying the RakuDoc source of this article (given below) into a file (eg. Advent.rakudoc). Assuming that zef has put in a directory in your path, and it is executable, then run:

RenderDocs --src=. --format=HTML Advent

• --src=. uses the current working directory instead of the default docs/,
• formats the source into HTML with the Bulma CSS framework,
• uses Advent.rakudoc as the source file name,
• and creates a file Advent.html in the CWD.

Using a browser (this works with Firefox), loading the file will generate an HTML page of this article. A note of warning, the most recent version of Raku will be needed.

Credit

Richard Hainsworth aka finanalyst

Source File

---

=begin rakudoc
=TITLE Things you can do in RakuDoc v2
=for AUTHOR :hidden
Richard Hainsworth
aka finanalyst

=config code :lang<RakuDoc>

After living with RakuDoc v2 for over a year, some things become normal that surprise others
when I explain them. Here are a few things I do when documenting my software.

=numhead Shoving stuff down the file

There are a couple of items needed in a changing document that should be easily managed,
probably at the top of the file, but which are best rendered at the bottom. This is easily
done using a semantic block with C<:hidden>. Suppose at the top of the document we have
the following

    =TITLE An important document
    =begin AUTHORS :hidden
    =item A. Writer
    =item A.N. Other
    =end AUTHORS

The TITLE contents (I<An important document>) will be rendered, but the contents of the AUTHORS semantic block
will not.

=begin nested
A note to those unaccustomed to RakuDoc: if a block name starts immediately after an C<=>,
then the contents of the block start on the same line, and end when the first blank line is encountered.
 
Since C<AUTHORS> is preceded by C<=begin>, the rest of the first line
is metadata and the contents start on the next line until the C<=end AUTHORS> line.

The contents of a semantic block, which is identified because the name is all caps, are processed and
stored. The C<:hidden> prevents the contents from being immediately added to the output.

Later, eg. at the bottom of the file, we can indicate where the processed string is added to the
output using a C<=place> block, for example,
=end nested

=begin code
=place semantic:AUTHORS :caption<Credits>
=end code

Here C<=place> seems to be a block, but it is considered to be a I<directive>. A directive
does not have a C<=for> or C<=begin> form, and can be followed by metadata.

In this case, 'semantic:' indicates where the place block is getting its data, while C<:caption>
contains a string that is used to add the block to the Table of Contents, and to act as a heading
in the flow of the text. A C<=place> can be used to include images (online or local), other
rakudoc files, and several other types of data.

By the way, it is possible to C<=place> data from the current source file that has not yet been
processed. Thus, it is possible to have a C<=place semantic:SOMENAME> before specifying B<=SOMENAME>.

=numhead Configuration

When writing this source in RakuDoc, which will be included at the end of the article,
I will be including a number of examples as code. RakuDoc allows for code to included
without explicitly requiring a C<=begin code> / C<=end code> sequence. All that is needed
is to indent the text in a block without any blank lines.

A code block can be marked with the metadata option C<:lang> to indicate which computer
language is contained in the block, for example so that a syntax highlighter can be used.
A code block without C<:lang> is considered by default to be B<Raku>.

An implicit code block has nothing to 'hang' a C<:lang> on, but I want for all the implicit code
blocks in this article to be C«:lang<RakuDoc>». I can do this using the C<=config> directive, eg.

=begin code
=config code :lang<RakuDoc>
=end code

The statement means that all C<code> blocks, which also includes all I<implicit code> blocks,
are by default C«:lang<RakuDoc>».

More generally, a B<config> directive expects a block name followed by one or more metadata
options. Then by default each successive block with that name will have that metadata option
set to the value in the config directive.

The scope of the B<config> directive can be controlled, as explained in the specification.

=numhead Numbering

One of the really irritating aspects I found in RakuDoc v1 (POD6) was that numbered items or
headings was not possible. As you can see this has been overcome. Up to four levels of numbering
are automatically supported.

=numhead2 Headings

This just shows a second level of heading

=numhead2 Lists

Two sorts of lists (with items and definitions) can also be numbered.
=numitem This is a numbered item
=numitem2 This is a second level item
=numitem2 And so on

=numhead Bulleting things
=begin section
=config item :bullet«\c[monkey]»

A new addition to RakuDoc v2 is the idea of bulleted lists. For example,
=item Go to the zoo
=item Visit some animals
=item Donate to a conservation charity
=end section

This was achieved by attaching a C<:bullet«\c[monkey]»> to an item block,
or for this document using a configuration:
=begin code
=config item :bullet«\c[monkey]»
=end code

=nested The I<metadata option> syntax should be considered like B<Raku> I<pair>. So the double brackets around the C<:bullet>
are forcing the interpolation semantics of a string, and hence C<\c[]> syntax is creating a Unicode entity. Here is a
L<list of Unicode icons|https://www.unicode.org/emoji/charts/full-emoji-list.html>.

=head How to try out these ideas

Installation was covered in the first Advent article this year. Once installed with
the C<zef install . -/precompile-install> instruction, there is a utility called
C<RenderDocs>, which B<zef> will put into some I<bin> directory.

Try copying the RakuDoc source of this article (given below) into a file (eg. C<Advent.rakudoc>).
Assuming that I<zef> has put <RenderDocs> in a directory in your path, and it is executable, then run:

    RenderDocs --src=. --format=HTML Advent

=item C<--src=.> uses the current working directory instead of the default C<docs/>,
=item formats the source into HTML with the B<Bulma> CSS framework,
=item uses R<Advent>B<.rakudoc> as the source file name,
=item and creates a file K<Advent.html> in the CWD.

Using a browser (this works with Firefox), loading the file will generate an HTML page of this article.

A note of warning, the most recent version of Raku will be needed.

=place semantic:AUTHOR :caption<Credit>

=end rakudoc