Proving a renderer

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

=begin rakudoc :one-option<first> :another-option(2)

AUTHORS

Richard Hainsworth, aka finanalyst

VERSION

v0.2.1

LICENSE

Artistic-2.0

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 processing

An 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.

=place toc:1 :caption<Short table of contents>

=place index:1 :caption<A short index>

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 █ █████████ ████, 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 A<an undeclared|XXX> 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|v1.2.3 ^.. v2.0.0; highly deprecated> 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 use F<> markup.

Links can be made internally say to the first heading or externally say to the raku documentation site.

A renderer should provide the opportunity to customise text using M<...|..,..;...> markup. The renderer M<should not recognise this functionality|PayMeMoreApp; user-id> 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 P<defn:Im-a-doppelganger> here. And to confound pedants, here is a definition P<defn:Happy> 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.

=numhead This is a numbered heading, level 1

text

=numhead2 This is a second level heading

text

=numhead3 A third level

text

=numhead3 Another third level

text

=numhead2 Back to second

text

=numhead3 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)

=numhead3 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.

=numitem The start of a numbered item list =numitem Next item =numitem2 now next level =numitem2 another at two =numitem3 a third level =numitem1 reset to level one =numitem3 jump levels

an unnumbered item =counter item :restart =for numitem2 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

=numdefn Lemma 1 do not make trouble

=numdefn Lemma 2 do not shout at people

=numdefn Lemma 3 just phone the SWAT team

An ordinary paragraph creates the definition list.

=counter numdefn :restart =for numdefn 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 cash

=begin section

The major sources of sustainable energy are:

wind
hydroelectric
solar
geothermal
fusion

(eventually) =end section

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';

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

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. =place semantic:AUTHORS :caption<Unrelenting hype> :headlevel(2)

Fabulous identity

Some silly text which will have its own extraordinary ToC entry

You are reminded that: Do not consider this a disquisition of possible combinations.

Some tables

A visual table
Animal	Legs	Eats
Zebra	4	Cookies
Human	2	Pizza
Shark	0	Fish

A visual table with a stupendously long caption
Animal	Legs	Eats
Zebra	4	Cookies
Human	2	Pizza
Shark	0	Fish

:header

=column

A procedural table
Date	Samples	Mean
Sample 1	Sample 2	Sample 3
2023-03-08	2023-04-14	2023-06-23 =column	0.4	0.8	0.2 =column	0.1	0.6	0.9 =column	0.3	0.5	0.0 =column	0.26667	0.63333	0.36667
Mean:	0.46667	0.53333	0.26667	0.42222

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.

=begin section

With configuration embedded B<basis> markup is rendered.

How short the season when roses are red. =end section But configuration directives only B<apply> inside a block scope.

Did I mention before that: roses are red

Placements

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

=place https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/fanciful-disclaimer.txt :caption<Text placement> :headlevel(2) =place https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/bootiful-disclaimer.rakudoc :caption<RakuDoc placement> :headlevel(2) =place https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/paneful-disclaimer.html :caption<HTML placement> :headlevel(2) =place https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/camelia.jpeg :caption<JPEG image placement> :headlevel(2) =place https://github.com/Raku/RakuDoc-GAMMA/raw/main/compliance-files/camelia.png :caption<Png image placement> :headlevel(2)

Enumerated blocks

The heading from now on will not be included in the Table of Contents

=numhead1 PHYSICS =numhead2 Newtonian =numhead2 Relativistic =begin numformula :caption<Mass-Energy Equivalence> e^{ipi}+1=0 =end numformula

=numhead1 PHYSICS =numhead2 Newtonian =numhead2 Relativistic =begin numformula :caption<Mass-Energy Equivalence> :numalias<RELFORM> e^{ipi}+1=0 =end numformula =begin numformula :caption<Mass-Energy Equivalence> :numalias< Equation %N. | EQNFORM> e^{ipi}+1=0 =end numformula

=begin section =numhead1 Heading =numhead2 Subheading =numhead3 Subsubheading =for numtable1 :caption< Caption for first table > | one | two | =for numformula1 :caption< Caption for first formula > e^{ipi}+1=0 =for numtable1 :caption< Caption for second table > | one | two | =for numformula1 :caption< Caption for second formula > e^{ipi}+1=0 =numhead3 Subsubheading =for numtable1 :caption< Caption for first table > | one | two | =for numtable1 :caption< Caption for second table > | one | two | =for numformula1 :caption< Caption for first formula > e^{ipi}+1=0 =end section

Here we can use the formula enumerations, viz.

Default is A<RELFORM>
Instance configured is A<EQNFORM>

=begin section =numhead1 Heading =numhead2 Subheading =numhead3 Subsubheading =for numtable1 :caption< Caption for first table > | one | two | =for numformula1 :caption< Caption for first formula > e^{ipi}+1=0 =for numtable1 :caption< Caption for second table > | one | two | =for numformula1 :caption< Caption for second formula > e^{ipi}+1=0 =numhead3 Subsubheading =for numtable1 :caption< Caption for first table > :!continued | one | two | =for numtable1 :caption< Caption for second table > | one | two | =for numformula1 :caption< Caption for first formula > :!continued e^{ipi}+1=0 =end section

=begin section =counter table1 :restart-after< head3 > =counter formula :restart-after< head3 >

=numhead1 Heading =numhead2 Subheading =numhead3 Subsubheading =for numtable1 :caption< Caption for first table > | one | two | =for numformula1 :caption< Caption for first formula > e^{ipi}+1=0 =for numtable1 :caption< Caption for second table > | one | two | =for numformula1 :caption< Caption for second formula > e^{ipi}+1=0 =numhead3 Subsubheading =for numtable1 :caption< Caption for first table > | one | two | =for numtable1 :caption< Caption for second table > | one | two | =for numformula1 :caption< Caption for first formula > e^{ipi}+1=0 =end section =begin section

=begin section

=begin section =counter TablesAndFormulae :restart-after< head3 >

=begin section =counter formula1 :restart-after< head3 > :prefix< head3 > =counter table1 :restart-after< head3 > :prefix< head3 >

=begin section

=counter TablesAndFormulae :prefix< head1 >

=begin section

=counter TablesAndFormulae :prefix< head1 >

=counter SpecialTable :restart(1000) =for numtable1 :caption< Caption for first table > | one | two | =for numformula1 :caption< Caption for first formula > e^{ipi}+1=0 =for numtable1 :caption< Caption for second table > | one | two | =end section =numhead1 Second heading =for numtable1 :caption< Caption for next table > | one | two | =for numformula1 :caption< Caption for next formula > e^{ipi}+1=0 =end section

=begin section =counter item :restart-except-after< item1 head1 table formula >

=numhead1 Heading =numitem Item the first =numitem Item the second =for numtable1 :caption< Caption for first table > | one | two | =numitem Item the third =numhead2 Subheading =numitem Item the fourth =for numformula1 :caption< Caption for first formula > e^{ipi}+1=0 =numitem Item the fifth =for numtable1 :caption< Caption for second table > | one | two | =for numformula1 :caption< Caption for second formula > e^{ipi}+1=0 =numitem Item the sixth =numhead1 Second heading =numitem Item the seventh =for numtable1 :caption< Caption for next table > | one | two | =for numformula1 :caption< Caption for next formula > e^{ipi}+1=0 =numitem Item the eighth =end section

Non-arabic numerals

=numhead First title =numhead Second title =numhead3 Sub-sub-head one (implies the sub-head) =numhead3 Sub-sub-head two =numhead2 Sub-head first explicit =numhead2 Sub-head second explicit =for numformula2 :form<%T %Z.%R. > e^{i\pi}+1=0

Text finishes after version number =place semantic:AUTHORS :caption<Credits> =place semantic:LICENSE =place semantic:VERSION :!toc =end rakudoc

^[1]such as this one

Rakuast::RakuDoc::Render v1.0.14

Renders RakuDoc v2 to text, HTML, HTML-Extra, Markdown

Authors

Richard Hainsworth

License

Artistic-2.0

Dependencies

Test::Deeply::RelaxedPrettyDumpTest::OutputLibCurlURIDigest::SHA1::NativeText::MiscUtilsMethod::ProtectedTest::RunRakuAST::Deparse::HighlightRainbow:ver<0.3.0+>File::Directory::TreeJSON::FastYAMLishXML

Test Dependencies

Test Test::META

Provides

RakuDoc::Citations
RakuDoc::MarkupMeta
RakuDoc::Numeration
RakuDoc::Plugin::HTML::Bulma
RakuDoc::Plugin::HTML::FontAwesome
RakuDoc::Plugin::HTML::Graphviz
RakuDoc::Plugin::HTML::Hilite
RakuDoc::Plugin::HTML::Latex
RakuDoc::Plugin::HTML::LeafletMaps
RakuDoc::Plugin::HTML::ListFiles
RakuDoc::Plugin::HTML::SCSS
RakuDoc::Plugin::Markdown::Graphviz
RakuDoc::Processed
RakuDoc::PromiseStrings
RakuDoc::Render
RakuDoc::ScopedData
RakuDoc::Templates
RakuDoc::To::Generic
RakuDoc::To::HTML
RakuDoc::To::HTML-Extra
RakuDoc::To::Markdown
RenderDocs

AUTHORS

VERSION

LICENSE

SYNOPSIS

Purpose

This is a first heading

This is a second level heading

This is third level heading

Lists

Taking a bullet

Blocks that are processed differently

Some tables

Adding index entries to your text

Scoping examples

Placements

Enumerated blocks

Non-arabic numerals

Rakuast::RakuDoc::Render v1.0.14

Authors

License

Dependencies

Test Dependencies

Provides

Documentation