Day 17: How to clarify which parts of the documentation change

Using Pod::To::HTML2 a new custom FormatCode, D<> (D for deprecation), can be made to help with the Raku Documentation process. The new FormatCode should show a span of documentation that is deprecated in some way. This happens a lot when Rakudo is being upgraded. However, people using older versions of Rakudo need to understand what has changed, as well as what has been added. So it is not a good idea to delete older information, but it is not efficient to re-generate the entire Documentation suite for each new version of Rakudo.

Perhaps it would be good for a span of words to be highlighted in some way, and then for a deprecation string to appear when a mouse hovers over it.

For example D<function moveover( $x, $y, $z) { … } | Not expected to work in Rakudo-H > would be used to cover the function definition, and the deprecation string is after the |.

First install the module using zef install Raku::Pod::Render which will install Pod::To:HTML2. You will need at least version 4.2.0. A default directory is created with some distribution plugins. To see examples of the distribution plugins, type Rakudoc-to-html Example in an empty directory. Then serve the file Samples.html using some html serving system.

However, this is about making a bespoke plugin to implement a new Formatting Code. Pod::To::HTML2 interprets specified local sub-directories whose name does not contain the character _ after the first character of the name to contain plugin information.

Pod::To::HTML2 is a sub-class of ProcessedPod, so below I shall mention instances of ProcessedPod, though possibly I should be saying instances of Pod::To::HTML2.

Lets start with an empty directory ‘test’ (this article is written for Ubuntu linux, apologies for those on other systems that differ significantly).

Now we enter the directory and create a Rakudoc file (eg. ‘test-d.rakudoc’) with the following text:

    =begin pod

    This is some text to test a new format code. For example, D<function moveover( $x, $y, $z) { ... } | Not expected to work in Rakudo-H >
    should have a highlight and a deprecation string.

    =end pod

Now if you run Rakudoc-to-html test-d.rakudoc in the test/ directory you will get an html file test-d.html together with a directory asset_files containing some CSS files and the icon images. Note how ‘asset_files’ has a ‘_’ in it so that it will not be interpreted in the future as a plugin.

The file test-d.html can be served to a browser. I have the excellent Comma IDE, which allows a project-root-directory file to be served to a brower simply by opening it in that browser. I am sure everyone reading this article will have some favourite way of serving a file.

The FormatCode is not known to the Renderer, so the unknown-name template is triggered for a FormatCode.

To create a plugin, we need to:

• tell the renderer that a custom Block is available. However, the Pod-Block for a FormatCode already exists, so we only need to provide a template for D. (I wrote about this in case you want to experiment with new Custom Blocks).
• tell the renderer what HTML needs to be created for the FormatCode-D, that is provide a template.
• provide Pod::To::HTML2 with a name for the CSS to be associated with the HTML containers, which we need to get the highlighting effect.

We create a sub-directory of test/ called deprecation-span. The name is not too important but it contains a ‘-‘ rather than ‘_’, though a name without ‘-‘ is possible.

Inside deprecation-span we create a file called config.raku. The name is important and a plugin must have a config.raku file. A config.raku is a Raku program that ends with a hash value. The following is a possible minimal content

%(
    :custom-raku(), # this key is mandatory, so we need it to exist and have Nil value
    :template-raku<deprecation-template.raku>,
    #:add-css<deprecate-span.css>,
)

You will see that this a hash in Raku idiom. One could call it RakuON by analogy with JSON. But you will also see that because it is normal Raku code, we can include comments as well. I have also commented-out the CSS line, as we will discuss CSS below.

The template is provided by ‘deprecate-template.raku’.

Although multiple templating engines, such as RakuClosure and Mustache, can also be used with ProcessedPod, I have not yet had enough time to develop the HTML2 plugins to use more than one. So I will use the default RakuClosureTemplates system here.

Basically all RakuClosure templates are contained in a Raku program that returns a Hash (like config.raku). The keys of the Hash are the names of the Pod-Block. The values for the keys are closures, viz., a sub that accepts two Hash parameters (conventionally %prm and %tml). The first (%prm) contains all the parameters passed by ProcessedPod to the template, and the second (%tml) contains all the templates known to ProcessedPod. So any template can call any template. (Currently, circularity is not detected). The sub must return a Str, which is inserted into the final html file. Plugins create a template Hash whose keys (new templates) are added to the default keys.

The ProcessedPod renderer passes (at least) two parameters to a template for a FormatCode in the %prm hash. These are contents, which is the first part of the FormatCode, and meta, which is the part after the |.

So we create a file called deprecate-template.raku with the following contents:

%(
    format-d => sub (%prm, %tml) { # note that the format letter is lower case
        '<span class="raku-deprecation" title="' ~ %prm<meta> ~ '">'
        ~ %prm<contents>
        ~ '</span>'
    },
)

We also have to tell that there is a new plugin, so we run

Rakudoc-to-html --add-plugins='deprecate-span' test-d.rakudoc

(add-plugins can take a space delimited list of plugins)

Now we have the correct text without an error, and if we put a mouse over the word ‘function’, we will get the deprecation string. In order to highlight the span so that the user can be prompted to hover a mouse over the text, we need to have some CSS.

By way of example, put the following CSS in the file deprecate-span.css (remember the HTML class raku-deprecation was included in the template):

.raku-deprecation {
	background-color: bisque;
	border-block-color: blue;
	border-width: 1px;
	border-style: dashed;
	border-radius: 5px;
}

We need to uncomment the :add-css line in config.raku. deprecate-span.css is assumed to be a valid CSS file and it will be transferred to test/asset_files/css/ by Pod::To::HTML2. Pod::To::HTML2 also creates the stylesheet reference in the HTML header so that it is served too.

Run the file again

Rakudoc-to-html --add-plugins='deprecate-span' test-d.rakudoc

and the CSS has been added. Obviously, a lot more CSS tricks can be played, but I just wanted to show some CSS.

There is much more to the plugin process, including the ability to add JQuery and images. In order to examine copies of the distributed plugins into your local test directory, run the following in that directory.

Rakudoc-to-html get-local

Rendered from newplugin at 2022-12-12T22:11:57Z