) =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<text> ┊=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 :lang<RakuDoc> =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: =for table :!toc :caption('') 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. =for table :!toc :caption('') Inline markup Instruction Mnemonic HTML equivalent Markdown equivalent ============= =========== =================== ================== =================== Basis V«B<text>» "B for Basis" C«text» **text** Important V«I<text>» "I for Important" C«text» *text* Unusual V«U<text>» "U for Unusual" C«text» __text__ Strikethrough V«O<text>» "O for Overstrike" C«<s>text</s>» ~~text~~ Superscript V«H<text>» "H for High text" C«text» ^text^ Subscript V«J<text>» "J for Junior text" C«text» ~text~ Code V«C<text>» "C for Code" C«<code>text</code>» `text` The table contains suggested HTML and Markdown equivalents; a renderer may choose other representations. This syntax does not provide a mechanism to associate metadata options with formatting codes explicitly. It is, however, possible to do this via a C<=config> directive. For example, C< C<> > markup by default does not allow for embedded format codes to be rendered, but an author might want C< B<> > to be allowed. This can be achieved with: =config C :allow This mechanism is explained further in the L<syntax section|#Directive syntax>. =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. The exact name of the resource to which a link is pointing must be used by the renderer. So C<L< For reference | README.md >> or C<L< text reference | README >> must link to C<README.md> and to C<README>, with the renderer making no assumption about the file format. However, a collection of RakuDoc sources may be intended as the base for multiple formats, such as C< .html >, C< .md >, or C< .pdf >, and so links within the collection may need to delegate the selection of an appropriate file format (if one is needed) to the renderer. This is accomplished explicitly using the C< .* > pseudo extension, for example: L< dealing with the filesystem | type/IO.Path.* > or for a heading within another resource: L< getting a directory listing | type/IO.Path.*#routine_dir > For example, if the output format is Markdown, these links would be rendered with C<.md> extensions replacing the C<.*> pseudo-extensions: [dealing with the filesystem](type/IO.Path.md) [getting a directory listing](type/IO.Path.md#routine_dir) Or, if the output format is HTML, these links would be rendered with C<.html> extensions instead: <a href="type/IO.Path.html"> dealing with the filesystem </a> <a href="type/IO.Path.html#routine_dir"> getting a directory listing </a> 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 :lang<RakuDoc> 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 :lang<RakuDoc> 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. For this reason, the term is rendered verbatim, including any attempted markup codes. 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 :lang<RakuDoc> 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 :lang<RakuDoc> 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 :lang<RakuDoc> 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 :lang<RakuDoc> BV«< » I<DISPLAY-TEXT> V« >» CV«< » I<DISPLAY-TEXT> V« >» HV«< » I<DISPLAY-TEXT> V« >» IV«< » I<DISPLAY-TEXT> V« >» JV«< » I<DISPLAY-TEXT> V« >» KV«< » I<DISPLAY-TEXT> V« >» RV«< » I<DISPLAY-TEXT> V« >» SV«< » I<DISPLAY-TEXT> V« >» TV«< » I<DISPLAY-TEXT> V« >» UV«< » I<DISPLAY-TEXT> V« >» VV«< » I<DISPLAY-TEXT> V« >» NV«< » I<DISPLAY-TEXT> V« >» OV«< » 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 :lang<RakuDoc> AV«< » I<DISPLAY-TEXT > V« | » METADATA=B<ALIAS-NAME>V« >» DV«< » I<DISPLAY-TEXT > V« | » METADATA=B<SYNONYMS>V« >» ΔV«< » I<DISPLAY-TEXT > V« | » METADATA=B<VERSION-ETC>V« >» EV«< » I<DISPLAY-TEXT > V« | » METADATA=B<HTML/UNICODE-ENTITIES>V« >» FV«< » I<DISPLAY-TEXT > V« | » METADATA=B<LATEX-FORM>V« >» LV«< » I<DISPLAY-TEXT > V« | » METADATA=B<TARGET-URI>V« >» MV«< » I<DISPLAY-TEXT > V« | » METADATA=B<WHATEVER>V« >» PV«< » I<DISPLAY-TEXT > V« | » METADATA=B<REPLACEMENT-URI>V« >» XV«< » 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 ZV«< » 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 =begin table :caption<Directives> :headlevel(2) =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 =begin table :caption<Blocks> :headlevel(2) =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 =begin table :caption<Metadata options> :headlevel(2) =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 =begin table :caption<Markup instructions> :headlevel(2) =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 which might render as: =begin nested =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 nested 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 may apply language specific syntax highlighting to the contents of a code block according to the following rules: =item C<=code> blocks with no explicit or preconfigured C<:lang> option default to C<:lang>. =item C<=code> blocks can be marked as not being in any specific language by using C<:!lang>. =item Renderers must not syntax-highlight any code block whose C<:lang> value is C, that is C<:!lang>. =item Renderers must not syntax-highlight any code block whose C<:syntax-highlighting> value is C; by default C<:syntax-highlighting> is True. =item Renderers may syntax-highlight any other code block (including C<:lang>), but are not required to do so. 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>. =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 overridden 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« \c[BALLOT BOX WITH CHECK] »>
Investigate existing solutions

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

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

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

=for item B<:bullet« \c[BALLOT BOX WITH X] »>
Abscond to the Bahamas with the cash
=end code
... would produce something like a list with checkboxes, thus:
=begin nested
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
=end nested

However, more interesting bullets are possible, including multiple characters. For example:
=begin code :lang :allow
=for item B<:bullet« \c[Heavy Check Mark] »>
Investigate existing solutions

=for item B<:bullet« \c[Heavy Check Mark] »>
Define a minimal initial feature set

=for item B<:bullet« \c[Anticlockwise Downwards And Upwards Open Circle Arrows] »>
Implement this minimal set of features

=for item B<:bullet« \c[prohibited sign] »>
Secure 100 million in venture capital

=for item B<:bullet« \c[prohibited sign, palm tree] »>
Abscond to the Bahamas with the cash
=end code
... to produce
=begin nested
=for item :bullet« \c[Heavy Check Mark] »
Investigate existing solutions

=for item :bullet« \c[Heavy Check Mark] »
Define a minimal initial feature set

=for item :bullet« \c[Anticlockwise Downwards And Upwards Open Circle Arrows] »
Implement this minimal set of features

=for item :bullet« \c[prohibited sign] »
Secure 100 million in venture capital

=for item :bullet« \c[prohibited sign, palm tree] »
Abscond to the Bahamas with the cash
=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« \c[Earth Globe Europe-Africa] » >
    B<=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
=end code
...which would produce:
=begin nested
=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

=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
C<:html-ordered> that leverages the C«

» 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
lists in HTML. A definition contains two parts: a term and a defining text. The term is the contents of the first line of the C block (i.e. the text immediately after an abbreviated C<=defn>, or the first line after a C<=for defn> or C<=begin defn>). The defining text is the remaining lines within the scope of the C block. A renderer is expected to distinguish between the term and the defining text. For this reason, the term part is rendered verbatim, including any attempted markup codes. For example: =begin code :lang =defn Happy When you're not blue. =defn Blue When you're not happy. =end code ...will be rendered as: =defn Happy When you're not blue. =defn Blue When you're not happy. A renderer is expected to retain the information generated by a definition list, and the defining text may be targeted by a L. =head4 Numbered definitions Definitions can be numbered in the same way as C<=item> lists. That is a C<=numdefn> instruction will express the I of the definition list when it is rendered. As with ordinary lists, if a C<=numdefn> instruction is associated with a C<:continued> metadata option, then the preceding definition list's inherent numeration is preserved and continued. For example: =begin code :lang =numdefn AAA first letters =numdefn BBB second letters A normal para =numdefn XXX ending letters =numdefn YYY finals =end code will yield something like: =numdefn AAA first letters =numdefn BBB second letters A normal para =numdefn XXX ending letters =numdefn YYY finals In order to continue a list, an explicit C<:continued> is needed, such as: =begin code :allow :lang =numdefn AAA first letters =numdefn BBB second letters A normal para =for numdefn B<:continued> XXX ending letters =numdefn YYY finals =end code will yield something like =numdefn AAA first letters =numdefn BBB second letters A normal para =for numdefn :continued XXX ending letters =numdefn YYY finals Suppose a writer needs every numbered definition to form a single monotonic sequence within some block scope (e.g. for every definition within a document section, or every definition throughout the entire document). This would require every C<=numdefn> to be specified with a C<:continued> option. Or the writer could simply pre-configure every C<=numdefn> within the scope, as follows: =begin code :lang =config numdefn :continued =end code =head2 Tables Tables can be specified in RakuDoc using a C<=table> block using either a I definition, or a I definition. The I semantics allow for a simple table to be quickly specified, but the simplicity imposes a number of constraints. The I semantics overcome those constraints by describing the contents of rows, columns, and cells. A table may be given an associated description or title using the C<:caption> option and included in the L. A I table may only be specified in the I form. As will become clear below, I are assumed if the next RakuDoc instruction after a C<=begin table> is one of C<=row>, C<=column>, or C<=cell>. =head3 Visual description of simple tables In a visual table specification, columns are separated by two or more consecutive whitespace characters (e.g. double-space or twin-tabs), or by a vertical line (C<|>) or a border intersection (C<+>), either of which must be separated from any content by at least one whitespace character. Note that only one column separator type is allowed in a single line, but different lines are allowed to use different visible column separator types (though that style is not recommended). Using a mixture of visible and non-visible column separator types in a table is an error. Rows can be specified in one of two ways: either one row per line, with no separators; or multiple lines per row with explicit horizontal separators (whitespace, intersections (C<+>), or horizontal lines: C<->, C<=>, C<_>) between I row. Either style can also have an explicitly separated header row at the top. If rows are using the two-whitespace-character separator, the row cells should be carefully aligned to ensure the table is interpreted as the user intended. Each individual table cell is separately formatted, as if it were a nested C<=para>. Note that table rows are expected to all have the same number of cells. This means you can create tables compactly, line-by-line: =begin code :lang =table The Shoveller Eddie Stevens King Arthur's singing shovel Blue Raja Geoffrey Smith Master of cutlery Mr Furious Roy Orson Ticking time bomb of fury The Bowler Carol Pinnsler Haunted bowling ball =end code or line-by-line with multi-line headers: =begin code :lang =table Superhero | Secret | | Identity | Superpower ==============|=================|================================ The Shoveller | Eddie Stevens | King Arthur's singing shovel Blue Raja | Geoffrey Smith | Master of cutlery Mr Furious | Roy Orson | Ticking time bomb of fury The Bowler | Carol Pinnsler | Haunted bowling ball =end code or with multi-line headers I multi-line data: =begin code :lang =begin table :caption('The Other Guys') Secret Superhero Identity Superpower ============= =============== =================== The Shoveller Eddie Stevens King Arthur's singing shovel Blue Raja Geoffrey Smith Master of cutlery Mr Furious Roy Orson Ticking time bomb of fury The Bowler Carol Pinnsler Haunted bowling ball =end table =end code Visual-style tables can only have a single header row (namely: everything before the first C<=====> line). That single header may, however, span one or more initial lines of the visual table specification, as some of the preceding examples illustrate. However, regardless of how many lines a visual-style header spans, it is always treated as a single header row. Individual renderers are free to choose how they represent visual header contents that have line breaks in them: they may treat them as a single string to be reflowed and wrapped, or they may elect to preserve the original line breaks within each header cell. The only requirement is that the entire header of a visual-style table must be rendered as a single row of cells. If two or more header rows are required, use a I instead. =head4 Valid tables Following are examples of valid tables. =begin code :lang =begin table The Shoveller Eddie Stevens King Arthur's singing shovel Blue Raja Geoffrey Smith Master of cutlery Mr Furious Roy Orson Ticking time bomb of fury The Bowler Carol Pinnsler Haunted bowling ball =end table =end code =begin code :lang =table Constants 1 Variables 10 Subroutines 33 Everything else 57 =end code =begin code :lang =for table mouse | mice horse | horses elephant | elephants =end code =begin code :lang =table Animal | Legs | Eats ======================= Zebra + 4 + Cookies Human + 2 + Pizza Shark + 0 + Fish =end code =begin code :lang =table Superhero | Secret | | Identity | Superpower ==============|=================|================================ The Shoveller | Eddie Stevens | King Arthur's singing shovel =end code =begin code :lang =begin table Secret Superhero Identity Superpower ============= =============== =================== The Shoveller Eddie Stevens King Arthur's singing shovel Blue Raja Geoffrey Smith Master of cutlery Mr Furious Roy Orson Ticking time bomb of fury The Bowler Carol Pinnsler Haunted bowling ball =end table =end code =begin code :lang =table X | O | ---+---+--- | X | O ---+---+--- | | X =end code =begin code :lang =table X O =========== X O =========== X =end code =begin code :lang =begin table foo bar =end table =end code =head4 Invalid tables Following are examples of invalid tables, and they should trigger an unhandled exception during parsing. =item Mixed column separator types in the same row are not allowed: =begin code :lang =begin table r0c0 + r0c1 | r0c3 =end table =end code =item Mixed visual and whitespace column separator types in the same table are not allowed: =begin code :lang =begin table r0c0 + r0c1 | r0c3 r1c0 r0c1 r0c3 =end table =end code =item Two consecutive interior row separators are not allowed: =begin code :lang =begin table r0c0 | r0c1 ============ ============ r1c0 | r1c1 =end table =end code =head4 Unexpected tables Following are examples of valid tables that are probably intended to be two columns. However, the columns in these examples are not aligned well, so each will parse as a single-column table. =begin item Unaligned columns with WS column separators: Notice the second row has the two words separated by only B WS character, while it takes at least B adjacent WS characters to define a column separation. B. =begin code :lang =begin table r0c0 r0c1 r1c0 r0c1 =end table =end code =end item =begin item Unaligned columns with visual column separators: Notice the second row has the two words separated by a visible character (V<'|'>) but the character is not recognized as a column separator because it doesn't have an adjacent WS character on both sides of it. Although this is a legal table, the result will not be what the user intended because the first row has two columns while the second row has only one column, and it will thus have an empty second column. =begin code :lang =begin table r0c0 | r0c1 r1c0 |r0c1 =end table =end code =end item =head3 Procedural description of tables A visual table is useful for most purposes, but a I description is needed if one or more of the following are required: =item row labels, =item vertical or horizontal alignments of individual cells, of complete rows or columns, or of the entire table, =item cells spanning multiple rows and/or columns, =item cells that include other RakuDoc blocks, such as a nested sub-table or a code block. Table semantics are I if the C<=table> declarator is immediately followed by C<=cell>, C<=row>, or C<=column>, otherwise I semantics are assumed. Only C<=cell>, C<=row>, C<=column>, or C<=comment> declarations are permitted within the immediate block scope of a procedural table. Note that both C<=cell> and C<=comment> introduce their own block scopes, so other RakuDoc blocks (including nested tables) may be included within their block scopes. The fundamental idea is that a procedural C<=table> sets up a semi-infinite 2D grid of cells, all of which are initially empty. The grid also tracks the fill position (I<$POS>: the next empty cell to be filled), and the fill direction (I<$DIR>: the direction to move I<$POS> after filling; either I or I). Subsequent C<=cell> blocks start filling that grid in, with any intervening C<=row> and C<=column> directives adjusting I<$POS> and I<$DIR>. C<=cell> blocks can be specified as spanning multiple rows and/or columns, using the C<:row-span(WIDTH)>, C<:col-span(HEIGHT)>, or C<:span(WIDTH, HEIGHT)> annotations, in which case the block fills more than one grid cell (and merges them into a single logical cell), with the top-left corner of the fill starting at I<$POS>. A C<=cell> block has the following effects: =item The specified contents are considered to fill in the cell(s) at I<$POS> (even if the contents are actually null/empty) =item I<$POS> is moved to the next unfilled cell in the direction specified by I<$DIR> (I either across or down) A C<=row> directive has the following effects: =item I<$DIR> is set to I =item If the previous action was not a C<=cell> (I it was a C<=table> , C<=row>, or C<=column>) then the C<=row> directive has no other effects (I the subsequent effect is skipped) =item Otherwise, starting at the row specified by I>, find the uppermost row I that is B> the row specified by I>, and where row I has at least one empty cell in a column strictly to the left of the column specified by I>, then move I> left-and-down, to the B> empty cell in row I. A C<=column> directive has the following effects: =item I<$DIR> is set to I =item If the previous action was not a C<=cell> (I it was a C<=table> , C<=row>, or C<=column>) then the C<=column> directive has no other effects (I the subsequent effect is skipped) =item Otherwise, starting at the column specified by I>, find the left-most column I that is B> the column specified by I>, and where column I has at least one empty cell in a row strictly above the row specified by I>, then move I> up-and-right, to the B> empty cell in column I In other words, C<=row> searches the south-west quadrant from I> to find the most north-westerly empty cell ... and moves I> to that cell. And C<=column> searches the north-east quadrant from I> to find the most north-westerly empty cell ... and moves I> to that cell. In addition, C<=table> and C<=cell> blocks and C<=row> and C<=column> directives can be annotated with any of the following metadata, which subsequently act as defaults for any C<=cell> in their scope: =item C<:align< ALIGNMENTS >> : changes how contents are aligned in a cell I may be any one of: C, C, C, C, and/or any one of: C, C, C. =item C<:header> : specifies that the cell(s) should be considered column headers =item C<:label> : specifies that the cell(s) should be considered row labels (I horizontal headers) Let’s see how it works... The following RakuDoc specification: =begin code :lang =begin table :caption =row :header =for cell :row-span(2) Date =for cell :column-span(3) Samples =for cell :row-span(2) Mean =row :header =cell I =cell I =cell I =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 =end code ... produces the following table: =begin table :!toc :caption =row :header =for cell :row-span(2) Date =for cell :column-span(3) Samples =for cell :row-span(2) Mean =row :header =cell I =cell I =cell I =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 Let’s examine how that specification creates that layout, step by step. Note that, in the following diagram, the various symbols have these meanings: =begin code :lang ┌───┐ │ │ : An empty table cell └───┘ ┌───┐ │ → │ : The empty cell at $POS; $DIR is currently "across" └───┘ ┌───┐ │ ↓ │ : The empty cell at $POS; $DIR is currently "down" └───┘ ┌───┐ │+++│ : The most recently filled cell └───┘ ┌───┐ │###│ : A previously filled cell └───┘ =end code And now the step-by-step explanation: =begin code :lang =begin table ┌───┬───┬───┬───┬───┬───┬┈┈ │ → │ │ │ │ │ │ (Create a new table grid ├───┼───┼───┼───┼───┼───┼┈┈ Default $POS is [0,0] │ │ │ │ │ │ │ Default $DIR is across) ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =row :header ┌───┬───┬───┬───┬───┬───┬┈┈ │ → │ │ │ │ │ │ (Previous action was not =cell ├───┼───┼───┼───┼───┼───┼┈┈ So set $DIR to "across" │ │ │ │ │ │ │ and don't change $POS) ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =for cell :row-span(2) ┌───┬───┬───┬───┬───┬───┬┈┈ Date │+++│ → │ │ │ │ │ │+++│───┼───┼───┼───┼───┼┈┈ (Fill in 1x2 cells │+++│ │ │ │ │ │ starting from $POS ├───┼───┼───┼───┼───┼───┼┈┈ Then move $POS to │ │ │ │ │ │ │ first empty cell ├───┼───┼───┼───┼───┼───┼┈┈ in $DIR direction) │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =for cell :column-span(3) ┌───┬───────────┬───┬───┬┈┈ Samples │###│+++++++++++│ → │ │ │###├───┬───┬───┼───┼───┼┈┈ (Fill in 3x1 cells │###│ │ │ │ │ │ starting from $POS ├───┼───┼───┼───┼───┼───┼┈┈ Then move $POS to │ │ │ │ │ │ │ first empty cell ├───┼───┼───┼───┼───┼───┼┈┈ in $DIR direction) │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =for cell :row-span(2) ┌───┬───────────┬───┬───┬┈┈ Mean │###│###########│+++│ → │ │###├───┬───┬───┤+++│───┼┈┈ (Fill in 1x2 cells │###│ │ │ │+++│ │ starting from $POS ├───┼───┼───┼───┼───┼───┼┈┈ Then move $POS to │ │ │ │ │ │ │ first empty cell ├───┼───┼───┼───┼───┼───┼┈┈ in $DIR direction) │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =row :header ┌───┬───────────┬───┬───┬┈┈ │###│###########│###│ │ (Find the next row at or │###├───┬───┬───┤###│───┼┈┈ below the current $POS │###│ → │ │ │###│ │ that has an empty cell ├───┼───┼───┼───┼───┼───┼┈┈ to the left of $POS, then │ │ │ │ │ │ │ move $POS to the leftmost ├───┼───┼───┼───┼───┼───┼┈┈ cell on that row, and set │ │ │ │ │ │ │ $DIR to "across") ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =cell Sample 1 ┌───┬───────────┬───┬───┬┈┈ │###│###########│###│ │ (Fill in 1x1 cell at $POS │###├───┬───┬───┤###│───┼┈┈ then move $POS to │###│+++│ → │ │###│ │ the first empty cell ├───┼───┼───┼───┼───┼───┼┈┈ in $DIR direction) │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =cell Sample 2 ┌───┬───────────┬───┬───┬┈┈ │###│###########│###│ │ (Fill in 1x1 cell at $POS │###├───┬───┬───┤###│───┼┈┈ then move $POS to │###│###│+++│ → │###│ │ the first empty cell ├───┼───┼───┼───┼───┼───┼┈┈ in $DIR direction) │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =cell Sample 3 ┌───┬───────────┬───┬───┬┈┈ │###│###########│###│ │ (Fill in 1x1 cell at $POS │###├───┬───┬───┤###│───┼┈┈ then move $POS to │###│###│###│+++│###│ → │ the first empty cell ├───┼───┼───┼───┼───┼───┼┈┈ in $DIR direction) │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =row ┌───┬───────────┬───┬───┬┈┈ │###│###########│###│ │ (Move $POS down to the │###├───┬───┬───┤###│───┼┈┈ next row with an empty cell │###│###│###│###│###│ │ that's to the left of $POS ├───┼───┼───┼───┼───┼───┼┈┈ and to left-most empty cell │ → │ │ │ │ │ │ on that row) ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =column ┌───┬───────────┬───┬───┬┈┈ │###│###########│###│ │ (Previous action was not a │###├───┬───┬───┤###│───┼┈┈ =cell so set $DIR to "down", │###│###│###│###│###│ │ with no other effect) ├───┼───┼───┼───┼───┼───┼┈┈ │ ↓ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =cell 2023-03-08 ┌───┬───────────┬───┬───┬┈┈ =cell 2023-04-14 │###│###########│###│ │ =cell 2023-06-23 │###├───┬───┬───┤###│───┼┈┈ │###│###│###│###│###│ │ (Each =cell block ├───┼───┼───┼───┼───┼───┼┈┈ fills in a 1x1 cell │+++│ │ │ │ │ │ at $POS, then moves ├───┼───┼───┼───┼───┼───┼┈┈ $POS to the first empty │+++│ │ │ │ │ │ cell in $DIR direction) ├───┼───┼───┼───┼───┼───┼┈┈ │+++│ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ ↓ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =column ┌───┬───────────┬───┬───┬┈┈ │###│###########│###│ │ (Previous action was │###├───┬───┬───┤###│───┼┈┈ a =cell, so move $POS │###│###│###│###│###│ │ to the uppermost empty ├───┼───┼───┼───┼───┼───┼┈┈ cell in the first non-full │###│ ↓ │ │ │ │ │ column to the right, ├───┼───┼───┼───┼───┼───┼┈┈ and set $DIR to "down") │###│ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │###│ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =cell 0.4 ┌───┬───────────┬───┬───┬┈┈ =cell 0.8 │###│###########│###│ │ =cell 0.2 │###├───┬───┬───┤###│───┼┈┈ │###│###│###│###│###│ │ (Each =cell block ├───┼───┼───┼───┼───┼───┼┈┈ fills in a 1x1 cell │###│+++│ │ │ │ │ at $POS, then moves ├───┼───┼───┼───┼───┼───┼┈┈ $POS to the first empty │###│+++│ │ │ │ │ cell in $DIR direction) ├───┼───┼───┼───┼───┼───┼┈┈ │###│+++│ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ │ ↓ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =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 │ │ │ │ │ ↓ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ (Rinse and repeat) ┊ ┊ ┊ ┊ ┊ ┊ ┊ =row ┌───┬───────────┬───┬───┬┈┈ │###│###########│###│ │ ($POS row is entirely empty │###├───┬───┬───┤###│───┼┈┈ so it's the first row with │###│###│###│###│###│ │ an empty cell to the left ├───┼───┼───┼───┼───┼───┼┈┈ of $POS, so stay on current │###│###│###│###│###│ │ row and move $POS to the ├───┼───┼───┼───┼───┼───┼┈┈ left-most empty cell in row; │###│###│###│###│###│ │ change $DIR to "across") ├───┼───┼───┼───┼───┼───┼┈┈ │###│###│###│###│###│ │ ├───┼───┼───┼───┼───┼───┼┈┈ │ → │ │ │ │ │ │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =for cell :label ┌───┬───────────┬───┬───┬┈┈ Mean: │###│###########│###│ │ =cell 0.46667 │###├───┬───┬───┤###│───┼┈┈ =cell 0.53333 │###│###│###│###│###│ │ =cell 0.26667 ├───┼───┼───┼───┼───┼───┼┈┈ =cell 0.42222 │###│###│###│###│###│ │ ├───┼───┼───┼───┼───┼───┼┈┈ (Fill in 1x1 cells, │###│###│###│###│###│ │ moving $POS each time ├───┼───┼───┼───┼───┼───┼┈┈ in the direction │###│###│###│###│###│ │ specified by $DIR) ├───┼───┼───┼───┼───┼───┼┈┈ │+++│+++│+++│+++│+++│ → │ ├───┼───┼───┼───┼───┼───┼┈┈ ┊ ┊ ┊ ┊ ┊ ┊ ┊ =end table ┌───┬───────────┬───┐ │###│###########│###│ (Terminate grid-filling │###├───┬───┬───┤###│ then trim the table to │###│###│###│###│###│ the bounding box around ├───┼───┼───┼───┼───┤ all filled cells) │###│###│###│###│###│ ├───┼───┼───┼───┼───┤ │###│###│###│###│###│ ├───┼───┼───┼───┼───┤ │###│###│###│###│###│ ├───┼───┼───┼───┼───┤ │###│###│###│###│###│ └───┴───┴───┴───┴───┘ =end code =head2 Formulae RakuDoc v.2 provides a built-in block C<=formula> and an inline markup code C«F<>» to contain text that will be rendered as formulae. There are several markup languages for expressing mathematical expressions, so the RakuDoc v.2 specification I the currently most widespread markup syntax for C<=formula> and C«F<>», namely the L, including the extensions specified in the L This does not preclude the development of custom blocks to support other mathematical markup languages, eg., a C«=MathML» custom block to support another syntax. Implementors of renderers are B> required to render the contents of these instructions; it is acceptable for a renderer to render the contents of a C<=formula> or C«F<>» in some other way than as a fully realized mathematical equation. For example, the following two formulae: =begin code :lang We will use the identity: F<\sum \frac{1}{n^{2}} = \frac{\pi^{2}}{6}> ...where the value of pi can be inferred from Euler’s Identity: =formula e^{i\pi}+1=0 =end code ...may either be rendered “accurately”: =begin nested =begin code :lang We will use the identity: F<\sum \frac{1}{n^{2}} = \frac{\pi^{2}}{6}> ...where the value of pi can be inferred from Euler’s Identity: =formula e^{i\pi}+1=0 =end code =end nested ... or may be converted to a suitable Unicode approximation: =begin nested We will use the identity: ∑ 1/n² = 𝜋²/6 ...where the value of pi can be inferred from Euler’s Identity: eⁱᐢ + 1 = 0 =end nested ... or may even left as raw LaTeX (perhaps with some kind of visual marker indicating that it is unprocessed): =begin nested We will use the identity: U> ... where the value of pi can be inferred from Euler’s Identity: U> =end nested Both C<=formula> and C«F<>» may take explicit ALT texts, so that the author can decide how their formula should be rendered in cases where the renderer cannot handle the specification. That is, the C<=formula> block accepts an `:alt` metaoption, and the syntax for the C«F<>» instruction is either C«» or C«F< ALT | FORMULA >». Using the ALT text options, the document author can supply a suitable explicit alternative rendering to renderers that cannot handle the full formula syntax: =begin code :lang We will use the identity: F<∑ 1/n² = 𝜋²/6 | \sum \frac{1}{n^{2}} = \frac{\pi^{2}}{6}> ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑ ...where the value of pi can be inferred from Euler’s Identity: =for formula :alt< eH + 1 = 0 > e^{i\pi}+1=0 ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑ =end code An ALT text allows an author to rely on getting an “accurate” representation under those renderers that fully support formulas, and to be able to fall back on a range of reasonable alternatives under those renderers that don’t: =begin table :caption :!toc =row :header =cell Fall back on =cell Example =row =cell Plaintext =cell FV«< Euler's Identity | e^{i\pi}+1=0 >» =row =cell RakuDoc =cell FV«< eH + 1 = 0 | e^{i\pi}+1=0 >» =row =cell Unicode =cell FV«< eⁱᐢ + 1 = 0 | e^{i\pi}+1=0 >» =row =cell Image =cell FV«» =row =cell Link =cell FV«< L | e^{i\pi}+1=0 >» =end table It is also possible to B the fallback options. For example, they could try for an “accurate” rendering of a formula, but fall back on the placement of a pre-rendered image, or (failing to find that) fall back again to a RakuDoc representation with an outgoing link: =begin code :lang We will use: F< P< L< eH + 1 = 0 | https://en.wikipedia.org/wiki/Euler%27s_identity > | file:EulerID.jpg > | e^{i\pi}+1=0 > =end code Implementors are free to delay – or reject – implementing LaTeX-based formulas, and implementations are considered compliant with the specification, so long as the ALT texts are rendered. =head2 RakuDoc comments RakuDoc comments are components that both RakuDoc renderers and ambient-code compilers ignore. Comments are useful for Idocumentation (documenting the documentation). Single-line comments use the C<=comment> marker: =begin code :lang =comment Add more here about the algorithm =end code For multi-line comments, use a delimited C block: =begin code :lang =begin comment This comment is multi-line. =end comment =end code =head2 Semantic blocks All uppercase block typenames are reserved for specifying standard documentation, publishing components, source constructs, or meta-information. The following must be recognised: =begin code :lang =NAME =AUTHOR =VERSION =TITLE =SUBTITLE =LICENSE =LICENCE =SYNOPSIS =end code The block name of a semantic block is to be rendered as if it were C<=head1 BLOCKNAME>, and the contents of the block are then to be rendered as one or more regular paragraphs. Consequently, if a semantic block has multiple lines, then its contents must be enclosed using the I> form. A semantic block may be defined, but omitted from the text in the place it is written. This is because sections about Authors, or Licensing, are sometimes required at the end, or at the beginning, or in the meta section of an HTML document. A renderer is expected to gather the contents of a semantic block for it to be accessible by an external program. If the metadata option C<:hidden> is associated with a semantic block (by using a C<=config> directive, or as a metadata option with the I or I forms) then the renderer will not render the semantic block at the position it is placed in the RakuDoc document. It will be placed in a data structure by the renderer and the contents can be rendered at a place defined by a L. The block name of a rendered semantic block will be placed in the L|#Table of Contents and Index> table in the position that it is rendered, unless the C<:toc>, C<:headlevel>, and or C<:caption> options are set. A C<:hidden> metadata option will also remove the block's entry from the ToC. But if it is placed by a C> instruction, the block entry will be placed at the appropriate point in the ToC. =head2 User-defined blocks When a block name contains both an upper case and a lower case character, as specified L, it is interpreted as a developer-defined block. The naming rules are to ensure that built-in blocks, semantic blocks, and custom blocks are never mixed up. The way in which a renderer styles the contents of a custom block depends on the renderer, and each renderer may specify a procedure for using user-supplied templates or code. The DOC phaser in Raku is the way an author can define which renderer to use, e.g.: =begin code :lang DOC use My::Special::Renderer; DOC use My::Other::Special::Renderer; =begin rakudoc ... =end rakudoc =end code Non-Raku environments might specify their own mechanisms for loading custom renderers. For example, they might require a RakuDoc comment at the start of the document: =begin code :lang =begin rakudoc =comment load MySpecialRenderer, MyOtherSpecialRenderer ... =end rakudoc =end code Or they might require that any special handlers be specified as metadata on the C block itself: =begin code :lang =begin rakudoc :Load< MySpecialRenderer MyOtherSpecialRenderer > ... =end rakudoc =end code If a renderer does not recognise a custom block, then the renderer should treat the block name as the contents of a C<=head1> block, which can be overridden as described in L
. 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
) =item2 names must be all lowercase and at least two characters long =item2 renderers may choose how to render builtin blocks, but must respect all the defined metadata options specified here, and may respect additional metadata options =item Semantic blocks (e.g. C, C) =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<text> ┊=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 :lang<RakuDoc> =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: =for table :!toc :caption('') 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. =for table :!toc :caption('') Inline markup Instruction Mnemonic HTML equivalent Markdown equivalent ============= =========== =================== ================== =================== Basis V«B<text>» "B for Basis" C«text» **text** Important V«I<text>» "I for Important" C«text» *text* Unusual V«U<text>» "U for Unusual" C«text» __text__ Strikethrough V«O<text>» "O for Overstrike" C«<s>text</s>» ~~text~~ Superscript V«H<text>» "H for High text" C«text» ^text^ Subscript V«J<text>» "J for Junior text" C«text» ~text~ Code V«C<text>» "C for Code" C«<code>text</code>» `text` The table contains suggested HTML and Markdown equivalents; a renderer may choose other representations. This syntax does not provide a mechanism to associate metadata options with formatting codes explicitly. It is, however, possible to do this via a C<=config> directive. For example, C< C<> > markup by default does not allow for embedded format codes to be rendered, but an author might want C< B<> > to be allowed. This can be achieved with: =config C :allow This mechanism is explained further in the L<syntax section|#Directive syntax>. =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. The exact name of the resource to which a link is pointing must be used by the renderer. So C<L< For reference | README.md >> or C<L< text reference | README >> must link to C<README.md> and to C<README>, with the renderer making no assumption about the file format. However, a collection of RakuDoc sources may be intended as the base for multiple formats, such as C< .html >, C< .md >, or C< .pdf >, and so links within the collection may need to delegate the selection of an appropriate file format (if one is needed) to the renderer. This is accomplished explicitly using the C< .* > pseudo extension, for example: L< dealing with the filesystem | type/IO.Path.* > or for a heading within another resource: L< getting a directory listing | type/IO.Path.*#routine_dir > For example, if the output format is Markdown, these links would be rendered with C<.md> extensions replacing the C<.*> pseudo-extensions: [dealing with the filesystem](type/IO.Path.md) [getting a directory listing](type/IO.Path.md#routine_dir) Or, if the output format is HTML, these links would be rendered with C<.html> extensions instead: <a href="type/IO.Path.html"> dealing with the filesystem </a> <a href="type/IO.Path.html#routine_dir"> getting a directory listing </a> 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 :lang<RakuDoc> 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 :lang<RakuDoc> 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. For this reason, the term is rendered verbatim, including any attempted markup codes. 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 :lang<RakuDoc> 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 :lang<RakuDoc> 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 :lang<RakuDoc> 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 :lang<RakuDoc> BV«< » I<DISPLAY-TEXT> V« >» CV«< » I<DISPLAY-TEXT> V« >» HV«< » I<DISPLAY-TEXT> V« >» IV«< » I<DISPLAY-TEXT> V« >» JV«< » I<DISPLAY-TEXT> V« >» KV«< » I<DISPLAY-TEXT> V« >» RV«< » I<DISPLAY-TEXT> V« >» SV«< » I<DISPLAY-TEXT> V« >» TV«< » I<DISPLAY-TEXT> V« >» UV«< » I<DISPLAY-TEXT> V« >» VV«< » I<DISPLAY-TEXT> V« >» NV«< » I<DISPLAY-TEXT> V« >» OV«< » 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 :lang<RakuDoc> AV«< » I<DISPLAY-TEXT > V« | » METADATA=B<ALIAS-NAME>V« >» DV«< » I<DISPLAY-TEXT > V« | » METADATA=B<SYNONYMS>V« >» ΔV«< » I<DISPLAY-TEXT > V« | » METADATA=B<VERSION-ETC>V« >» EV«< » I<DISPLAY-TEXT > V« | » METADATA=B<HTML/UNICODE-ENTITIES>V« >» FV«< » I<DISPLAY-TEXT > V« | » METADATA=B<LATEX-FORM>V« >» LV«< » I<DISPLAY-TEXT > V« | » METADATA=B<TARGET-URI>V« >» MV«< » I<DISPLAY-TEXT > V« | » METADATA=B<WHATEVER>V« >» PV«< » I<DISPLAY-TEXT > V« | » METADATA=B<REPLACEMENT-URI>V« >» XV«< » 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 ZV«< » 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 =begin table :caption<Directives> :headlevel(2) =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 =begin table :caption<Blocks> :headlevel(2) =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 =begin table :caption<Metadata options> :headlevel(2) =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 =begin table :caption<Markup instructions> :headlevel(2) =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