Proving a renderer

A file with many RakuDoc components and some idea about what is expected.

Table of Contents

SYNOPSISPurposeThis is a first heading  - This is a second level heading    - This is third level headingThis is a numbered heading, level 1  - This is a second level heading    - A third level    - Another third level  - Back to second    - A third level    - Another third levelLists  - Taking a bulletBlocks that are processed differently  - Unrelenting hypeThis is an extraordinary paragraphSome tablesAdding index entries to your textScoping examplesPlacementsEnumerated blocksPHYSICS  - Newtonian  - RelativisticPHYSICS  - Newtonian  - RelativisticHeading  - Subheading    - Subsubheading    - SubsubheadingHeading  - Subheading    - Subsubheading    - SubsubheadingHeading  - Subheading    - Subsubheading    - SubsubheadingHeading  - Subheading    - Subsubheading    - SubsubheadingHeading  - Subheading    - Subsubheading    - SubsubheadingHeading  - Subheading    - Subsubheading    - SubsubheadingHeading  - Subheading    - Subsubheading    - SubsubheadingHeading  - Subheading    - Subsubheading    - SubsubheadingSecond headingHeading  - Subheading    - Subsubheading    - SubsubheadingSecond headingHeading  - SubheadingSecond headingCreditsLICENSEVERSION

SYNOPSIS

Assuming a new renderer has been developed and installed (eg using zef) at Rakudoc::To::MyRender, the render this file using a raku --rakudoc=MyRenderer terminal command. The renderer will be consistent with the RakuDoc v2 specification if all the blocks are rendered appropriately, and warnings are generated by the statements marked as incorrect below.

Purpose

This file is intended to prove a RakuDoc v2 renderer. It can be used in several ways:  • to generate the AST representation of all the RakuDoc components in the specification  • to prove a renderer that a new renderer should be able to process this file  • to visualise how the final output of a RakuDoc source will look after processingAn attempt has been made to utilise all RakuDoc components, it is not an exhaustive test of all components in all possible combinations. Please suggest additional combinations if they turn out to have unusual effects.Several mistakes have been included where the RakuDoc v2 specification indicates how inconsistent behaviours or unknown components should be handled.The the end of the rendering of this source file, a number of warning messages should be included.

Short table of contents

SYNOPSISPurposeThis is a first headingThis is a numbered heading, level 1ListsBlocks that are processed differentlyThis is an extraordinary paragraphSome tablesAdding index entries to your textScoping examplesPlacementsEnumerated blocksPHYSICSPHYSICSHeadingHeadingHeadingHeadingHeadingHeadingHeadingHeadingSecond headingHeadingSecond headingHeadingSecond headingCreditsLICENSEVERSION

A short index

elements to be placed: This is third level heading

formatting code: Adding index entries to your text

index: Adding index entries to your text, Adding index entries to your text

inline formatting: Adding index entries to your text

This is a first heading

text

This is a second level heading

text

This is third level heading

A paragraph to illustrate Basis type formatting.A paragraph to illustrate Important type formatting.A paragraph to illustrate Unusual type formatting.A paragraph to illustrate Strikethrough type formatting.A paragraph to illustrate Superscript type formatting. (For text output, many terminals do not support superscript/subscript font positions, so consider using a colouration as well.)A paragraph to illustrate Subscript type formatting.A paragraph to illustrate Code type formatting. It can contain other markup, eg. A<> markup.A paragraph to illustrate Verbatim type formatting. It can contain other RakuDoc, eg. P<defn:Happy> without executing it.A paragraph to illustrate some >< formatting (in the source has Z<Zero width> between >< ).A paragraph to illustrate Keyboard formatting.A paragraph to illustrate Replacement formatting.A paragraph to illustrate Terminal formatting.A paragraph to illustrate several G<G undefined type>, Q<Q undefined type>, W<W undefined type>, Y<Y undefined type> formatting; warnings are expected.Various entities are possible such as « or the same thing using unicode «. Entities can be double unicodes, such as 🇺🇦, which is the Ukrainian flag.In case you have forgotten, here is something aliased at the start: Do not consider this a disquisition of possible combinations.This is an example of an Alias where A<DECLARATION> was replaced by the contents of the =alias directive. Aliases are scoped, see below, but cannot be specified before being used in the document. Here is an undeclared forward reference, which was written as A<an undeclared|XXX>. The use of an undeclared alias causes a warning.We can also make an inline definition. This whole paragraph will be referenced later.A developer note can be attached highly deprecated[for v1.2.3 ^.. v2.0.0] to text. A renderer may show the text or only show it for contexts compliant with the version.But a note without meta no versioning here is ignored and a warning generated.When we want a formula \sum \frac{1}{n^{2}} = \frac{\pi^{2}}{6} use F<> markup.Links can be made internally [say to the first heading](This is a first heading) or externally say to the raku documentation site.A renderer should provide the opportunity to customise text using M<...|..,..;...> markup. The renderer should not recognise this functionality and issue a warning.A note [ 1 ] will not itself be rendered inline, but the text will be rendered in a footnote or popup. A marker or number will be rendered to point to the text.Suppose we want to place the definition Im-a-doppelganger ⦗We can also make an inline definition. This whole paragraph will be referenced later.

⦘ here. And to confound pedants, here is a definition Happy ⦗Happy

  when not blue

⦘ defined using a =defn block.Normally extra spaces are removed with paragraphs, but sometimes we truly dot dot dot   dash dash dash       want them.Good text will contain elements to be placed in an index. The index has already been placed at the start of the document, although content is generated here.

3.This is a numbered heading, level 1

text

3.1.This is a second level heading

text

3.1.1.A third level

text

3.1.2.Another third level

text

3.2.Back to second

text

3.2.1.A third level

Although this heading has the same text in the heading, the Table of Contents should provide a unique target for it (this may not be possible in some formats such as MarkDown)

3.2.2.Another third level

text

Lists

Unnumbered up to four levels of bulleting are required, a renderer can offer more.  • The start of a unnumbered item list  • Next item    ▹ now next level    ▹ another at two      ‣ a third level        ⁃ fourth level        ⁃ fourth level          ∙ level five            ∙ level six              ∙ level seven  • reset to level one      ‣ jump levels

to put space between lists, probably a =para without text is needed.1.The start of a numbered item list 2.Next item 2.1.now next level 2.2.another at two 2.2.1.a third level 3.reset to level one 3.1.1.jump levels   • an unnumbered item4.1.but we can resume after a break

Definitions

  can be placed in lists

Happy

  when not blue

Blue

  when not happy

Being assertive

  Just shout why don't you?

This is an ordinary paragraph

1.Lemma 1

  do not make trouble

2.Lemma 2

  do not shout at people

3.Lemma 3

  just phone the SWAT team

An ordinary paragraph creates the definition list.

4.Lemma 4

  Claim you are the victim here

Taking a bullet

The project originally consisted of five phases, of which two are already complete and two have been abandoned:  ☑ Investigate existing solutions  ☑ Define a minimal initial feature set  ☐ Implement this minimal set of features  ☒ Secure 100 million in venture capital  ☒ Abscond to the Bahamas with the cashThe major sources of sustainable energy are:  🌍 wind  🌍 hydroelectric  🌍 solar  🌍 geothermal  🌍 fusion    🤞 (eventually)

Blocks that are processed differently

my $x = 2;
# a brilliant program!

my $x = 3;
# a renderer should observe the basis markup
# and the markup but render R<markup> verbatim

# indenting causes an implicit code block
my $raku = 'fantastic';

  --- input --- 
This is a text with basis markup that conserves
all spacing      when trying    to get column
just using       white spaces   naively
better           to             use tables

  --- output --- 
This is almost the same as input
but may have a different styling

Occasionally some text that is inset from the margin is required. So enclose it in a nested block.

The following semantic block was included at the beginning in source, but it is now included here.

Unrelenting hype

Richard Hainsworth, aka finanalyst

Fabulous identity

e^{i\pi}+1=0

A customised block

=begin MyBlock :caption<A customised block> :headlevel(2)

Actually it fails because no customisation has been made.
It
should
be
rendered without spaces      being chewed up.
=end MyBlock

Some silly text which will have its own extraordinary ToC entryYou are reminded that: Do not consider this a disquisition of possible combinations.

Some tables

Adding index entries to your text

An index entry is an inline formatting code that is rendered normally (i.e. with no special identifying styling) within the text, but which is also added to the index. Index entries may be specified with subentries, including multilevel subentries, though a renderer is not required to represent anything more than the first level. A single index entry can specify two or more separate entries in the index, all of which will refer back to the same point in the text.

Scoping examples

Configuration and aliases are scoped.Without configuration embedded B<markup> is rendered verbatim.With configuration embedded basis markup is rendered.How short the season when roses are red. But configuration directives only B<apply> inside a block scope.Did I mention before that: Do not consider this a disquisition of possible combinations.

Placements

Renderers are required to place text and RakuDoc sources, but may fallback to text messages for other formats.

Text placement

Link ｢https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/fanciful-disclaimer.txt｣ caused LibCurl Exception, response code ｢0｣ with error ｢Could not resolve host: github.com｣

RakuDoc placement

Link ｢https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/bootiful-disclaimer.rakudoc｣ caused LibCurl Exception, response code ｢0｣ with error ｢Could not resolve host: github.com｣

HTML placement

Link ｢https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/paneful-disclaimer.html｣ caused LibCurl Exception, response code ｢0｣ with error ｢Could not resolve host: github.com｣

JPEG image placement

Link ｢https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/camelia.jpeg｣ caused LibCurl Exception, response code ｢0｣ with error ｢Could not resolve host: github.com｣

Png image placement

Link ｢https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/camelia.png｣ caused LibCurl Exception, response code ｢0｣ with error ｢Could not resolve host: github.com｣

Enumerated blocks

11.PHYSICS

11.1.Newtonian

11.2.Relativistic

Formula2.Mass-Energy Equivalence

E = MC²

TOPIC L - PHYSICS

Newtonian [subtopic L1]

Relativistic [subtopic L2]

Equation 3: Mass-Energy Equivalence

E = MC²

Equation 4: Mass-Energy Equivalence

E = MC²

TOPIC M - Heading

Subheading [subtopic M1]

13.1.1.Subsubheading

Equation 5: Caption for first formula

E = MC²

Equation 6: Caption for second formula

E = MC²

13.1.2.Subsubheading

Equation 7: Caption for first formula

E = MC² Here we can use the formula enumerations, viz.  • Default is  • Instance configured is

TOPIC N - Heading

Subheading [subtopic N1]

14.1.1.Subsubheading

Equation 8: Caption for first formula

E = MC²

Equation 9: Caption for second formula

E = MC²

14.1.2.Subsubheading

Equation 1: Caption for first formula

E = MC²

TOPIC O - Heading

Subheading [subtopic O1]

15.1.1.Subsubheading

Equation 1: Caption for first formula

E = MC²

Equation 2: Caption for second formula

E = MC²

15.1.2.Subsubheading

Equation 1: Caption for first formula

E = MC²

TOPIC P - Heading

Subheading [subtopic P1]

16.1.1.Subsubheading

Equation 4: Caption for first formula

E = MC²

Equation 6: Caption for second formula

E = MC²

16.1.2.Subsubheading

Equation 9: Caption for first formula

E = MC²

TOPIC Q - Heading

Subheading [subtopic Q1]

17.1.1.Subsubheading

Equation 2: Caption for first formula

E = MC²

Equation 4: Caption for second formula

E = MC²

17.1.2.Subsubheading

Equation 7: Caption for first formula

E = MC²

TOPIC R - Heading

Subheading [subtopic R1]

18.1.1.Subsubheading

Equation 2: Caption for first formula

E = MC²

Equation 4: Caption for second formula

E = MC²

18.1.2.Subsubheading

Equation 3: Caption for first formula

E = MC²

TOPIC S - Heading

Subheading [subtopic S1]

19.1.1.Subsubheading

Equation 1: Caption for first formula

E = MC²

Equation 2: Caption for second formula

E = MC²

19.1.2.Subsubheading

Equation 1: Caption for first formula

E = MC²

TOPIC T - Heading

Subheading [subtopic T1]

20.1.1.Subsubheading

Equation 2: Caption for first formula

E = MC²

Equation 4: Caption for second formula

E = MC²

20.1.2.Subsubheading

Equation 7: Caption for first formula

E = MC²

TOPIC U - Second heading

TOPIC V - Heading

Subheading [subtopic V1]

22.1.1.Subsubheading

Equation 2: Caption for first formula

E = MC²

Equation 4: Caption for second formula

E = MC²

22.1.2.Subsubheading

Equation 5: Caption for first formula

E = MC²

TOPIC W - Second heading

Equation 7: Caption for next formula

E = MC²

TOPIC X - Heading

2.Item the first 3.Item the second

4.Item the third

Subheading [subtopic X1]

5.Item the fourth

Equation 2: Caption for first formula

E = MC²

6.Item the fifth

Equation 3: Caption for second formula

E = MC²

7.Item the sixth

TOPIC Y - Second heading

8.Item the seventh

Equation 4: Caption for next formula

E = MC²9.Item the eighth

Text finishes after version number

Credits

Richard Hainsworth, aka finanalyst

LICENSE

Artistic-2.0

VERSION

Footnotes

1 |^| such as this one

Index

elements to be placed: This is third level heading

formatting code: Adding index entries to your text

index: Adding index entries to your text, Adding index entries to your text

   entry: Adding index entries to your text, Adding index entries to your text

      nested: Adding index entries to your text

   multiple entries: Adding index entries to your text

   subentry: Adding index entries to your text

      multilevel: Adding index entries to your text

      rendering: Adding index entries to your text

inline formatting: Adding index entries to your text

Rendered from resources/compliance-rendering/rakudociem-ipsum.rakudoc/rakudociem-ipsum at 11:45 UTC on 2026-01-09

Source last modified at 10:54 UTC on 2026-01-09

WARNINGS

1: ｢G｣ is not defined, but is reserved for future use in block ｢rakudoc｣ with heading ｢This is third level heading｣.

2: ｢Q｣ is not defined, but is reserved for future use in block ｢rakudoc｣ with heading ｢This is third level heading｣.

3: ｢W｣ is not defined, but is reserved for future use in block ｢rakudoc｣ with heading ｢This is third level heading｣.

4: ｢Y｣ is not defined, but is reserved for future use in block ｢rakudoc｣ with heading ｢This is third level heading｣.

5: Unknown or as yet undeclared alias ｢XXX｣ in block ｢rakudoc｣ with heading ｢This is third level heading｣ over-riden by ｢an undeclared｣

6: Δ<> markup ignored because it has no version/note content ｢Δ<no versioning here>｣ in block ｢rakudoc｣ with heading ｢This is third level heading｣.

7: Markup-M failed: template ｢PayMeMoreApp｣ does not exist. Got ｢M<should not recognise this functionality|PayMeMoreApp; user-id>｣

8: No template exists for custom block ｢MyBlock｣. It has been rendered as unknown in block ｢MyBlock｣ with heading ｢MyBlock｣.

9: Link ｢https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/fanciful-disclaimer.txt｣ caused LibCurl Exception, response code ｢0｣ with error ｢Could not resolve host: github.com｣

10: Link ｢https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/bootiful-disclaimer.rakudoc｣ caused LibCurl Exception, response code ｢0｣ with error ｢Could not resolve host: github.com｣

11: Link ｢https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/paneful-disclaimer.html｣ caused LibCurl Exception, response code ｢0｣ with error ｢Could not resolve host: github.com｣

12: Link ｢https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/camelia.jpeg｣ caused LibCurl Exception, response code ｢0｣ with error ｢Could not resolve host: github.com｣

13: Link ｢https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/camelia.png｣ caused LibCurl Exception, response code ｢0｣ with error ｢Could not resolve host: github.com｣