) =item2 names must be all uppercase and at least two characters long =item2 renderers should treat these as if they are C<head1> with a caption consisting of the semantic block name =item2 the contents of the block should be treated as a paragraph. =item Custom blocks (e.g. C<MyNewBlock>) =item2 names must contain at least one uppercase, and at least one lowercase character =item2 renderers will define how users may specify metadata options and syntax =item2 renderers will define how the contents of the block are interpreted and rendered =item Custom markup codes (e.g. C<Æ>, C<Ø>, C<ß>) =item2 names must consist of exactly one uppercase Unicode character (i.e. with the Upper property) =item2 names may not be a character in the ASCII range (these are reserved for current and future built-in markup codes) =item2 the built-in markup instruction L<C<M<>>|#Markup extras> is also provided for custom markup =head2 Implied code and indentation An example of implied code was given in the L<section on Code blocks|#Code blocks>. Implied code can be used in other blocks. Each block creates a virtual margin (at the column before its leading C<=>) and that virtual margin extends B<I<only>> to the end of the block (I<i.e.> B<not> to the start of the next named block). Thus: =begin code :lang<Rakudoc> ┊=begin rakudoc ┊This is an implicit =para block ┊ ┊ This is implicit =code block ┊ ┊=begin nested ┊This is an implicit =para block ┊ ┊ This is implicit =code block ┊ ┊=begin nested ┊This is an implicit =para block ┊ ┊ This is implicit =code block ┊ ┊=end nested ┊ ┊=for nested ┊This is an implicit =para block ┊over multiple lines ┊ending at this final non-blank line ┊ ┊ This is implicit =code block (NOT a =para) ┊ ┊=end nested ┊ ┊This is an implicit =para block ┊ ┊ This is implicit =code block ┊ ┊=end rakudoc =end code Which means that: =begin code :lang<Rakudoc> =begin rakudoc =for Podcast this is not code this is code =end rakudoc =end code ...because the final line is indented from the virtual margin of its containing C<=begin rakudoc>/C<=end rakudoc> block, so it must be code. Whereas: =begin code :lang<Rakudoc> =begin rakudoc =for Podcast this is not code this is not code either =end rakudoc =end code ...because the final content line starts at the virtual margin of its containing C<=begin rakudoc>/C<=end rakudoc> block. Care must be taken with I<abbreviated> and I<extended> blocks where the block ends at the next blank line. =begin code :lang<Rakudoc> =begin rakudoc This is an ordinary paragraph While this is not an ordinary paragraph; it is a code block. =head1 Mumble mumble Surprisingly, this is a code block (with fancy indentation too) This is just an ordinary paragraph. =end rakudoc =end code The I<Surprisingly ...> paragraph is a code block because a block only sets the virtual margin within that block, and the C<=head1> block terminates at the blank line immediately after the C<=head1> line, and before the apparent code block begins. At which point, the virtual margin reverts to the previous virtual margin set by the surrounding C<=begin rakudoc...=end rakudoc> block. The current virtual margin terminates at the end of the block whose opener set it, and not at the start of the next block that sets a virtual margin. In other words, the virtual margin is a local feature of each individual block, not a collective feature of the entire document, and therefore a block's virtual margin always ends at the end of the block itself (and reverts at that point to the virtual margin of the surrounding block, if any). Which means: =begin code :lang<Rakudoc> =begin rakudoc This is an ordinary paragraph While this is not This is a code block =head1 Mumble mumble This IS also a code block because the preceding =head's virtual margin ended at the end of the preceding =head block, which was at the preceding blank line. So the virtual margin for this implicit block is the virtual margin of the surrounding C<=begin rakudoc ... =end rakudoc> block. This block is indented relative to that C<=rakudoc block>'s virtual margin, so it's a code block. This is a para block (with fancy indentation too, because the indentation of first line alone determines whether an implicit block is a C<=para> or a C<=code> block, and all subsequent lines, regardless of their indentation, become part of that block ... until the end of the implicit block, which occurs at the next blank line or the next explicit RakuDoc block or directive.) =end rakudoc =end code And if, instead, you wanted the block straight after the C<=head> to be an implicit paragraph block (i.e. not an implicit code block), you'd write it: =begin code :lang<Rakudoc> =begin rakudoc This is an ordinary paragraph While this is not This is a code block =begin section =head1 Mumble mumble This is a para block, NOT a code block because the virtual margin for this implicit block is the virtual margin of the surrounding =begin section ... =end section block. The first line of this implicit block is NOT indented relative to that =section block's virtual margin, so it's a para block. =end section This is a para block too...because its first line is not indented relative to the virtual margin of the current =begin rakudoc ... =end rakudoc block. =end rakudoc =end code Indentation from the current virtual margin only implies a para or code block in blocks that B<don’t> already explicitly specify otherwise. Hence, all the following I<“container blocks”> should honour the I<indented>=C<code> and I<on-margin>=C<para> shortcuts: C<=defn>, C<=item>, C<=itemN>, C<=nested>, C<=rakudoc>, C<=section>, C<=pod>, C<=cell>. B<I<None>> of the following blocks should infer C<para> or C<code> from indentation: C<=para>, C<=code>, C<=input>, C<=output>, C<=comment>, C<=table>, C<=formula>, C<=data>, C<=head>, C<=headN>, C<=SEMANTIC>. That’s because each of them specifies explicitly what type of information their contents are supposed to be, so there’s no need to infer anything. In particular, C<=para> and C<=code> are specifically provided to I<circumvent> inference from indentation. Finally, user-defined custom blocks should always pass their contents verbatim to whatever appropriate user-defined handler is in scope, and it’s up to that handler to infer the meaning of any indentation. =head1 Metadata A powerful feature of RakuDoc is the ability to associate metadata with a block. Metadata can be used to change the way a block is rendered, or to allow a renderer to access data in the cloud, or receive data from a microservice. Some metadata options are defined for certain blocks and a renderer must produce the behaviour described in this section (or in the section for the relevant block), to the extent possible for a given output format, A renderer may ignore metadata options not specified in this document, or define other metadata tabs that it will recognise. =head2 Anchors Whenever a C<=head> block such as: =begin code :lang<RakuDoc> =head Table of Contents and Index =end code ...is rendered, it is also associated with an anchor, so that when a link of the form C<L<link to an internal heading|#Table of Contents and Index>> is rendered, the renderer will place a link to the correct heading in the output format. The anchor will also be used in the Table of Contents. Note that the text in the C<L<...>> before the C<|> is the display text, and the tag after the C<|> is the content of the target C<=head> block. In order for a link to work correctly, the anchor must be unique. The renderer is free to chose the algorithm it uses for the internal anchor. This is because different outputs, such as Markdown and HTML, have different formats for anchors. An author may want to shorten an internal link to a title, and also to place an anchor on every block. The C<:id<name of a link>> metadata option can be attached to any block. For example: =begin code :lang<RakuDoc> =for head :id<ToCaI> Table of Contents and Index ...and later we can add: L<link to an internal heading|#ToCaI> =end code The renderer is expected to create a link with that name to the start of the block. It is up to the author of the document to ensure that all C<:id> links are unique. A renderer may mangle the link name (e.g. the contents of a header) to create an anchor ID internally because different output formats may place restrictions on the characters that can be used in a link. However, a document author may not rely on a renderer's ID generation algorithm. Internal links (links to anchors within the same document) must be specified by a leading C<#> followed by either: =item the target block's explicit C<:id<LABEL>>, or =item the exact contents of the corresponding C<=header> block, or =item the exact contents of a block’s explicit C<:caption<TEXT>>. Internal links cannot be specified by a C<#> followed by =item a C<=header> block's implicit I<autogenerated-from-content> ID, or =item a block’s implicit I<autogenerated-from-caption> ID. That is, the in-document link target cannot be the mangled contents of a C<=header> block or a C<:caption<...>> metatag; it can only be the original contents. For example: =begin code =for header :id<h123> A sample header =for table :id<t456> :caption<Example table> A B C 1 2 3 This is a L<valid link (to an explicit block ID) | #h123 > This is a L<valid link (to an explicit block ID) | #t456 > This is a L<valid link (to a heading) | #A sample header > This is a L<valid link (to a caption) | #Example table > This is L<NOT a valid link | #A_sample_header > This is L<NOT a valid link | #Example_table > =end code =head2 Table of Contents and Index When a renderer parses a file containing RakuDoc, heading and C<X<>> markup information is collected. This information can be rendered using L<a C<P<>> markup instruction|#Placement links>, or may be used in another way by the renderer (e.g. to create a sidebar with the Table of Contents). Named blocks are considered by default to be equivalent to C<=head> for the purposes of a Table of Contents. The exceptions are C<para>, C<nested>, C<code>, C<input> and C<output> blocks. This default can be changed with the C<:toc> and C<:headlevel> meta tabs. Setting C<:toc> on a block will include the contents of the block in the Table of Contents. Including the entire block contents is usually not desirable, so the C<:caption<...> > meta tab can be used to provide a text for the Table of Contents. Setting C<:!toc> will prevent a block's information from being included in the Table of Contents. Setting C<:headlevel(N)>, where N is an integer greater than 0, will cause the block information to be treated in the same way as a C<headN> heading is treated. Setting N to less than 1 has the same effect as C<:!toc>. If it is not explicitly set, C<:toc> will set the headlevel to 1. =head2 Developer or delta notes When a set of source files is related to a project with versions (such as the Raku language), documentation may get out of date, or may only apply to features of a future release. A delta note can be attached to a block using the C<:delta> metadata tab, or specified inline with the C< Δ< ... > > markup instruction. Both the metadata tab and the markup instruction have two arguments: the first is the version specification, and the second is an optional text note. =nested B<Note:> This is an example of a built in markup code that uses a Unicode Upper character. The mnemonic is I<Delta>, which is commonly used to indicate an incremental component. The version specification is summarised as follows: =table Syntax | Meaning ------ | ------ '*' | Any version v1.2.3 | specific version v1.2.3+ | specific version or later v1.2.3- | specific version or earlier v1.2.3..v2.3.4 | inclusive range of versions v1.2.3^..^v2.3.4 | exclusive range of versions v1.2.3..^v2.3.4 and v1.2.3^..v2.3.4 | semi-inclusive range of versions The version specification (e.g. v1.2.3) shown here follows the rules of L<semantic versioning|https://semver.org>, which is the preferred form for Raku documentation, but is not mandatory. Note that the C<..> and C<^> characters create Raku ranges. With no extra information about which version should be displayed, a renderer should have a way to include both the string and the version specification. Alternatively, if there is information about the version to be shown, a renderer should only show blocks that correspond to the version information. A block that does not have a C<:delta> is treated as if it has C<:delta<*>>. An example is given in the description of the L<C<section> block |#Sections> =head1 Markup instructions Markup instructions provide a way to add inline mark-up to a piece of text. All RakuDoc markup instructions consist of a single capital letter followed immediately by a set of single or double angle brackets; Unicode double angle brackets may be used. Markup instructions may nest other markup instructions. Some markup instructions only affect their contents and do not have any metadata associated with them. These are sometimes called D<formatting codes>. Other markup instructions have side effects. =head2 Formatting codes RakuDoc characterises formatting codes semantically, allowing a renderer to choose any appropriate visual representation. Thus C< B<> > is for the Basis of a sentence, although a visual equivalent might involve a bold font. The following should be made available in all renderers. =table Inline markup Instruction Mnemonic HTML equivalent Markdown equivalent ============= =========== =================== =============== =================== Basis B<text> "B for Basis" text **text** Important I<text> "I for Important" text *text* Unusual U<text> "U for Unusual" text __text__ Strikethrough O<text> "O for Overstrike" <s>text</s> ~~text~~ Superscript H<text> "H for High text" text ^text^ Subscript J<text> "J for Junior text" text ~text~ Code C<text> "C for Code" <code>text</code> `text` The table contains suggested HTML and Markdown equivalents, a renderer may choose other representations. =head2 Instructions with side effects Markup instructions, including all customisable instructions, will typically have associated metadata. =head3 Links To create a link, enclose it in C<L< >>. RakuDoc links are more general than the conventional HTML links. The general syntax is C< L< LABEL | TARGET > > =begin comment When section and config for formatting are working, the last line should be rewritten as =begin section =config C :allow<R> The general syntax is C< L< R<LABEL> | R<TARGET> > > =end section =end comment where the optional label is text that is rendered and the target may include a schema. If the label is omitted, then the target is used as the label. Whitespace on either side of the bar is not significant. When the schema is missing, then the C<https://> schema is implied, which means that if the website url is missing as well, the link is to the same host as the document. Several schemas are possible: =item C<https://> or C<http://> The renderer may style the label and cause a jump in a networked environment, as is normal for HTML documents. =item C<rakudoc:> A reference to a Rakudoc source, which might be in a Raku module or a Rakudoc file. =item C<mailto:> An email address. Typically, activating this type of link invokes a mailer. =item C<man:> A link to the system manpages. =item C<isbn:> and C<issn:> The International Standard Book Number or International Standard Serial Number for a publication. =item C<defn:> A link to a L<block-form definition|#Definition lists> or an L<inline definition|#Inline definitions> of the specified term within the current document. To refer to a specific section within a webpage, manpage, or RakuDoc document, add the name of that section after the main link, separated by a C<#>. To refer to a section of the current document, omit the external address. A renderer is expected to render a link with a schema as follows: =item At a minimum, a link like L<rakudoc:ModuleName> is simply rendered as text, to something like: “the ModuleName documentation”, and L<man:appname> to something like: “The appname manpage”. And neither of them attempt to add any kind of actual operational link. =item At the next level of sophistication, a renderer encountering either link scheme may attempt to shell out a call to C<raku --doc ModuleName> or C<man appname>, and present the results in a pop-up. =item If the renderer is in a networked environment, the renderer is expected to provide a set of user selectable options that provide links to such documentation, for example, a set of HTML links in a pop-down box. A renderer might also allow users to preconfigure their preferred website(s) for these schemes, perhaps offering C<rakudoc:> links to C<https://raku.land/> or C<man:> links to C<https://www.kernel.org/doc/man-pages/> as defaults. Renderers are not expected to handle all schemas beyond the minimum above. Renderers offering more sophisticated styling or operational links should provide ways to configure schemas, whilst offering reasonable defaults. =head4 Examples =begin code :allow I<ACM Transactions on Programming Languages and Systems> is a registered serial publication (L<B<issn:0164-0925>>) This module implements the standard Unix L<B<man:find(1)>> facilities. Please forward bug reports to L<B<mailto:abyss@example.org>> This module needs the L<LAME library|B<http://www.mp3dev.org/mp3/>>. You could also write the code L<in gibberish|B<RakuDoc:Acme::Anguish>> Also see: L<B<man:bash(1)#Compound Commands>>, =defn lexiphania An unfortunate proclivity for employing grandiloquisms (for example, words such as "proclivity", "grandiloquism", and indeed "lexiphania"). =defn glossoligation Restraint of the tongue (voluntary or otherwise) To treat his chronic L<B<defn:lexiphania>> the doctor prescribed an immediate L<B<defn:glossoligation>> or, if that proved ineffective, a complete cephalectomy. =end code =head3 Placement links A second kind of link E<mdash> the C<P<>> or B<placement link> E<mdash> works in the opposite direction. Instead of directing focus out to another document, it allows you to assimilate the contents of another document into your own. In other words, the C<P<>> markup instruction takes a URI and (where possible) inserts the contents of the corresponding document inline in place of the code itself. A URI meets the regex pattern C<\w+:\S+>, where the word characters before C<:> are called the I<schema>. There may not be any spaces in a URI. C<P<>> markup is handy for breaking out standard elements of your documentation set into reusable components that can then be incorporated directly into multiple documents. For example: =begin code :lang<RakuDoc> =COPYRIGHT P<file:/shared/docs/std_copyright.rakudoc> =DISCLAIMER P<http://www.MegaGigaTeraPetaCorp.com/std/disclaimer.txt> =end code might produce: =begin nested B<Copyright> =nested This document is copyright (c) MegaGigaTeraPetaCorp, 2006. All rights reserved. B<Disclaimer> =begin nested ABSOLUTELY NO WARRANTY IS IMPLIED. NOT EVEN OF ANY KIND. WE HAVE SOLD YOU THIS SOFTWARE WITH NO HINT OF A SUGGESTION THAT IT IS EITHER USEFUL OR USABLE. AS FOR GUARANTEES OF CORRECTNESS...DON'T MAKE US LAUGH! AT SOME TIME IN THE FUTURE WE MIGHT DEIGN TO SELL YOU UPGRADES THAT PURPORT TO ADDRESS SOME OF THE APPLICATION'S MANY DEFICIENCIES, BUT NO PROMISES THERE EITHER. WE HAVE MORE LAWYERS ON STAFF THAN YOU HAVE TOTAL EMPLOYEES, SO DON'T EVEN *THINK* ABOUT SUING US. HAVE A NICE DAY. =end nested =end nested The C<P<>> markup code can also be specified with an optional display text, which will be rendered if the renderer cannot find or access the external data source for the placement link. For example: =begin code :lang<RakuDoc> :allow =COPYRIGHT P<B<The document is copyright. |> file:/shared/docs/std_copyright.rakudoc> =DISCLAIMER P<B<NO WARRANTY. NONE. NIL. NADA. |> http://www.MegaGigaTeraPetaCorp.com/std/disclaimer.txt> =end code If the filesystem or internet is inaccessible, this might produce: =begin nested B<Copyright> =nested This document is copyright. B<Disclaimer> =nested NO WARRANTY. NONE. NIL. NADA. =end nested If a renderer cannot find or access the external data source for a placement link, and the placement link does not have an alternative display text, it must issue a warning and render the URI directly in some form, possibly as an outwards link. For example: =begin nested B<Copyright> =nested See: C<file:/shared/docs/std_copyright.rakudoc> B<Disclaimer> =nested See: L<http://www.MegaGigaTeraPetaCorp.com/std/disclaimer.txt> =end nested You can use any of the following URI forms (see L<#Links>) in a placement link: =item C<http:> and C<https:> =item C<file:> =item C<toc:> =item C<index:> =item C<semantic:> The C<toc:> form is a special pseudo-scheme that inserts a table of contents in place of the C<P<>> code. After the colon, list the block types that you wish to include in the table of contents. For example, to place a table of contents listing only top- and second-level headings: P<toc:1,2 > To place a table of contents that lists the top four levels of headings: P<toc:1..4 > In order to include the whole table of contents, use C<toc:*>. The C<*> is needed to make this term a valid URI. A document may have as many C<P<toc:...>> placements as necessary. The C<index:*> form is a special pseudo-scheme that inserts an index table in place of the C<P<>> code. The C<semantic:XXX> form places the XXX semantic block at the position of the C<P<>> instruction. =begin comment When =section/=config working, above line should be =begin section =config C :allow<R> The C<semantic:R<NAME>> form places the R<NAME> semantic block at the position of the C<P<>> instruction. =end section =end comment =head3 Alias placement A variation on the placement instruction is the C<A<>> instruction, which is replaced by the contents of the named alias or object specified within its delimiters. For example: =begin code :lang<RakuDoc> =alias PROGNAME Earl Irradiatem Eventually =alias VENDOR 4D Kingdoms =alias TERMS_URL L<http://www.4dk.com/eie> The use of A<PROGNAME> is subject to the terms and conditions laid out by A<VENDOR>, as specified at A<TERMS_URL>. =end code Any Raku object after the Check Phase, such as an object that starts with a sigil, is available within an alias placement. Unless the object is already a string type, it is converted to a string during document-generation by implicitly calling C<.raku> on it. So, for example, a document can refer to its own filename (as C<A<$?FILE>>), or to the subroutine inside which the specific RakuDoc is nested (as C<A<&?ROUTINE>>), or to the current class (as C<A<$?CLASS>>). Similarly, the value of any program constants defined with sigils can be easily reproduced in documentation: =begin code :lang<RakuDoc> # Actual code... constant Num $GROWTH_RATE = 1.6; =begin rakudoc =head4 Standard Growth Rate The standard growth rate is assumed to be A<$GROWTH_RATE>. =end rakudoc =end code Non-mutating method calls on these objects are also allowed, so a document can reproduce the surrounding subroutine's signature (C<A<&?ROUTINE.signature>>) or the type of a constant (C<A<$GROWTH_RATE.WHAT>>). See L<Aliases|#Alias blocks> for further details of the aliasing macro mechanism. =head3 Inline definitions A C<D<>> formatting code marks a piece of text as being the I<“inline definition”> of a term. That is: it’s like a C<=defn> block, but it’s not a list item; it’s just part of the regular text. Well-written documentation often includes sentences/paragraphs that introduce a new term, and define it. Typically we want to visually distinguish those newly defined terms, and to be able to link back to the paragraph where they’re defined. For example: =begin code :allow There ensued a terrible moment of B<D<coyotus interruptus>>: a brief suspension of the effects of gravity, accompanied by a sudden to-the-camera realization of imminent downwards acceleration. =end code The contents of the C<D<>> represent the term being defined, the location of the C<D<>> implies a link target location, and the paragraph containing the C<D<>> suggests a suitable pop-up definition of the term (if a renderer supports such). The definition term in a C<D<>> is rendered distinctly (typically in B<I<bold italics>>), and the C<D<>> sets up a link target to that term, and possibly a pop-up for the corresponding C<L<>> link to display the entire paragraph in which the C<D<>> appeared. In other words, when rendered to HTML, a C<D<term being defined>> would be translated to something like: =begin code :lang<html> :allow ...a B«<dfn id="term being defined">term being defined</dfn>» would be... =end code And a C<L<defn:term being defined>> link would be translated to something like: =begin code :lang<html> :allow ...a B«<a href="#term being defined">term being defined</a>» link would be... =end code A definition may be given synonyms, which are specified after a vertical bar and separated by semicolons: =begin code :allow A D<formatting code|B<formatting codes;formatters>> provides a way to add inline mark-up to a piece of text. =end code =head3 Space-preserving text Any text enclosed in an S<> code is formatted normally, except that every whitespace character in it — including any newline — is preserved. These characters are also treated as being non-breaking (except for the newlines, of course). For example: =begin code :lang<RakuDoc> The emergency signal is: S< dot dot dot dash dash dash dot dot dot>. =end code would be formatted like so: =begin code :lang<RakuDoc> The emergency signal is: dot dot dot dash dash dash dot dot dot. =end code rather than: =begin code :lang<RakuDoc> The emergency signal is: dot dot dot dash dash dash dot dot dot. =end code =head3 Comments A comment is text that is never rendered. To create a comment enclose it in C<Z< >>: =for code :lang<RakuDoc> Raku is awesome Z<Of course it is!> This would be rendered as: =nested Raku is awesome Z<Of course it is!> =head3 Notes Notes are ancillary information that may be rendered as footnotes or sidenotes or pop-up notes, depending on the renderer and environment. To create a note enclose it in C<N< >> =for code :lang<RakuDoc> Raku is multi-paradigmatic N<Supporting Procedural, Object Oriented, and Functional programming> Which produces: =nested Raku is multi-paradigmatic N<Supporting Procedural, Object Oriented, and Functional programming> =head3 Keyboard input To flag text as keyboard input enclose it in C<K< >> =begin code :lang<RakuDoc> =output Enter your name: K<John Doe> =end code Which is rendered like so: =begin nested =output Enter your name: K<John Doe> =end nested =head3 Replaceable The C<R<>> markup instruction specifies that the contained text is a B<replaceable item>, a placeholder, or a metasyntactic variable. It is used to indicate a component of a syntax or specification that should eventually be replaced by an actual value. For example: =begin code :lang<RakuDoc> The basic C<ln> command is: C<ln> R<source_file> R<target_file> =end code This is rendered like so: =nested The basic C<ln> command is: C<ln> R<source_file> R<target_file> =head3 Terminal output To flag text as terminal output enclose it in C<T< >> =begin code :lang<RakuDoc> =input T<Enter your name:> John Doe =end code Which would be rendered: =begin nested =input T<Enter your name:> John Doe =end nested =head3 Unicode and HTML references Unicode codepoint names or numbers may be included in a RakuDoc document by enclosing them in C<E< >>. When C<E< >> encloses a number, it is treated as the Unicode value for the code point using binary, octal, decimal, or hexadecimal numbers using the Raku notations for explicitly based numbers. Numbers without an explicit base, as per Raku convention, are decimal. For example, each of the following: =begin code :lang<RakuDoc> Raku makes considerable use of the E<171> and E<187> characters. Raku makes considerable use of the E<0b10101011> and E<0b10111011> characters. Raku makes considerable use of the E<0o253> and E<0o273> characters. Raku makes considerable use of the E<0d171> and E<0d187> characters. Raku makes considerable use of the E<0xAB> and E<0xBB> characters. =end code will yield the same rendering: =nested Raku makes considerable use of the « and » characters. It is also possible to specify Unicode codepoint B<names>. Multiple codepoints separated by C<,> will be considered as a single grapheme. So: =begin code E<LEFT-POINTING DOUBLE ANGLE QUOTATION MARK> E<REGIONAL INDICATOR SYMBOL LETTER U, REGIONAL INDICATOR SYMBOL LETTER A> Ukraine E<RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK> =end code will be rendered as: « 🇺🇦 Ukraine ». Since emojis are graphemes that can be described by Unicode, C<E<...>> will also generate emojis. For example: =begin code :lang<RakuDoc> E<WHITE SMILING FACE> Smiling face =end code will generate: E<WHITE SMILING FACE> Smiling face Alternatively, HTML5 character references may be used. For example: =begin code :lang<RakuDoc> Raku makes considerable use of the E<laquo> and E<raquo> characters. =end code also yields: Raku makes considerable use of the « and » characters. The C<E<>> markup may be used for a list of characters separated by C<;> =begin code Raku code often contains the E<0xff62;0xff63> bracketing characters to avoid using quotes. =end code This would yield: Raku code often contains the ｢｣ bracketing characters to avoid using quotes. The C<E<>> code can also be specified with an alternate display text (before the entity specification and separated from it by a C<|>). When an alternate text is specified, it is used if the specified entity cannot be represented by the renderer (e.g. if the renderer only supports ASCII). For example: =begin code :lang<RakuDoc> :allow Raku makes considerable use of the E<B<left- |> laquo> and E<B<right-double-angle |> raquo> characters. Raku code often contains the E<B<left- and right-corner |> 0xff62;0xff63> bracketing characters to avoid using quotes. =end code An ASCII-only renderer would then render those like so: Raku makes considerable use of the left- and right-double-angle characters. Raku code often contains the left- and right-corner bracketing characters to avoid using quotes. =head3 Verbatim text The C<V<>> markup instruction treats its entire contents as being B<verbatim>, disregarding every apparent markup instruction within it. For example: =for code :lang<RakuDoc> The B<V< V<> >> markup instruction disarms other codes such as V< I<>, C<>, B<>, and M<> >. Note, however that the C<V<>> code only changes the way its contents are parsed, I<not> the way they are rendered. That is, the contents are still wrapped and formatted like plain text, and the effects of any markup instructions surrounding the C<V<>> code are still applied to its contents. For example the previous example is rendered as: =nested The B<V< V<> >> markup instruction disarms other codes such as V< I<>, C<>, B<>, and M<> >. Note that C<C<>> also by default keeps its contents verbatim, the difference between C<C<>> and C<V<>> is that C<C<>> 'colors' the contents to show that it is code, whilst C<V<>> uses the default text presentation. The default behaviors of both C<V<>> and C<C<>> can be changed using a C<=config> directive, e.g., =begin code :lang<Rakudoc> =config C :allow =config V :allow< N L X > =end code =head3 Indexing terms Anything enclosed in an C<X<>> code is an B<index entry>. The contents of the code are both formatted into the document and used as the (case-insensitive) index entry: =begin code :allow :lang<RakuDoc> An B<X<array>> is an ordered list of scalars indexed by number, starting with 0. A B<X<hash>> is an unordered collection of scalar values indexed by their associated string key. =end code You can specify an index entry in which the indexed text and the index entry are different, by separating the two with a vertical bar: =begin code :allow :lang<RakuDoc> An B<X<array|arrays>> is an ordered list of scalars indexed by number, starting with 0. A B<X<hash|hashes>> is an unordered collection of scalar values indexed by their associated string key. =end code In the two-part form, the index entry comes after the bar and is case-sensitive. You can specify hierarchical index entries by separating indexing levels with commas: =begin code :allow :lang<RakuDoc> An X<array|B<arrays, definition of>> is an ordered list of scalars indexed by number, starting with 0. A X<hash|B<hashes, definition of>> is an unordered collection of scalar values indexed by their associated string key. =end code You can specify two or more entries for a single indexed text, by separating the entries with semicolons: =begin code :allow :lang<RakuDoc> A X<hash|B<hashes, definition of; associative arrays>> is an unordered collection of scalar values indexed by their associated string key. =end code The indexed text can be empty, creating a "zero-width" index entry: =begin code :allow :lang<RakuDoc> B<X<|puns, deliberate>>This is called the "Orcish Maneuver" because you "OR" the "cache". =end code =head3 Markup extras In order to allow for renderers to add customisable markup code, whilst at the same time abiding by the L<naming rules|#Naming rules>, the markup instruction C<M< visible text | list-of-strings >> is defined as a I<built-in> markup instruction. The R<visible text> is shown in the text, and may be blank. The R<list-of-strings> is specified in the same way as the C<X<>> markup instruction for L<indexing|#Indexing entries>. The semantics of the string is defined by the renderer. If a renderer does not recognise the list of strings, it is expected that the visible text will be rendered and marked in some way (such as with a border or highlight color), and at least the first string will be made available in the same way as the C<D<>> markup instruction. It is also recommended that the first string is used by the renderer to identify the functionality being provided. For example, suppose a Rakudoc document is used to create part of a website in which a button is to be styled that accesses the API of a payment service (e.g. 'PayMe'). A developer can then create some functionality according to the rules of a RakuDoc renderer, and present it to the service point. In an HTML document, this might be coded as a C< <button class="PayMeApp" data-token="vendor-id" data-price="$0.99"> > with a specific class and structure. The RakuDoc instruction might then be: =begin code :lang<Raku> :allow To sample this marvelous libation B<M<order now by PayMeApp|PayMeApp; vendor-id; $0.99>> =end code An HTML renderer would the convert this to, for example, =begin code :lang<HTML> To sample this marvelous libation <button class="PayMeApp" data-token="vendor-id" data-price="$0.99"> order now by PayMeApp </button> =end code =head3 Display and metadata In the descriptions above, it will be seen that markup codes may only contain display text or a mix of display and meta information. This section clarifies these groups. If a markup code may contain both display text and meta information, the character C<|> is used to delimit the two components. In order to use C<|> inside a display text, it must be escaped (C<\|>) or specified as an entity (C«E<VERTICAL LINE>»). =head4 Display only codes The following codes may I<only> contain display text: =begin nested =begin code :allow V« B<» I<DISPLAY-TEXT> V« >» V« C<» I<DISPLAY-TEXT> V« >» V« H<» I<DISPLAY-TEXT> V« >» V« I<» I<DISPLAY-TEXT> V« >» V« J<» I<DISPLAY-TEXT> V« >» V« K<» I<DISPLAY-TEXT> V« >» V« R<» I<DISPLAY-TEXT> V« >» V« S<» I<DISPLAY-TEXT> V« >» V« T<» I<DISPLAY-TEXT> V« >» V« U<» I<DISPLAY-TEXT> V« >» V« V<» I<DISPLAY-TEXT> V« >» V« N<» I<DISPLAY-TEXT> V« >» V« O<» I<DISPLAY-TEXT> V« >» =end code =end nested =head4 Metadata and (optional) display text The following codes may (and, in some cases, must) contain both a display text and some kind of metadata. =begin nested =begin code :allow V« A<» I<DISPLAY-TEXT > V« | » METADATA=B<ALIAS-NAME>V« >» V« D<» I<DISPLAY-TEXT > V« | » METADATA=B<SYNONYMS>V« >» V« Δ<» I<DISPLAY-TEXT > V« | » METADATA=B<VERSION-ETC>V« >» V« E<» I<DISPLAY-TEXT > V« | » METADATA=B<HTML/UNICODE-ENTITIES>V« >» V« F<» I<DISPLAY-TEXT > V« | » METADATA=B<LATEX-FORM>V« >» V« L<» I<DISPLAY-TEXT > V« | » METADATA=B<TARGET-URI>V« >» V« M<» I<DISPLAY-TEXT > V« | » METADATA=B<WHATEVER>V« >» V« P<» I<DISPLAY-TEXT > V« | » METADATA=B<REPLACEMENT-URI>V« >» V« X<» I<DISPLAY-TEXT > V« | » METADATA=B<INDEX-ENTRY>V« >» =end code =end nested The markup codes C<A>, C<E>, C<F>, C<L>, and C may be specified B<without> a display text, in which case, the renderer (as elsewhere provided in this specification) may provide an automatic rendering if the metadata component fails to produce a renderable result. If an explicit display text is provided (i.e. to the left of a C<|>), that text overrides the default alternate rendering. =head4 Metadata only =begin nested V« Z<» METADATA=B<COMMENT>V« >» =end nested The comment code C<Z<> > is intended not to have a display text so the contents of a comment can be considered as pure metadata. =head1 Implementor considerations RakuDoc is intended to be a markup language for text oriented documentation, which will be rendered into output formats such as I<HTML> or I<epub>. It is expected that there may be several modules that will render RakuDoc. In order for a renderer to be compliant with the specification, it must: =item render in some way all the built-in RakuDoc blocks and markup codes =item2 where fallbacks have been specified, only the minimum fallback need be rendered =item recognise and apply all the directives =item provide some mechanism for a user to add custom blocks and markup codes =item signal rendering errors in some way, unless such warnings have been explicitly silenced =item2 rendering errors include unknown block/code types, as well as the use of unimplemented built-ins =item2 the following signalling mechanisms are acceptable approaches to fulfil this requirement: =item3 writing error messages to STDERR =item3 writing error messages to a log file =item3 appending error messages to the end of the rendered output in a distinctive style that indicates they are errors =item3 rendering unhandled blocks or codes inline (in a distinctive style) and providing the associated error message in a pop-up that activates on hover or mouse-click P<semantic:AUTHORS> =head1 Summary =head2 Directives =begin table :!toc =row :header =cell Directive =cell Specifies =row =cell V<=alias> =cell Define a RakuDoc macro =row =cell V<=begin> =cell Start of an explicitly terminated block =row =cell V<=column> =cell Start a new column in a procedural table =row =cell V<=config> =cell Block scope modifications to a block or markup instruction =row =cell V<=end> =cell Explicit termination of a begin block =row =cell V<=finish> =cell No ambient blocks after this point =row =cell V<=for> =cell Start of an implicitly (blank-line) terminated block =row =cell V<=row> =cell Start a new row in a procedural table =row =end table =head2 Blocks =begin table :!toc =row =cell Block typename =cell Specifies =row =cell V<=cell> =cell Contents of a table cell, only valid in a procedural table context =row =cell V<=code> =cell Verbatim pre-formatted sample source code =row =cell V<=input> =cell Pre-formatted sample input =row =cell V<=output> =cell Pre-formatted sample output =row =cell V<=comment> =cell Content to be ignored by all renderers =row =cell V<=head> =cell First-level heading =row =cell V<=headN> =cell Nth-level heading =row =cell V<=numhead> =cell First-level numbered heading =row =cell V<=numheadN> =cell Nth-level numbered heading =row =cell V<=defn> =cell Definition of a term =row =cell V<=item> =cell First-level list item =row =cell V<=itemN> =cell Nth-level list item =row =cell V<=numitem> =cell First-level numbered list item =row =cell V<=numitemN> =cell Nth-level numbered list item =row =cell V<=nested> =cell Nest block contents within the current context =row =cell V<=para> =cell Ordinary paragraph =row =cell V<=rakudoc> =cell No "ambient" blocks inside =row =cell V<=section> =cell Defines a section =row =cell V<=pod> =cell Legacy version of RakuDoc =row =cell V<=table> =cell Visual or procedural table =row =cell V<=formula> =cell Render content as LaTex formula =row =cell V<=data> =cell Raku data section =row =cell RESERVED =cell Semantic blocks (SYNOPSIS, TITLE, etc.) =row =cell CustomName =cell User-defined block =end table =head2 Metadata options =begin table :!toc =row :header =cell Metadata option =cell Blocks applied to =cell Description =row =column =for cell :row-span(4) :align<middle> C<:allow> =column =cell C<=code> =cell C<=input> =cell C<=output> =cell C<=table> =column =for cell :row-span(4) :align<middle> Change default of verbatim blocks =row =cell C<:id> =cell all blocks =cell Specify the anchor for a block =row =column =for cell :row-span(2) C<:continued> =column =cell C<=item> =cell C<=numitem> =column =for cell :row-span(2) Continue numbering from the previous numbered list =row =column =for cell :row-span(8) C<:toc> =column =cell C<=para> =cell C<=nested> =cell C<=code> =cell C<=input> =cell C<=output> =cell C<=table> =cell C<=formula> =cell C<=place> =column =for cell :row-span(8) Include content or caption in Table of contents =row =column =for cell :row-span(4) C<:!toc> =column =cell SEMANTIC block =cell Custom block =cell C<=headN> =cell C<=numheadN> =column =for cell :row-span(4) Do not include content or caption in Table of contents =row =column =for cell :row-span(10) C<:headlevel> =column =cell SEMANTIC block =cell Custom block =cell C<=para> =cell C<=nested> =cell C<=code> =cell C<=input> =cell C<=output> =cell C<=table> =cell C<=formula> =cell C<=place> =column =for cell :row-span(10) Define the head level at which the caption is included in the Table of contents =row =column =for cell :row-span(9) C<:caption> =column =cell Semantic block =cell Custom block =cell C<=nested> =cell C<=code> =cell C<=input> =cell C<=output> =cell C<=table> =cell C<=formula> =cell C<=place> =column =for cell :row-span(9) Caption to be associated with a block in the Table of Contents =row =cell C<:hidden> =cell Semantic block =cell Remove block from rendered text and ToC (use C<P<semantic: ...>> to inject elsewhere) =row =column =for cell :row-span(4) C<:header> =column =cell C<=table> (procedural semantics only) =cell C<=cell> =cell C<=row> directive =cell C<=column> directive =column =for cell :row-span(4) Specify rows, columns, or cells to be rendered as headers =row =column =for cell :row-span(4) C<:label> =column =cell C<=table> (procedural semantics only) =cell C<=cell> =cell C<=row> directive =cell C<=column> directive =column =for cell :row-span(4) Specify rows, columns, or cells to be rendered as labels =row =column =for cell :row-span(4) C<:align<ALIGNMENTS>> =column =cell C<=table> (procedural semantics only) =cell C<=cell> =cell C<=row> directive =cell C<=column> directive =column =for cell :row-span(4) Specify how cell contents are to be vertically and/or horizontally aligned =row =cell C<:row-span(HEIGHT)> =cell C<=cell> =cell Specify how many rows a single cell should span in a procedural table =row =cell C<:column-span(WIDTH)> =cell C<=cell> =cell Specify how many columns a single cell should span in a procedural table =row =cell C<:span(WIDTH, HEIGHT)> =cell C<=cell> =cell A shortcut for C<:column-span(WIDTH) :row-span(HEIGHT)> =row =column =for cell :row-span(10) :align<top> C<:delta> =column =cell C<=table> =cell C<=formula> =cell C<=nested> =cell C<=code> =cell C<=input> =cell C<=output> =cell C<=headN> =cell C<=numheadN> =cell Semantic block =cell Custom block =column =for cell :row-span(10) :align<top> Developer information associated with a block =row =cell C<:bullet<CHAR>> =cell C<=itemN> =cell Replace the default bullet with one or more characters, or entities specified with C<E< ... >> =end table =head2 Markup instructions =begin table :!toc =row =cell Markup instruction =cell Specifies =row =cell V<A<...|...>> =cell Alias to be replaced by contents of specified V<=alias> directive =row =cell V<B<...>> =cell Basis/focus of sentence (typically rendered bold) =row =cell V<C<...>> =cell Code (typically rendered fixed-width) =row =cell V<D<...>> =cell Definition inline (V<D<term being defined|synonym1; synonym2>>) =row =cell V<Δ<...|...;...>> =cell Delta note (V<Δ<visible text|version; Notification text>>) =row =cell V<E<...|...;...>> =cell Entity (HTML or Unicode) description (V<E<entity1;entity2; multi,glyph;...>>) =row =cell V<F<...|...>> =cell Inline content for a formula (V<F<ALT|LaTex notation>>) =row =cell V<G<...>> =cell (This markup code is not yet defined, but is reserved for future use) =row =cell V<H<...>> =cell High text (typically rendered superscript) =row =cell V<I<...>> =cell Important (typically rendered in italics) =row =cell V<J<...>> =cell Junior text (typically rendered subscript) =row =cell V<K<...>> =cell Keyboard input (typically rendered fixed-width) =row =cell V<L<...|...>> =cell Link (V<L<display text|destination URI>>) =row =cell V<M<...|..,..;...>> =cell Markup extra (V<M<display text|functionality;param,sub-type;...>>) =row =cell V<N<...>> =cell Note (not rendered inline, but visible in some way: footnote, sidenote, pop-up, etc.)) =row =cell V<O<...>> =cell Overstrike or strikethrough =row =cell V<P<...|...>> =cell Placement link =row =cell V<Q<...>> =cell (This markup code is not yet defined, but is reserved for future use) =row =cell V<R<...>> =cell Replaceable component or metasyntax =row =cell V<S<...>> =cell Space characters to be preserved =row =cell V<T<...>> =cell Terminal output (typically rendered fixed-width) =row =cell V<U<...>> =cell Unusual (typically rendered with underlining) =row =cell V<V<...>> =cell Verbatim (internal markup instructions ignored) =row =cell V<W<...>> =cell (This markup code is not yet defined, but is reserved for future use) =row =cell V<X<...|..,..;...>> =cell Index entry (V<X<display text|entry,subentry;...>>) =row =cell V<Y<...>> =cell (This markup code is not yet defined, but is reserved for future use) =row =cell V<Z<...>> =cell Zero-width comment (contents never rendered) =row =end table =LICENSE Artistic-2.0 =end rakudoc

block will typically only be used in the delimited form so that the document writer can define an explicit block scope. The C<=begin section> declaration starts a new block scope, and the C<=end section> returns the scope to the previous one. Unlike an C<=end rakudoc>, an C<=end section> does not always change the scope back to ambient code. It only does so when its corresponding C<=begin section> changed the scope I ambient code. In contrast, an C<=end rakudoc> always reverts to ambient code. Sections may be embedded within other sections. When a C<=begin section> is not present, a renderer may apply the following heuristic to determine the block scope (assuming X, Y, and Z are digits such that C«0 < X < Y < Z »): =item A C<=headY> declaration starts a new block scope. =item The next C<=headY> declaration ends the block scope of the previous C<=headY> =item A C<=headZ> declaration following a C<=headY> is within the block scope of the preceding C<=headY> declaration, and does not end it. =item A C<=headX> declaration ends the scope of any preceding C<=headY> and C<=headZ> declarations. Note that a C<=begin section> declaration overrides the heuristic, meaning that multiple C<=headX> declarations can be placed within the same block scope. A renderer is not expected to render blocks differently when they are embedded in a C

block. Providing metadata to a C<=begin section> block definition is B the same as declaring metadata using a C<=config> directive. Metadata in a config is provided to all matching blocks in the current block scope. Metadata in the C<=begin section> declaration is only applied to the section itself, not to the blocks it contains. For example, suppose the following RakuDoc text was included in a source file =begin code :lang =begin section :delta(v2.3.2-, 'removed due to conflict with chancellors') =head2 role fool This role is especially important in authoritarian kingdoms to remind kings of their humanity. =end section =end code If a user indicates to a renderer that they wish to view documentation valid today, which corresponds (for example) to C then, because C is after C, the section above – including the nested C<=head2> block and the following plain paragraph – would not be rendered. If however, a user indicates they wish to view documentation for C, the renderer would render the section above, including an indication the section will be removed in C. =head3 Document scope A C<=begin rakudoc> declaration (or equivalently a C<=begin pod>) also defines a new scope, and also has the effect that code following it is not considered Raku code. An C<=end rakudoc> will return scope to the ambient code. This also means that C blocks cannot be nested, while C

blocks may be nested. The first C<=begin rakudoc> declaration in a document starts the RakuDoc scope of the document. Metadata following the first such declaration are made available to all blocks in the document. =head2 Ordinary paragraphs An ordinary paragraph consists of text that is to be formatted into a document at the current level of nesting, with whitespace squeezed, lines filled, and any special inline mark-up applied. Ordinary paragraphs consist of one or more consecutive lines of text, each of which starts with a non-whitespace character. The paragraph is terminated by the first blank line or directive. For example: =begin code :lang =head1 This is a heading block This is an ordinary paragraph. Its text will be squeezed and short lines filled. It is terminated by the first blank line. This is another ordinary paragraph. Its text will also be squeezed and short lines filled. It is terminated by the trailing directive on the next line. =head2 This is another heading block This is yet another ordinary paragraph, at the first virtual column set by the previous directive =end code Ordinary paragraphs do not require an explicit marker or delimiters (within a C block). Alternatively, there is also an explicit C<=para> marker that can be used to explicitly mark a paragraph, which would be necessary outside a C block. =begin code :lang =para This is an ordinary paragraph. Its text will be squeezed and short lines filled. =end code This is rendered as: =para This is an ordinary paragraph. Its text will be squeezed and short lines filled. In addition, the longer C<=begin para> and C<=end para> form can be used. For example: =begin code :lang =begin para This is an ordinary paragraph. Its text will be squeezed and short lines filled. This is still part of the same paragraph, which continues until an... =end para =end code As demonstrated by the previous example, within a delimited C<=begin para> and C<=end para> block, any blank lines are preserved. =head2 Nesting or indenting a block RakuDoc provides a C<=nested> block that marks all its contents as being nested: =begin code :lang =begin nested We are all of us in the gutter, but some of us are looking at the stars! =begin nested -- Oscar Wilde =end nested =end nested =end code ...which would produce: =begin nested We are all of us in the gutter, but some of us are looking at the stars! =begin nested -- Oscar Wilde =end nested =end nested Nesting blocks can contain any other kind of block, including implicit paragraph and code blocks. Note that the relative physical indentation of the nested blocks plays no role in determining their ultimate indentation in the final rendering. The preceding example could equally have been specified: =begin code :lang =begin nested We are all of us in the gutter, but some of us are looking at the stars! =begin nested -- Oscar Wilde =end nested =end nested =end code =head2 Verbatim blocks Normally a writer does not want to consider the way text flows on a page. They want the end of each line to be treated the same as a space, and for extra spaces to be eliminated. However, the exact placing of whitespace sometimes I important, especially for code. =head3 Code blocks Code blocks are used to specify pre-formatted text (typically source code), which should be rendered without rejustification, without whitespace squeezing, and by default B recognizing any inline markup instructions. Code blocks also have an implicit nesting associated with them. Typically these blocks are used to show examples of code, mark-up, data formats, or other textual specifications. They are usually rendered using a fixed-width font. A code block may be implicitly specified as one or more lines of text, each of which starts with a whitespace character at the block's virtual left margin. The implicit code block is then terminated by a blank line or an explicit directive. For example: =begin code :lang This ordinary paragraph introduces a code block: $this = 1 * code('block'); $which.is_specified(:by); =end code Implicit code blocks may be used L. There is also an explicit C<=code> block (which can be specified within any block type, not just C<=rakudoc>, C<=item>, etc.): =begin code :lang The C subroutine adds feedback: =begin code sub loud_update ($who, $status) { say "$who -> $status"; silent_update($who, $status); } =end code =end code As the previous example demonstrates, within an explicit C<=code> block the code does not have to be indented; it can start at the (virtual) left margin. Furthermore, lines that start with whitespace characters after that margin have subsequent whitespace preserved exactly (in addition to the implicit nesting of the code). Explicit C<=code> blocks may also contain empty lines. =head5 Preprocessing and postprocessing of code The code in a document is almost always related to a specific programming language, by default Raku. But examples of Ruby, C, RakuDoc, or other languages may also appear in the Raku documentation sources. A renderer should offer the option to use syntax highlighting to render code in a code block, perhaps by specifying a C<:syntax-highlighting> metadata option for code blocks. By default, a renderer will not change the contents of a code block, but see the caveat when L is used|#Markup within verbatim blocks>. The C<:lang< ... >> metadata option may be used to specify that the contents of a given C<=code> block are in a given language. If the specified language is unknown to a renderer, it may choose either to default to Raku syntax highlighting, or may apply some other heuristic. =head3 I/O blocks RakuDoc provides blocks for specifying the input and output of programs. These are similar to C

 blocks in that they preserve whitespace and are rendered distinctly
from regular text paragraphs.

The C<=input> block is used to specify pre-formatted keyboard input,
which should be rendered without re-justification or squeezing of whitespace.

The C<=output> block is used to specify pre-formatted terminal or file output,
which should also be rendered without re-justification or whitespace-squeezing.

Although they are rendered with verbatim whitespace, like a code block, input and output
blocks differ from code blocks in that they do recognize any inline mark-up instructions within
their text.

For example:

=begin code :lang

    =begin output
            Name:    Baracus, B.A.
            Rank:    Sgt
            Serial:  1PTDF007

            Do you want additional personnel details? K

            Height:  180cm/5'11"
            Weight:  104kg/230lb
            Age:     49

            Print? K
        =end output

=end code

In this example, the two embedded C> sequences would be recognized as
inline mark-up and rendered appropriately (i.e. as keyboard input).

=head3 Markup within verbatim blocks

Although C<=code> blocks automatically disregard all markup instructions, occasionally you may still
need to specify some markup within a code block. For example, you may wish to
emphasize a particular keyword in an example (using a C> code). Or you may want to indicate that
part of the example is metasyntactic (using the C> code). Or you might need to insert a non-ASCII
character (using the C> code).

You can specify a list of markup instructions that should still be recognized within a code block using
the C<:allow> option. The value of the C<:allow> option must be a list of the (single-letter)
names of one or more markup instructions. Those codes will then remain active inside the code block.
For example:
=begin code :allow< B V > :lang
    =begin code B<:allow< B R >> :lang
    sub demo {
        V 'Hello R';
        I 'The I format is not recognised';
    }
    =end code
=end code

This would be rendered:

=begin code :allow< B R > :lang
sub demo {
    B 'Hello R';
    I 'The I format is not recognised';
}
=end code

It should be noted that both C<:allow> and C<:lang> (if C<:syntax-highlighting> is true)
will affect the rendering of the content of the block. This is likely to cause conflicts
in some cases. The renderer is free to choose how to resolve such conflicts, e.g. by
disregarding the C<:allow> metadata.

=head2 Lists

Lists in RakuDoc are specified as a series of contiguous C<=item> blocks.
No special "container" directives or other list delimiters are required to enclose the entire list.

Note that C<=item> is just an abbreviation for C<=item1>.

=head3 Unordered lists

Lists in RakuDoc are by default unordered. For example:

=begin code :lang
The three suspects are:

=item  Happy
=item  Sleepy
=item  Grumpy
=end code

This produces:

=begin nested
The three suspects are:

=item  Happy
=item  Sleepy
=item  Grumpy
=end nested

By default, a compliant renderer will provide a bullet for each item. RakuDoc also allows
for custom bullets as L.

=head3 Multi-level lists

Lists may be multi-level, with items at each level specified using the
C<=item1>, C<=item2>, C<=item3>, etc. blocks.
(The indentation depends on the rendering engine and does not need to be included
in the RakuDoc markup.) Up to four levels are normally differentiated.

For example:

=begin code :lang
=item1  Animal
=item2     Vertebrate
=item3     Mammals
=item4     Primates
=item2     Invertebrate

=item1  Phase
=item2     Solid
=item3        Crystalline
=item3        Amorphous
=item2     Liquid
=item2     Gas
=end code

This would produce:

=item1  Animal
=item2     Vertebrate
=item3     Mammals
=item4     Primates
=item2     Invertebrate

=item1  Phase
=item2     Solid
=item3        Crystalline
=item3        Amorphous
=item2     Liquid
=item2     Gas

Note, however, that C blocks within the same list are not I nested.
That is, lower-level items should not be specified inside higher-level items:
=begin code :lang
    =comment THE WRONG WAY...
    =begin item1          ───────────────┐
    The choices are:                     |
    =item2 Liberty          ─── Level 2  ├─── Level 1
    =item2 Death            ─── Level 2  |
    =item2 Beer             ─── Level 2  |
    =end item1            ───────────────┘

    =comment THE CORRECT WAY...
    =begin item1          ───────────────┐
    The choices are:                     ├─── Level 1
    =end item1            ───────────────┘
    =item2 Liberty        ─────────────────── Level 2
    =item2 Death          ─────────────────── Level 2
    =item2 Beer           ─────────────────── Level 2
=end code

=head3 Multi-paragraph lists

Using the delimited form of the C<=item> block (C<=begin item> and C<=end item>),
we can specify items that contain multiple paragraphs.

For example:

=begin code :lang
Let's consider two common proverbs:

=begin item
I

This is a common myth and an unconscionable slur on the Spanish people,
the majority of whom are extremely attractive.
=end item

=begin item
I

In deciding whether to become an early riser, it is worth considering
whether you would actually enjoy annelids for breakfast.
=end item

As you can see, folk wisdom is often of dubious value.
=end code
This renders as:
=begin nested
Let's consider two common proverbs:

=begin item
I

This is a common myth and an unconscionable slur on the Spanish people,
the majority of whom are extremely attractive.
=end item

=begin item
I

In deciding whether to become an early riser, it is worth considering
whether you would actually enjoy annelids for breakfast.
=end item

As you can see, folk wisdom is often of dubious value.
=end nested

=head3 Bullets and bullet strategy

When rendered, each C<=item>R will be preceded by a bullet and each level
may have a different bullet. A compliant renderer will define a I bullet for at least the first four
levels within a nested list, with the bulleting strategy for other levels being up to the renderer.

The default bullet can be over-ridden with a custom bullet for any C<=item>R, for example
=begin code :lang :allow
The project originally consisted of five phases, of which
two are already complete and two have been abandoned:

=for item B<:bullet< E >>
Investigate existing solutions

=for item B<:bullet< E >>
Define a minimal initial feature set

for item B<:bullet< E >>
Implement this minimal set of features

=for item B<:bullet< E >>
Secure 100 million in venture capital

for item B<:bullet< E >>
Abscond to the Bahamas with the cash
=end code
... would produce something like a list with checkboxes, thus:
=begin nested
=begin code
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
=end code
=end nested

However, more interesting bullets are possible, including multiple characters. For example:
=begin code :lang :allow
=for item B<:bullet< E >>
Investigate existing solutions

=for item B<:bullet< E >>
Define a minimal initial feature set

=for item B<:bullet< E >>
Implement this minimal set of features

=for item B<:bullet< E >>
Secure 100 million in venture capital

=for item B<:bullet< E >>
Abscond to the Bahamas with the cash
=end code
... to produce
=begin nested
=begin code
✅     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
=end code
=end nested

By using the C<=config> directive, it is also possible to change the default bullets for
the duration of a section. For example,
=begin code :lang :allow
    =begin section

    B<=config item1 :bullet< E >>
    B<=config item2 :bullet< E >>

    The major sources of sustainable energy are:
        =item1 wind
        =item1 hydroelectric
        =item1 solar
        =item1 geothermal
        =item1 fusion
        =item2 (eventually)
    =end section
=end code
...which would produce:
=begin nested
=begin code
The major sources of sustainable energy are:
🌍 wind
🌍 hydroelectric
🌍 solar
🌍 geothermal
🌍 fusion
   🤞(eventually)
=end code
=end nested

In the event that a custom bullet cannot be rendered (e.g. a specified Unicode glyph is unrecognised or unrenderable in the target format),
a compliant renderer will fall back to its default bullet and generate an error message.

=head3 Ordered lists

A C<=numitemN> expresses the I of a list:
=begin code :lang
     =numitem1 Visito
     =numitem2 Veni
     =numitem2 Vidi
     =numitem2 Vici
=end code
This would produce something like:
=begin nested
1. Visito

1.1. Veni

1.2. Vidi

1.3. Vici
=end nested

The numbering scheme is at the discretion of the renderer. A renderer might, for example,
provide a scheme similar to the examples here, and also provide an enhancement, such as
`:html-ordered` that leverages the `

` markup. The numbering of successive C<=numitem1> list items increments automatically, but is reset to 1 whenever any other kind of non-ambient RakuDoc block appears between two C<=numitem1> blocks. For example: =begin code :lang The options are: =numitem1 Liberty =numitem1 Death =numitem1 Beer The tools are: =numitem1 Revolution =numitem1 Deep-fried peanut butter sandwich =numitem1 Keg =end code This would produce: =begin nested The options are: 1. Liberty 2. Death 3. Beer The tools are: 1. Revolution 2. Deep-fried peanut butter sandwich 3. Keg =end nested The numbering of nested items (C<=numitem2>, C<=numitem3>, etc.) only resets to 1 when a higher-level item's numbering either resets or increments. To prevent a C<=numitemN> from resetting after a non-item block, you can specify the C<:continued> option: =begin code :lang =numitem1 Retreat to remote Himalayan monastery =numitem1 Learn the hidden mysteries of space and time I =for numitem1 :continued Prophet! =end code This produces: =begin nested 1. Retreat to remote Himalayan monastery 2. Learn the hidden mysteries of space and time ???? 3. Prophet! =end nested Normally, if two C<=numitemN> blocks are separated by some other kind of block (for example, a C<=para>, C<=code>, or C<=table> block), then the numbering of the second C<=numitemN> block resets to 1. However, if the second C<=numitemN> block is specified with a C<:continued> option the numbering of that second block does not reset, but increments instead (i.e. as if there had been no intervening non-numbered block). The C<:continued> option has no effect on any higher- or lower-numbered C<=numitem> blocks that are currently active in the same scope. That is: a C<=for numitemN :continued> causes the numbering of every active C<=numitemZ> block (where I > I) to reset to 1, and the numbering of every active C<=numitemA> block (where I

< I) stays the same. A C<=numitem> is the same as a C<=numitem1>, by analogy with C<=item> and C<=head>. The underlying paradigm is that every sequence of list instructions (that is: C<=itemN> and/or C<=numitemN> instructions) has an I. The C<=numitemN> instructions express the numeration when rendered, while the C<=itemN> instructions do not. When a sequence of list instructions is terminated by another sort of block then by default a new list is created with its own inherent numeration. By specifying C<:continued> on the B list instruction, the previous I is preserved and continued. =head3 Definition lists Lists that define terms or commands can be specified using the C<=defn> block, which is equivalent to HTML C

. The contents of the unrecognised custom block should be rendered verbatim, like a C<=code> block. Consequently, multi-paragraph contents should be enclosed using the I form of the block. =head2 Naming rules In order to avoid conflicts between built-in blocks, semantic blocks, custom blocks, and markup instructions, the following rules must be followed: =item Builtin blocks (e.g. C, C, C