New Pod Blocks
ErrorsCollection
These are the cool possibilities using the Collection and Raku::Pod::Render distributions.
(The repeated headings in the Table of Contents are deliberate, as will become clear in this text.)
For example, <hr> .
=for HR :class<yellowish-dots>=for HR :class<bluish-dots>=for HR :class<greenish-dots>
renders as
Raku::Pod::Render introduces the idea of 'plugins' to keep block names and the templates associated with them together. Collection takes the concept further by having plugins that can run Raku programs at each stage of the Collection process, after the Mode has been configured.
Plugins keep the CSS, templates and new custom block names in the same sub-directory.
This mechanism also means that Mode specific output, such as scripts and CSS for HTML output can be managed by Mode plugins. The Website mode for Collection-Raku-Documentation contains plugins to gather CSS, jQuery scripts, js libraries, and Images from other plugins, and collate them so that they are served with each page.
Since the entire page is in a template, it is also possible to create separate page templates, with different CSS assets.
The following are Custom user-facing Pod::Blocks that come with Collection-Raku-Documentation
For Raku files, a special block was created for the various types of Camelia image. They normally float on the right-hand side. In order to contain them before the next set of texts, they are included in an HTML5 flex-box, which is created using a template for para.
The following code
=begin para :template<flex-container>=Camelia=CameliaShadow=CameliaFaded=end para
yields
Suppose you want a different template to act on an existing block, like Para, which is coded as HTML p. For example,
I like this sonnet:=for para :template<quotation> :author<William Shakespeare> :citation<Sonnet 116>Let me not to the marriage of true minds\nAdmit impediments; love is not love\nWhich alters when it alteration finds,\nOr bends with the remover to remove.
I like this sonnet:
Let me not to the marriage of true minds
Admit impediments; love is not love
Which alters when it alteration finds,
Or bends with the remover to remove.
Sonnet 116
Here is an example where the format code F has been leveraged to generate FontAwesome icons. The plugin here utilises v4.7. The API for v5 / 6 is different, so another plugin may be needed.
Since Raku treats all Unicode characters the same, Chinese/Arabic/Cyrillic glyphs can now be specified to repeat or alias the predefined codes of B C I K T U E Z X N L P V .
Some FontAwesome iconsF<fa-ambulance> Example of ambulanceF<fa-automobile> Example of automobile (alias)F<fa-bicycle> Example of bicycleF<fa-bus> Example of busF<fa-truck> Example of truckF<fa-wheelchair> Example of wheelchairF<fa-wheelchair-alt> Example of wheelchair-alt
Generates Some FontAwesome icons
Example of ambulance
Example of automobile (alias)
Example of bicycle
Example of bus
Example of truck
Example of wheelchair
Example of wheelchair-alt
FontAwesome has some other options.
Train normal size F<fa-train> Triple size train F<fa-train|fa-3x>An animated spinner F<fa-refresh|fa-spin fa-3x fa-fw>
Generates
Train normal size Triple size train
An animated spinner
Notice how these examples leverage off the idea of meta data together with a Format Code. This is not standard Rakudoc (aka POD6), as this metadata is only specified for X<> and L<> . Raku::Pod::Render allows for metadata to be added to any non-standard letter used as a Format Code, and any Unicode thingy that Raku treats as a "character" to be made into a Format Code.
When many Rakudoc files are included in a collection, there is a need to collect data from each. So for example, the Raku Documentation files all have metadata associated with the first pod definition. We need to collect files according to the metadata. The keys kind, subkind, and category are allocated to all Raku Documents.
=for ListFiles :select<kind=Programs>Programs that support Raku development
renders as
Programs that support Raku development
Modules and applications used to debug Raku programs
How to run Rakudo, a Raku implementation, and modify its behavior with environment variables.
rakudoc - the Raku pod reader
How to run Rakudo, a Raku implementation, and the command line options you can use with it.
=for ListFiles :select<kind=Programs> :headlevel(0)Programs that support Raku development, title is not included in the TOC.
Programs that support Raku development, title is not included in the TOC.
Modules and applications used to debug Raku programs
How to run Rakudo, a Raku implementation, and modify its behavior with environment variables.
rakudoc - the Raku pod reader
How to run Rakudo, a Raku implementation, and the command line options you can use with it.
Other examples of ListFiles can be seen in the TOC and Itemised index pages.
Content files today, especially for the Web, rely on images.
=for Image :src<images/octopus_build.gif> :class<justify-center>New searching functionality is being developed
Generates an image with the text in the Table of Contents. The TOC entry can be eliminated with a :headlevel(0).
All websites need JQuery plugins or JS scripts. Collection creates the infrastructure for these plugins to be written and added to a site.
For example, the filterlines plugin uses a small JQuery script, adds some html around existing Rakudoc content and handles everything else. (Try typing 'R' then 'e' in the search box).
=begin filterlines=for ListFiles :select<kind=Programs>Programs that support Raku development=end filterlines
renders as
Programs that support Raku development
Modules and applications used to debug Raku programs
How to run Rakudo, a Raku implementation, and modify its behavior with environment variables.
rakudoc - the Raku pod reader
How to run Rakudo, a Raku implementation, and the command line options you can use with it.
The leafletmap plugin inserts a map in place of the =LeafletMap Pod::Block using the fabulous Leaflet JS library. The map MUST have a fixed height, so this is specified in the config file. However, height and width should be set by CSS, but it is not clear what the best way is to signal that a CSS value is available from CSS in the config file.
By default, the map will point at Cardiff Castle in Cardiff, Wales with a 200px height and 16 unit magnification, using OpenStreetMap as the tile provider. So
=Leafletmap
produces:
The simplest customisation is to centre the map by specifying the lattitude and longitude, and to change the starting zoom level (smaller numbers are larger views). It is also possible to change the height of the map. Each map on a page must have its own id. Additionally, when developing a page, not setting a width is tiresome. Note another very underutilised feature of Rakudoc, the ability to spread meta-data accross lines. The first virtual column must start in a = and there must be at least one horizontal whitespace character. Thus
=for Leafletmap= :lat(55.948595) :long(-3.199913)= :zoom(13) :height<300px>= :id<new-map>= :headlevel(2)= :width<50vw>Edinburgh Castle
will produce
Maps are generated from tiles and the information can be rendered in many ways. There are multiple tile providers, collected in a github resource leaflet-extras. "Leaflet-providers provides tile layers from different providers, including OpenStreetMap, Stamen, Esri and OpenWeatherMap. The full listing of free to use layers can be previewed." (from README of leaflet-providers)
Some providers have map types that do not need registration, most types need registration. Here are all the providers and variants.
For example, is a map with the Esri.WorldImagery provider[.variant] string.
=for LeafletMap :provider<Esri.WorldImagery> :id<third-map> :width<50vw>
Registration offers more variety and more complex maps, but goes beyond the generic Collection plugin.
However, the extra customisation is possible by changing the config file and the template for the =Leafletmap block.
For example, suppose you have registered with Thunderforest and obtained an api-key, eg. xxxx. Then in config.raku uncomment 'api-key' and insert your key in place of ????. The template already allows for an apikey field, but some providers require other variable names, or two variables. More information can be found in leaflet-extras.
Another common need is to put markers on a map. This can be done using =LeafMarker blocks. The map-id of the map the markers are to be associated with has to be supplied if there are more than one maps on a page, otherwise the default map id is used.
:popup<text> associated the text with the marker but the user needs to click in it to see.
:title<text> allows for the text to be visible with a mouseover.
:fa-icon will work if the FontAwesome plugin has been configured for rendering (see above for detail on extra commands).
:headlevel(0) is set so that the Table of Contents is not affected.
=for LeafletMap :id<map-four> :height<600px> :zoom(12) :width<50vw>=for LeafMarker= :map-id<map-four> :name<mk1>= :lat(51.48160) :long(-3.18070)= :headlevel(0)= :title<Cardiff Castle>=for LeafMarker= :map-id<map-four>= :lat(51.529269) :long(-3.188109)= :fa-icon<fa-cutlery fa-spin fa-3x fa-fw>= :headlevel(0)= :title<Fintans Fish & Chip Co>=for LeafMarker= :map-id<map-four>= :lat(51.502576) :long(-3.190222)= :fa-icon<fa-cutlery>= :headlevel(0)= :popup<Yan’s Fish Bar>
Thus for two chippies judged the best in Cardiff at the time of writing:
This block introduces a directed graph in the dot language. It is rendered into HTML as an svg using the dot program. Since a graph data is require, only the delimited form of the block (starting with =begin/=end) will be used.
The following diagraph comes from the dot documentation. The following Rakudoc
=begin Graphviz :headlevel(0)digraph G {main -> parse -> execute;main -> init;main -> cleanup;execute -> make_string;execute -> printfinit -> make_string;main -> printf;execute -> compare;}=end Graphviz
produces
This plugin block sends the Latex markup to the CodeCogs online equation editor. For example,
=for Latex :headlevel(0)\begin{align*}\sum_{i=1}^{k+1} i^{3}&= \biggl(\sum_{i=1}^{n} i^{3}\biggr) + i^3\\&= \frac{k^{2}(k+1)^{2}}{4} + (k+1)^3 \\&= \frac{k^{2}(k+1)^{2} + 4(k+1)^3}{4}\\&= \frac{(k+1)^{2}(k^{2} + 4k + 4)}{4}\\&= \frac{(k+1)^{2}(k+2)^{2}}{4}\end{align*}
If a block is used in a Rakudoc document that is misspelt or a Custom plugin has not been correctly defined, then the ProcessedPod renderer will render the block as an Unknown Name with an error message. For example, suppose 'head' is misspelt as 'header'.
=header1 This should be a headerThis is some text
renders as:
This is some text