RakuDoc renderer

Renders RakuDoc sources into an output format dependent on templates

---

Table of Contents

SYNOPSIS
Overview
  - Table of outputs and renderers
Documentation
RenderTextify utility
Wrapping
Troubleshooting
Credits

---

SYNOPSIS

  • Clone the repository
  • Install using zef as follows (flag is important)

zef install . -/precompile-install

---

Overview

This distribution is intended to provide several renderers from RakuDoc v2 into commonly used output formats.

The basic render engine is RakuDoc::Render, which renders into Text. It is designed to be extended to other output formats by subclassing.

Currently, the other renderers in this distribution are:

Table of outputs and renderers

Output	Renderer	Documentation
Text	RakuDoc::To::Generic	a wrapper for RakuDoc::Render
Markdown	RakuDoc::To::Markdown	Markdown
HTML	RakuDoc::To::HTML	A minimal, single file, 'all in' HTML
HTML-Extra	in development	HTML output using Bulma CSS, Graphviz, Leaflet-Maps, Latex, assumes internet
This is software using bleeding edge Rakudo, so look at troubleshooting below.

Using the Generic renderer, the canonical method for generating rendered text is possible (which sends output to STDOUT, so pipe to a file), namely

RAKUDO_RAKUAST=1 raku --rakudoc=Generic rakudociem-ipsum.rakudoc > store-output

Some naive wrapping and width modification is possible using environment variables.

The file rakudociem-ipsum.rakudoc is the file for testing RakuDoc v2 compliance. It can be obtained with:

bin/get-compliance-document

In order to avoid environment variables, eg for Windows, a RakuDoc file can be rendered to Text using the RenderTextify. It avoids some installation problems, stores the output and offers some other output options, eg.

bin/RenderTextify rakudociem-ipsum

(the .rakudoc extension may be omitted if desired)

---

Documentation

The two main documentation sources are:

  • An overview of the generic renderer

  • The templating system

Other modules are also documented:

  • Processed - objects to keep track of intermediate state

  • PStr - Strings containing forward references

  • ScopedData - an object to keep track of data valid for a block scope

  • a table of the minimum set of templates to render any RakuDoc source

  • a grammar for parsing the meta data of a Markup code

  • an object for numerating items headings

---

RenderTextify utility

The utility bin/RenderTexify can be called with a RakuDoc source and it saves the result directly to a file, rather than to STDOUT.

For example,

bin/RenderTextify rakudociem-ipsum

will produce the file

rakudociem-ipsum.rakudoc.text

The executable bin/RenderTexify can also be called with the flags test and pretty and the name of a file to render. The use case of these options is to see what templates receive from the rendering engine when developing new templates.

The file is output to text files with the flag and .text appended to the name. The file format .rakudoc is assumed, and added if missing.

For example,

bin/RenderTextify --pretty rakudociem-ipsum

will produce the file

rakudociem-ipsum.rakudoc.pretty.text

---

Wrapping

The text output will be naively wrapped (the algorithm is still being developed), either by setting the environment variable POSTPROCESSING=1 or using RenderTextify. For example,

POSTPROCESSING=1 RAKUDO_RAKUAST=1 raku --rakudoc=Generic doc.rakudoc > store-output

or

bin/RenderTextify --post-processing doc

If the environment variable WIDTH (--width) is also set, the text output will be wrapped to the value. WIDTH by default is set at 80 chars. To set at 70, use:

POSTPROCESSING=1 WIDTH=70 RAKUDO_RAKUAST=1 raku --rakudoc=Generic doc.rakudoc > store-output

or

bin/RenderTextify --post-processing --width=70 doc

---

Troubleshooting

In order to get the RakuDoc render test file (rakudociem-ipsum) to work, a recent version of the Rakudoc compiler is needed, after v2024.06.

If the cannonical command above fails, perhaps with a message such as

===SORRY!===
    This element has not been resolved. Type: RakuAST::Type::Simple

then try

RAKUDO_RAKUAST=1 raku -I. -MRakuDoc::Render --rakudoc=Generic rakudociem-ipsum.rakudoc > store-output

The command above may also generate an error, such as

    ===SORRY!=== Error while compiling ..... (OO::Monitors)
    Variable '$cond' is not declared.  Perhaps you forgot a 'sub' if this
    was intended to be part of a signature?
    at ....
    ------> macro wait-condition(⏏$cond) is export {
because the RakuAST compiler does not yet handle macros, and (OO::Monitors) uses them.

The first step is to re-run the test files, eg.,

prove6 -I.

This causes a recompilation of the modules in this distribution to be recompiled because the tests run isa-ok on each module.

This is sometimes not sufficient. The next step is to use the utility bin/force-compile in the root of the repo. It deletes the .precomp files in the current directory, and runs prove6 -I..

---

AUTHOR

Richard Hainsworth aka finanalyst

---

VERSION

v0.3.1

---

---

Rendered from ./docs/./docs/README.rakudoc at 21:43 UTC on 2024-06-29

Source last modified at 21:27 UTC on 2024-06-29