rakudociem-ipsum.rakudoc

=begin rakudoc :one-option<first> :another-option(2)
=TITLE Proving a renderer
=SUBTITLE A file with many RakuDoc components and some idea about what is expected.
=for AUTHORS :hidden
Richard Hainsworth, aka finanalyst
=for VERSION :hidden
v0.2.1
=for LICENSE :hidden
Artistic-2.0
=SYNOPSIS Assuming a new renderer has been developed and installed (eg using
I<zef>) at B<Rakudoc::To::MyRender>, the render this file using a
C<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.

=alias DECLARATION Do not consider this a disquisition of possible combinations.

=head Purpose

This file is intended to prove a RakuDoc v2 renderer. It can be used in several ways:
=item to generate the AST representation of all the RakuDoc components in the specification
=item to prove a renderer that a new renderer should be able to process this file
=item 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 I<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>

=comment The following section is to test blocks without extra options
Note that all text before a blank line and following a comment should
not be included in the final rendering.

=head1 This is a first heading

text

=head2 This is a second level heading

text

=for head3 :delta<v2;developers can attach notes to blocks associated with versions>
This is third level heading

A paragraph to illustrate B<Basis type> formatting.

A paragraph to illustrate I<Important type> formatting.

A paragraph to illustrate U<Unusual type> formatting.

A paragraph to illustrate O<Strikethrough type> formatting.

A paragraph to illustrate H<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 J<Subscript type> formatting.

A paragraph to illustrate C<Code type> formatting. It can contain other markup, eg. C<A<> markup>.

A paragraph to illustrate V<Verbatim type> formatting. It can contain other RakuDoc, eg.
V<P<defn:Happy>> without executing it.

A paragraph to illustrate some >Z<Zero width>< formatting (in the source has V«Z<Zero width>» between >< ).

A paragraph to illustrate K<Keyboard> formatting.

A paragraph to illustrate R<Replacement> formatting.

A paragraph to illustrate T<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 E<171> or the same thing using
unicode E<LEFT-POINTING DOUBLE ANGLE QUOTATION MARK>. Entities
can be double unicodes, such as E<REGIONAL INDICATOR SYMBOL LETTER U, REGIONAL INDICATOR SYMBOL LETTER A>,
which is the Ukrainian flag.

In case you have forgotten, here is something aliased at the start: A<DECLARATION>

This is an example of an Alias where V«A<DECLARATION>» was replaced by the contents of the V<=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 V«A<an undeclared|XXX>». The use of
an undeclared alias causes a warning.

We can also make an inline D<definition|Im-a-doppelganger>. 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 F<\sum \frac{1}{n^{2}} = \frac{\pi^{2}}{6}> use V«F<>» markup.

Links can be made internally L<say to the first heading|#This is a first heading> or externally
L<say to the raku documentation site|https://docs.raku.org>.

A renderer should provide the opportunity to customise text using V«M<...|..,..;...>» markup.
The renderer M<should not recognise this functionality|PayMeMoreApp; user-id> and issue a warning.

A note N<such as this one> 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 C<=defn> block.

Normally      extra spaces are removed with paragraphs,
but sometimes S<we truly dot dot dot   dash dash dash       want them>.

Good text will contain X<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

=head Lists

Unnumbered up to four levels of bulleting are required, a renderer can
offer more.

=item The start of a unnumbered item list
=item Next item
=item2 now next level
=item2 another at two
=item3 a third level
=item4 fourth level
=item4 fourth level
=item5 level five
=item6 level six
=item7 level seven
=item1 reset to level one
=item3 jump levels
=para
=para to put space between lists, probably a C<=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
=item an unnumbered item
=for numitem2 :continued
but we can resume after a break
=para
=defn Definitions
can be placed in lists

=defn Happy
when not blue

=defn Blue
when not happy

=defn Being assertive
Just B<shout> why don't you?
=para

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.

=for numdefn :continued
Lemma 4
Claim you are the victim here

=alias XXX This is the alias we referenced at the top of the document, but it won't be
=          rendered.

=head2 Taking a bullet

The project originally consisted of five phases, of which
two are already complete and two have been abandoned:

=for item :bullet« \c[BALLOT BOX WITH CHECK] »
Investigate existing solutions

=for item :bullet« \c[BALLOT BOX WITH CHECK] »
Define a minimal initial feature set

=for item :bullet« \c[BALLOT BOX] »
Implement this minimal set of features

=for item :bullet« \c[BALLOT BOX WITH X] »
Secure 100 million in venture capital

=for item :bullet« \c[BALLOT BOX WITH X] »
Abscond to the Bahamas with the cash

=begin section
=config item1 :bullet« \c[Earth Globe Europe-Africa] »
=config item2 :bullet« \c[Hand with Index and Middle Fingers Crossed] »

The major sources of sustainable energy are:
=item1 wind
=item1 hydroelectric
=item1 solar
=item1 geothermal
=item1 fusion
=item2 (eventually)
=end section


=head Blocks that are processed differently

=begin code
my $x = 2;
# a brilliant program!
=end code

=begin code :allow<B K>
my $x = 3;
# a renderer B<should> observe the basis markup
# and the K<markup> but render R<markup> verbatim
=end code

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

=begin input
This is a text with B<basis> markup that conserves
all spacing      when trying    to get column
just using       white spaces   naively
better           to             use tables
=end input

=begin output
This is almost the same as input
but may have a different styling
=end output

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

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)

=for formula :caption<Fabulous identity>
e^{i\pi}+1=0

=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

=begin para :toc :caption<This is an extraordinary paragraph>
Some silly text which will have its own B<extraordinary> ToC entry
=end para

You are reminded that: A<DECLARATION>

=head Some tables

=for table :caption<A visual table> :headlevel(2)
    Animal | Legs |    Eats
    =======================
    Zebra  +   4  + Cookies
    Human  +   2  +   Pizza
    Shark  +   0  +    Fish

=for table :caption<A visual table with a stupendously long caption> :headlevel(2)
    Animal | Legs |    Eats
    =======================
    Zebra  +   4  + Cookies
    Human  +   2  +   Pizza
    Shark  +   0  +    Fish

=begin table :caption<A procedural table> :headlevel(2)
    =row :header
        =for cell :row-span(2)
        Date
        =for cell :column-span(3)
        Samples
        =for cell :row-span(2)
        Mean
    =row :header
        =cell I<Sample 1>
        =cell I<Sample 2>
        =cell I<Sample 3>
    =row
    =column
        =cell 2023-03-08
        =cell 2023-04-14
        =cell 2023-06-23
    =column
        =cell 0.4
        =cell 0.8
        =cell 0.2
    =column
        =cell 0.1
        =cell 0.6
        =cell 0.9
    =column
        =cell 0.3
        =cell 0.5
        =cell 0.0
    =column
        =cell 0.26667
        =cell 0.63333
        =cell 0.36667
    =row
        =for cell :label
        Mean:
        =cell 0.46667
        =cell 0.53333
        =cell 0.26667
        =cell 0.42222
=end table

=head Adding index entries to your text

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

=head Scoping examples

Configuration and aliases are scoped.

Without configuration C<embedded B<markup> is rendered> verbatim.

=begin section
=config C :allow<B>

With configuration C<embedded B<basis> markup> is rendered.

=alias DECLARATION roses are red

How short the season when A<DECLARATION>.
=end section
But configuration directives C<only B<apply> inside> a block scope.

Did I mention before that: A<DECLARATION>

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

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