Specification.pod6

=begin pod :puburl('/specification')  :pubdate('2023-11-15 18:14:00')

=comment
This file is deliberately specified in Podlite format

=TITLE Podlite - a lightweight markup language

=begin nested :notify<warning> :caption('Work on the next release continues!')

If you have any ideas to make it better, or if you have any questions,
you're welcome to suggest changes or start a conversation on 
our L<GitHub page|https://github.com/podlite/podlite-specs/discussions>.

Looking forward to working on the next release with your valuable input.
=end nested

=toc head1, head2, head3

=begin AUTHORS
=item Damian Conway <L<C<damian@conway.org>|mailto:damian@conway.org>>
=item Aliaksandr Zahatski <L<C<zag@cpan.org>|mailto:zag@cpan.org>>
=end AUTHORS

=VERSION 1.0

=begin CHANGES
=head2 v1.0
=head3 New:
    =item Notification blocks, C<:notify> attribute for C<=nested> blocks,
    =item C<:folded> attribute,
    =item C<:folded-levels> for C<=toc> block,
    =item Refactor Named custom blocks and markup custom codes, C<M<>>,
    =item embedding binary data into documents, C<=data>, C<:filename>, C<:encoding>,
    =item C<:mime-type> attribute for C<=include> and C<=data> blocks,
    =item introduce C<data:> schema for use in C<=picture> and C<=table>,
    =item render tables from CSV files, C<=table>,
    =item new markdown mode for parser,
    =item C<M<>> - extends inline markup features,
    =item add C<:id>, C<:caption>, C<:lang> attributes,
    =item task lists, C<=item> and C<:checked> attribute,
    =item intro Selectors,
    =item table of contents, C<=toc>,
    =item include block, C<=include>,
    =item inserting pictures, C<=picture>, C<P<>>,
    =item mathematical formulas, C<=formula>, C<F<>>,
    =item Markdown support, C<=markdown>,
    =item mistake marking,  C<O<>>,
    =item text positioning, C<J<>>, C<H<>>,
    =item Emoji, C<E<>>,
    =item contextual backlinks, C<W<>>,
    =item advanced table format, C<=row>,C<=cell> blocks,
    C<:header>, C<:rowspan>, C<:colspan> attributes.
=head3 Deprecated/removed:
    =item Contextual aliases,
    =item C<=finish>,
    =item markers in comments,
    =item C<:margin> attribute,
    =item C<=encoding> directive,
    =item C<P<toc:>> due to C<=toc> block,
    =item C<P<man:>>, C<P<doc:>> due to C<=include> block,
    =item C<P<>> - placement links,
    =item Declarator block,
    =item C<:formatted> attribute,
    =item C<:like> attribute.
=end CHANGES

=head1 Podlite

D<Podlite> is an easy-to-use markup language with a simple, consistent
underlying document object model. Podlite can be used for writing language
documentation, for documenting programs and modules, as well as for
other types of document composition.

The Podlite is a purely descriptive mark-up notation, with no presentational
components.


=head2 General syntactic structure

Podlite documents are specified using D<directives|directive>, which are
used to declare configuration information and to delimit blocks of
textual content.

Every directive starts either with an equals sign (C<=>) followed
immediately by an identifier.

An D<identifier|Podlite identifiers> composed of an alphabetical character followed by 
any combination of alphanumeric characters. Alphabetic and numeric 
definitions encompass relevant Unicode characters. The underscore 
is consistently treated as alphabetic. Additionally, an identifier 
can include isolated apostrophes or hyphens, given that the subsequent
character is alphabetic.

Directives that start with C<=> can be indented like the code they
interleave, but their initial C<=> must still be the first non-whitespace
character on their line.

An indented Podlite block is considered to have a I<virtual left margin>,
determined by the indentation of its opening delimiter.

In other words, if a directive is indented from the left margin, the
column at which the first character of its opening delimiter appears is
thereafter considered the first column of the entire block's contents.

The virtual margin treats leading tabs as aligning to tabstops spaced 
every C<($?TABSTOP // 8)> characters.

=head2 Podlite blocks

The content of a document is specified within one or more D<blocks|block>.
Every Podlite block may be declared in any of three forms:
I<L<delimited style|#Delimited blocks>>, I<L<paragraph style|#Paragraph
blocks>>, or I<L<abbreviated style|#Abbreviated blocks>>.
All of these forms are equivalent.

Anything in a document that is neither a Podlite directive nor contained
within a Podlite block is treated as "ambient" material. Typically this
would be the source code of the program that the Podlite is documenting. 
Podlite parsers still parse this text into the internal representation of the
file, representing it as a "ambient" block. Renderers
will I<usually> ignore such blocks.
This is the D<default mode|Default mode; parser modes> of the parser.

All directives have a defined terminator and the Podlite parser always reverts to
D<"ambient"|Ambient mode; parser modes> at the end of each Podlite directive or 
block.

The C<=pod> block puts the parser in D<"pod" mode|Pod mode; parser modes>, 
treating all text between blocks as implicit paragraph Podlite, even if 
it's not inside an explicit block.

To keep the parser in "pod" mode, enclose the desired Podlite region 
in a C<=pod> block:

=begin code :allow<B>
  B<=begin pod>

  =head1 A heading

  This is Podlite too. Specifically, this is a simple C<para> block

      $this = pod('also');  # Specifically, a code block

  B<=end pod>
=end code

The contents of files with the extensions C<.podlite> and C<.pod6> are 
implicitly wrapped in a C<=pod> directive.

For C<.md> and C<.markdown> files, the parser operates in D<"Markdown" 
mode|Markdown mode; parser modes> for the entire file, treating all 
text as markdown even if it is not inside an C<=markdown> block.

Any other file extension puts the parser in default mode. The L<C<=include>
block|#Include block > has a mechanism to override this behavior by using 
the C<:mime-type> attribute for the included files.


=head3 Delimited blocks

Delimited blocks are bounded by C<=begin> and C<=end> markers, both of
which are followed by a valid Podlite identifier, which is the
D<typename> of the block. Typenames that are entirely lowercase (for
example: C<=begin head1>) or entirely uppercase (for example: C<=begin
SYNOPSIS>) are reserved.

After the typename, the rest of the C<=begin> marker line is treated as
configuration information for the block. This information is used in
different ways by different types of blocks, but is always specified using
any of:

=for table :nested :caption("Configuration syntax options") :id<configuration_syntax>
 Value is...       Specify with...       Or with...       Or with...
 ===============   ===================   ==============   ======================
 Boolean (true)    C«:key»               C«:key(1)»       C«key => 1»
 Boolean (false)   C«:!key»              C«:key(0)»       C«key => 0»
 String            C«:key<str>»          C«:key('str')»   C«key => 'str'»
 List              C«:key<1 2 3>»        C«:key[1,2,3]»   C«key => [1,2,3]»
 Hash              C«:key{a=>1, b=>2}»                    C«key => {a=>1, b=>2}»

All option keys and values must, of course, be constants since Podlite is a
specification language, not a programming language. Specifically, option
values cannot be closures.

The configuration section may be extended over subsequent lines by
starting those lines with an C<=> in the first (virtual) column followed
by a whitespace character.

The lines following the opening delimiter and configuration are the
data or contents of the block, which continue until the block's matching
C<=end> marker line. For most block types, these contents may be
indented if you wish, without them being treated as L<code blocks|#Code
blocks>. Indented text is only treated as code within
C<=pod>, L<C<=nested>|#Nesting blocks>, L<C<=item>|#Lists>, C<=code>,
and L<semantic|#Semantic blocks> blocks.

The general syntax is:

=begin code :allow< R >
     =begin R<BLOCK_TYPE>  R<OPTIONAL CONFIG INFO>
     =                  R<OPTIONAL EXTRA CONFIG INFO>
     R<BLOCK CONTENTS>
     =end R<BLOCK_TYPE>
=end code

For example:

=begin code
     =begin table  :caption<Table of Contents>
         Constants           1

         Variables           10

         Subroutines         33

         Everything else     57
     =end table

        =begin Name  :required
        =            :width(50)
        The applicant's full name
        =end Name

        =begin Contact  :optional
            The applicant's contact details
        =end Contact
=end code

Note that no blank lines are required around the directives; blank
lines within the contents are always treated as part of the contents.
This is a universal feature of Podlite.

Note also that in the following specifications, a "blank line" is a line
that is either empty or that contains only whitespace characters. That
is, a blank line matches the following pattern: C</^^ \h* $$/>. Podlite uses
blank lines as delimiters, rather than empty lines, to minimize unpleasant
surprises when stray spaces or tabs mysteriously turn up in hitherto
empty lines.


=head3 Paragraph blocks

Paragraph blocks are introduced by a C<=for> marker and terminated by
the next Podlite directive or the first blank line (which is I<not>
considered to be part of the block's contents). The C<=for> marker is
followed by the name of the block and optional configuration
information. The general syntax is:

=begin code :allow< R >
     =for R<BLOCK_TYPE>  R<OPTIONAL CONFIG INFO>
     =                R<OPTIONAL EXTRA CONFIG INFO>
     R<BLOCK DATA>
=end code

For example:

=begin code
     =for table  :caption<Table of Contents>
         Constants           1
         Variables           10
         Subroutines         33
         Everything else     57

        =for Name  :required
        =          :width(50)
        The applicant's full name

     =for Contact  :optional
        The applicant's contact details

=end code


=head3 Abbreviated blocks

Abbreviated blocks are introduced by an C<'='> sign in the
first column, which is followed immediately by the typename of the
block. The rest of the line is treated as block data, rather than as
configuration. The content terminates at the next Podlite directive or the
first blank line (which is not part of the block data). The general
syntax is:

=begin code :allow< R >
     =R<BLOCK_TYPE>  R<BLOCK DATA>
     R<MORE BLOCK DATA>

=end code

For example:

=begin code
     =table
         Constants           1
         Variables           10
         Subroutines         33
         Everything else     57

        =Name  The applicant's full name
     =Contact  The applicant's contact details

=end code

Note that abbreviated blocks cannot specify configuration information. If
configuration is required, use a C<=for> or C<=begin>/C<=end> instead.


=head3 Block equivalence

The underlying documentation model treats all block
specifications (delimited, paragraph, and abbreviated) the same way.
It is possible to choose the form is most convenient for a particular
documentation task. In the descriptions that follow, the abbreviated
form will generally be used, but should be read as standing for all
three forms equally.

For example, although L<#Headings> shows only:

=begin code
  =head1 Top Level Heading
=end code

this automatically implies that you could also write that block as:

=begin code
  =for head1
  Top Level Heading
=end code

or:

=begin code
  =begin head1
  Top Level Heading
  =end head1
=end code


=head3 Standard configuration options

Podlite predefines a small number of standard configuration options that can be
applied uniformly to any built-in block type. These include:

=begin defn
C<:caption>

This option specifies that the block may be given an associated description or
title using the C<:caption> option.

Usually, this description uses for build L<table of contents|#Table of contents>.

=end defn

=begin defn
C<:id>

This option allows to explicitly define identificator for blocks and use 
those IDs for linking, rather than relying on it content (see L<#Links>).

=end defn

=begin defn
C<:nested>

This option specifies that the block is to be nested within its current
context. For example, nesting might be applied to block quotes, to textual
examples, or to commentaries. In addition the L<C<=code>|#Code blocks>,
L<C<=item>|#Lists>, L<C<=input>|#I/O blocks>, and L<C<=output>|#I/O blocks>
blocks all have implicit nesting.

Nesting of blocks is usually rendered by adding extra indentation to the
block contents, but may also be indicated in other ways:
by boxing the contents, by changing the font or size of the nested text,
or even by folding the text (so long as a visible placeholder is provided).

Occasionally it is desirable to nest content by more than one level:

=begin code
    =begin para :nested
    =begin para :nested
    =begin para :nested
    "We're going deep, deep, I<deep> undercover!"
    =end para
    =end para
    =end para
=end code

This can be simplified by giving the C<:nested> option a positive integer
value:

=begin code :allow<B>
    =begin para B<:nested(3)>
    "We're going deep, deep, I<deep> undercover!"
    =end para
=end code

You can also give the option a value of zero, to defeat any implicit
nesting that might normally be applied to a paragraph. For example, to
specify a block of code that should appear I<without> its usual
nesting:

=begin code :allow<B V>
    =comment Don't nest this code block in the usual way...
    B<=begin code :nested(0)>

                 1         2         3         4         5         6
        123456789012345678901234567890123456789012345678901234567890
        |------|-----------------------|---------------------------|
          line        instruction                comments
         number           code

    V<=end code>
=end code

Note that C<:!nested> could also be used for this purpose:

=begin code
    =Z<>begin code :!nested
=end code

=end defn

=begin defn
C<:numbered>

This option specifies that the block is to be numbered. The most common
use of this option is to create L<numbered headings|#Numbered headings> and
L<ordered lists|#Ordered lists>, but it can be applied to any block.

The numbering conventions for headings and lists are specified in those
sections, but it is up to individual renderers to decide how to display
any numbering associated with other types of blocks.

Note that numbering is never explicit; it is always implied by context.

=end defn

=begin defn
C<:checked>

This attribute indicates that a checkbox should be added to that block. 
It possible to apply a C<:checked> attributes to any block.
The most common use of this option is to create L<task lists|#Task lists>.

For unchecked checkbox the C<:!checked> is used.

The task list item marker (checkbox) is added to the output. 
In an HTML output, this would be represented as an 
 C<<input type="checkbox">> element.

The specification does not define how these checkboxes are interacted with.
Implementors are free to choose whether they render them as disabled,
unchangeable elements, or handle dynamic interactions like checking and unchecking
in the final rendered document.

=end defn

=begin defn
C<:folded>

This option specifies whether the block is foldable and, if specified,
whether it should be collapsed or expanded by default. This feature is
useful in managing the length of documents and focusing the reader's
attention on certain sections as needed.

A C<:!folded> or C<:folded(0)> expands the callout by default, and a 
C<:folded> or C<:folded(1)> collapses it instead.

=begin code :allow<B> 
  =for table B<:folded> :caption('Culinary Techniques for Sustainability')
    Sous-vide   Low energy consumption
    ----------  -------------------------
    Steaming    Preserves nutrients
    Baking      Efficient for batch cooking
=end code

When applied to a block element, such as a heading, the attribute typically
affects all headings with lower-level content, creating a hierarchical
folding effect.

For example:

=begin code :allow<B>
  =for B<head2 :folded>
  Green Energy Overview 
=end code

=begin comment
TODO: my be it may sense to add a C<:folded-caption> attribute to 
define a custom title for the collapsed block.

The C<:folded-caption> attribute allows for defining a custom title 
for the collapsed block. If no caption is provided, rendering systems
may automatically use the C<:caption> attribute. If the C<:caption> 
attribute is not present, the first line or paragraph of the block 
is used as the default title. For semantic blocks, the name of the
block can be used as the default title.


=begin code
    =picture :folded(1) :folded-caption("Wind Turbine Fields")
    Images/wind_turbines.jpg
    Wind turbines stand tall against the sky, harnessing
    the power of the wind to generate energy 
=end code
=end comment
=end defn

=begin defn
C<:lang>

This option used to L<provide information|#Assign programming language to code blocks> about the programming language
used in a specific code block. This helps in ensuring that the code is 
displayed and interpreted correctly by rendering engines or syntax highlighters.

Here's a table that lists a few programming languages along with their possible 
values for the C<:lang> attribute:

=begin table :caption("Matching languages and lang attribute values")

    Programming language        Possible C<:lang> values 

    C++                          cpp                    
    CSS                          css                    
    HTML                         html                   
    Java                         java                   
    JavaScript                   javascript             
    Python                       python                 
    Raku                         raku                   

=end table

If the language is not specified, the default language is used based 
on the file extension or mime type of the current document.

=end defn

=begin defn
C<:allow>

This option expects a list of markup codes that are to be recognized
within any C<V<>> codes that appear in (or are implicitly applied to)
the current block. The option is most often used on C<=code> blocks to
allow mark-up within those otherwise verbatim blocks, though it can be
used in I<any> block that contains verbatim text. See L<#Formatting
within code blocks>.

=end defn

=head2 Selectors

Selectors consist of patterns that help identify and filter specific blocks
within documents. Each pattern contains optional source of blocks and block names.

The general syntax is:

=begin code :allow< R >
R<EXTERNAL_SOURCE>
or
[ R<EXTERNAL_SOURCE> | ] R<BLOCKS_SELECTOR>
=end code

...where

=item EXTERNAL_SOURCE - optional source of blocks for filtering, default current document,
=item BLOCK_SELECTOR - list of block names, filter for

For example:

=begin table :nested

    Selector                                        Description
    _______________________________________         ___________________________________________________
    head1, head2, item1                             all head1, head2 and item1 blocks from document

    file:article.pod6 | head1, head2                all head1 and head2 blocks from article.pod6 file

    file:./includes/*.pod6 | head1, head2           all head1 and head2 blocks from pod6 files placed 
                                                    in includes directory

    doc:Data::Dumper | code                         all code blocks from a module documentation

    file:/docs/**/*.md | head1                      search headers with first level for all ".md" files 
                                                    within the "docs" directory and its subdirectories.
=end table

Please note that while the Selector blocks provide a way to query and filter specific elements 
within Markdown files, Markdown itself doesn't have formal named blocks like the Podlite syntax. 
Instead, Markdown uses a lightweight markup to structure content. The above table provides a mapping
between Podlite block names and their corresponding Markdown elements.

=begin table :nested :caption("A table of correspondences for some Podlite blocks and markdown blocks")

    Podlite                                             Markdown                Describtion
    _______________________________________         ______________          _____________________________________
    C<=head1>, C<=head2>, ...                                 #, ##, ...            Heading level 1,2...

    C<=nested>                                          ">"                      blockquote

    C<=para>                                            block of text          paragraph

    C<N<>>                                               [^1]: footnote.       footnote

    C<=Html>                                            <span>text<span>       HTML block
    
    C<O<text>>                                         ~~text~~               Strikethrough, "O for Overstrike"

    C<H<text>>                                         ^text^                 Superscript, "H for High text"

    C<J<text>>                                          ~text~                 Subscript, "J for Junior text"

    C<F<>>, C<=formula>                              $,$$, ```math             Mathematical formulas 

=end table

The most common use of Selectors is to create L<table of contents|#Table of contents> and
in L<include block|#Include block>.

=head2 Block types

Podlite offers notations for specifying a wide range of standard block types...


=head3 Headings

Podlite provides an unlimited number of levels of heading, specified by the
C<=head>R<N> block marker. For example:

=begin code
  =head1 A Top Level Heading

    =head2 A Second Level Heading

      =head3 A third level heading

            =head86 A "Missed it by I<that> much!" heading
=end code

While Podlite parsers are required to recognize and distinguish all levels
of heading, Podlite renderers are only required to provide distinct
I<renderings> of the first four levels of heading (though they may, of
course, provide more than that). Headings at levels without distinct
renderings would typically be rendered like the lowest distinctly
rendered level.


=head4 Numbered headings

You can specify that a heading is numbered using the C<:numbered> option. For
example:

=begin code
  =for head1 :numbered
  The Problem
  
  =for head1 :numbered
  The Solution
  
      =for head2 :numbered
      Analysis
  
          =for head3
          Overview
  
          =for head3
          Details
  
      =for head2 :numbered
      Design
  
  =for head1 :numbered
  The Implementation
=end code

which would produce:

=begin nested
1. The Problem

2. The Solution

=begin nested
2.1. Analysis

=begin nested
Overview

Details
=end nested

2.2: Design
=end nested

3. The Implementation
=end nested

It is usually better to preset a numbering scheme for each heading
level, in a series of L<configuration blocks|#Block pre-configuration>:

=begin code :allow<B Z>
  B<=config head1 :numbered
  Z<>=config head2 :numbered
  Z<>=config head3 :!numbered>
  
  =head1 The Problem
  =head1 The Solution
  =head2   Analysis
  =head3     Overview
  =head3     Details
  =head2   Design
  =head1 The Implementation
=end code

Alternatively, as a short-hand, if the first whitespace-delimited word
in a heading consists of a single literal C<#> character, the C<#> is
removed and the heading is treated as if it had a C<:numbered> option:

=begin code
  =head1 # The Problem
  =head1 # The Solution
  =head2   # Analysis
  =head3       Overview
  =head3       Details
  =head2   # Design
  =head1 # The Implementation
=end code

Note that, even though renderers are not required to distinctly render
more than the first four levels of heading, they I<are> required to
correctly honour arbitrarily nested numberings. That is:

=begin code
    =head6 # The Rescue of the Kobayashi Maru
=end code

should produce something like:

=nested
B<2.3.8.6.1.9. The Rescue of the Kobayashi Maru>


=head3 Ordinary paragraph blocks

Ordinary paragraph blocks consist of text that is to be formatted into
a document at the current level of nesting, with whitespace
squeezed, lines filled, and any special L<inline mark-up|#Markup codes>
applied.

Ordinary paragraphs consist of one or more consecutive lines of text,
each of which starts with a non-whitespace character at (virtual) column
1. The paragraph is terminated by the first blank line or block
directive. For example:

=begin code
  =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

Within a C<=pod>, C<=item>, C<=defn>, C<=nested>, or
L<semantic|#Semantic blocks> block, ordinary paragraphs do not require
an explicit marker or delimiters, but there is also an explicit C<para>
marker (which may be used anywhere):

=begin code :allow<B>
  B<=para>
  This is an ordinary paragraph.
  Its text  will   be     squeezed     and
  short lines filled.
=end code

and likewise the longer C<=for> and C<=begin>/C<=end> forms. For example:

=begin code :allow<B>
  B<=begin para>
    This is an ordinary paragraph.
    Its text  will   be     squeezed     and
    short lines filled.
    
    This is I<still> part of the same paragraph,
    which continues until an...
  B<=end para>
=end code

As the previous example implies, when any form of explicit C<=para> block
is used, any whitespace at the start of each line is removed during rendering.
In addition, within a delimited C<=begin para>/C<=end para> block, any
blank lines are preserved.


=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 without recognizing any inline markup
codes. Code blocks also have an implicit L<nesting|#Nesting blocks>
associated with them. Typically these blocks are used to show examples
of code, mark-up, or other textual specifications, and are 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.
For example:

=begin code
  This ordinary paragraph introduces a code block:

    $this = 1 * code('block');
    $which.is_specified(:by<indenting>);
=end code

Implicit code blocks may only be used within C<=pod>, C<=item>, C<=defn>,
C<=nested>, or L<semantic|#Semantic blocks> blocks.

There is also an explicit C<=code> block (which can be specified within
I<any> other block type, not just C<=pod>, C<=item>, etc.):

=begin code :allow<B>
  The C<loud_update()> subroutine adds feedback:

    B<=begin code>

    sub loud_update ($who, $status) {
        say "$who -> $status";

        silent_update($who, $status);
    }

    B<=end code>
=end code

As the previous example demonstrates, within an explicit C<=code> block
the code 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.


=head4 Formatting within code blocks

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

You can specify a list of markup codes 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 codes. Those codes will then remain active inside the
code block. For example:

=begin code
  =begin code :allow< B R >
  sub demo {
      B<say> 'Hello R<name>';
  }
  =end code
=end code

would be rendered:

=begin code :allow< B R >
  sub demo {
      B<say> 'Hello R<name>';
  }
=end code

Note that the use of the C<:allow> option also makes it possible
for verbatim L<markup codes|#Markup codes> (such as C<C<>>
and C<V<>>) to L<contain other codes as well|#Pre-configuring markup codes>.

=head4 Assign programming language to code blocks

The C<:lang> attribute will be used to provide information about the 
programming language used in a particular block of code. This helps
in ensuring that the code is correctly rendered and interpreted by the
renderers or syntax highlighting tools.

For example:

=begin code :allow<B>
  =begin code B<:lang<raku>>
  sub demo {
     say 'Hello R<name>';
  }
  =end code
=end code 


=head3 I/O blocks

Podlite also provides blocks for specifying the input and output of programs.

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

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

Note that, like C<=code> blocks, both C<=input> and C<=output> blocks have an
implicit level of nesting. They are also like C<=code> blocks in that they
are typically rendered in a fixed-width font, though ideally all three blocks
would be rendered in distinct font/weight combinations (for example: regular
serifed for code, bold sans-serif for input, and regular sans-serif for
output).

Unlike C<=code> blocks, both C<=input> and C<=output> blocks honour any
nested markup codes. This is particularly useful since a sample of
input will often include prompts (which are, of course, output).
Likewise a sample of output may contain the occasional interactive
component. Podlite provides L<special markup codes|#Example specifiers>
(C<K<>> and C<T<>>) to indicate embedded input or output, so you can use
the block type that indicates the overall purpose of the sample (i.e. is
it demonstrating an input operation or an output sequence?) and then use
the "contrasting" markup code within the block.

For example, to include a small amount of input in a sample of output
you could use the C<K<>> markup code:

=begin code :allow<B>
  =begin output
      Name:    Baracus, B.A.
      Rank:    Sgt
      Serial:  1PTDF007
  
      Do you want additional personnel details? B<K<y>>
  
      Height:  180cm/5'11"
      Weight:  104kg/230lb
      Age:     49
  
      Print? B<K<n>>
  =end output
=end code


=head3 Lists

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

=begin code
  The seven suspects are:
  
  =item  Happy
  =item  Dopey
  =item  Sleepy
  =item  Bashful
  =item  Sneezy
  =item  Grumpy
  =item  Keyser Soze
=end code

List items have one implicit level of nesting:

=begin nested
The seven suspects are:

=item  Happy
=item  Dopey
=item  Sleepy
=item  Bashful
=item  Sneezy
=item  Grumpy
=item  Keyser Soze
=end nested

Lists may be multi-level, with items at each level specified using the
C<=item1>, C<=item2>, C<=item3>, etc. blocks. Note that C<=item> is just
an abbreviation for C<=item1>. For example:

=begin code
  =item1  Animal
  =item2     Vertebrate
  =item2     Invertebrate
  
  =item1  Phase
  =item2     Solid
  =item2     Liquid
  =item2     Gas
  =item2     Chocolate
=end code

which would be rendered something like:

=for para :nested
E<bull> Animal
=for para :nested(2)
E<ndash> Vertebrate
=for para :nested(2)
E<ndash> Invertebrate

=for para :nested
E<bull> Phase
=for para :nested(2)
E<ndash> Solid
=for para :nested(2)
E<ndash> Liquid
=for para :nested(2)
E<ndash> Gas
=for para :nested(2)
E<ndash> Chocolate

Podlite parsers must issue a warning if a "level-R<N+1>" C<=item> block
(e.g. an C<=item2>, C<=item3>, etc.) appears anywhere except where there
is a preceding "level-R<N>" C<=item> in the same surrounding block. That
is, an C<=item3> should only be specified if an C<=item2> appears
somewhere before it, and that C<=item2> should itself only appear if
there is a preceding C<=item1>.

Note that item blocks within the same list are not physically nested.
That is, lower-level items should I<not> be specified inside
higher-level items:

=begin code
    =comment WRONG...
    =begin item1          --------------
    The choices are:                    |
    =item2 Liberty        ==< Level 2   |==<  Level 1
    =item2 Death          ==< Level 2   |
    =item2 Beer           ==< Level 2   |
    =end item1            --------------
=end code

=begin code
    =comment CORRECT...
    =begin item1          ---------------
    The choices are:                     |==< Level 1
    =end item1            ---------------
    =item2 Liberty        ==================< Level 2
    =item2 Death          ==================< Level 2
    =item2 Beer           ==================< Level 2
=end code


=head4 Ordered lists

An item is part of an ordered list if the item has a C<:numbered>
configuration option:

=begin code
     =for item1 :numbered
     Visito

     =for item2 :numbered
     Veni

     =for item2 :numbered
     Vidi

     =for item2 :numbered
     Vici
=end code

This would produce something like:

=begin nested
1. Visito

=begin nested
1.1. Veni

1.2. Vidi

1.3. Vici
=end nested
=end nested

although the numbering scheme is entirely at the discretion of the
renderer, so it might equally well be rendered:

=begin nested
1. Visito

=begin nested
1a. Veni

1b. Vidi

1c. Vici
=end nested
=end nested

or even:

=begin nested
A: Visito

=begin nested
E<nbsp;nbsp>(i) Veni

E<nbsp>(ii) Vidi

(iii) Vici
=end nested
=end nested

Alternatively, if the first word of the item consists of a single C<#>
character, the item is treated as having a C<:numbered> option:

=begin code
     =item1  # Visito
     =item2     # Veni
     =item2     # Vidi
     =item2     # Vici
=end code

To specify an I<unnumbered> list item that starts with a literal C<#>, either
make the octothorpe verbatim:

=begin code :allow<B>
    =item B<V<#>> introduces a comment
=end code

or explicitly mark the item itself as being unnumbered:

=begin code :allow<B>
    =for item B<:!numbered>
    # introduces a comment
=end code

The numbering of successive C<=item1> list items increments
automatically, but is reset to 1 whenever any other kind of non-ambient
Podlite block appears between two C<=item1> blocks. For example:

=begin code
    The options are:

    =item1 # Liberty
    =item1 # Death
    =item1 # Beer

    The tools are:

    =item1 # Revolution
    =item1 # Deep-fried peanut butter sandwich
    =item1 # Keg
=end code

would produce:

=begin nested
The options are:

=begin nested
=para 1. Liberty
=para 2. Death
=para 3. Beer
=end nested

The tools are:

=begin nested
=para 1. Revolution
=para 2. Deep-fried peanut butter sandwich
=para 3. Keg
=end nested
=end nested

The numbering of nested items (C<=item2>, C<=item3>, etc.) only resets
(to 1) when the higher-level item's numbering either resets or increments.

To prevent a numbered C<=item1> from resetting after a non-item block,
you can specify the C<:continued> option:

=begin code :allow<B>
     =for item1
     # Retreat to remote Himalayan monastery

     =for item1
     # Learn the hidden mysteries of space and time

     I<????>

     =for item1 B<:continued>
     # Prophet!
=end code

which produces:

=begin nested
=para 1. Retreat to remote Himalayan monastery
=para 2. Learn the hidden mysteries of space and time
=para I<????>
=para 3. Prophet!
=end nested

=head4 Task lists

In addition to the ordered list Podlite also supports 
task lists, which are commonly known as checklists or to-do lists.

To create a task list item just apply a C<:checked>
attribute to C<=item> block.

=begin code :allow<B> 
 =for item B<:checked>
 Buy groceries
 =for item B<:!checked>
 Clean the garage
=end code

The rendered output looks like this:

 [X] Buy groceries
 [ ] Clean the garage

Alternatively, if item content starts with brackets with space (C<[ ]>)
the item is treated as having a C<:!checked> attribute.
To select a checkbox, add an C<x> in between the brackets (C<[x]>). it eqvivalent
of C<:checked> attribute.

For example:
=begin code :allow<B> 
 =item B<[x]> Buy groceries
 =itme B<[ ]> Clean the garage 
=end code

It possiible to create multilevel to-do lists, which permits the 
inclusion of various task levels or sub-tasks.
Here's an example:

=begin code :allow<B> 
 B<=item1> [ ] Work
   B<=item2> [ ] Prepare the presentation
   =item2 [x] Send emails
 =item1 [ ] Home
   =item2 [ ] Vacuum the living room
   =item2 [ ] Water the plants
=end code

=head4 Unordered lists

List items that are not C<:numbered> or C<:checked> are treated as defining unordered
lists. Typically, such lists are rendered with bullets. For example:

=begin code
    =item1 Reading
    =item2 Writing
    =item3 'Rithmetic
=end code

might be rendered:

=for para :nested(1)
E<bull;nbsp;nbsp>Reading
=for para :nested(2)
E<mdash;nbsp;nbsp>Writing
=for para :nested(3)
E<curren;nbsp;nbsp>'Rithmetic

As with numbering styles, the bulletting strategy used for different levels
within a nested list is entirely up to the renderer.


=head4 Multi-paragraph list items

Use the delimited form of the C<=item> block to specify items that
contain multiple paragraphs. For example:

=begin code
     Let's consider two common proverbs:

     =begin item :numbered
     I<The rain in Spain falls mainly on the plain.>

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

     =begin item :numbered
     I<The early bird gets the worm.>

     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

which produces:

=begin nested
=config item :numbered
Let's consider two common proverbs:

=begin item
I<The rain in Spain falls mainly on the plain.>

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<The early bird gets the worm.>

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


=head4 Definition lists

To create term/definition lists, use a C<=defn> block. This is
similar in effect to an C<=item> block, in that a series of C<=defn>
blocks implicitly defines a list (but which might then be rendered into
HTML using C«<DL>...</DL>» tags, rather than C«<UL>...</UL>» tags)

The first non-blank line of content is treated as a term being defined,
and the remaining content is treated as the definition for the term.
For example:

=begin code
    =defn  MAD
    Affected with a high degree of intellectual independence.

    =defn  MEEKNESS
    Uncommon patience in planning a revenge that is worth while.

    =defn
    MORAL
    Conforming to a local and mutable standard of right.
    Having the quality of general expediency.
=end code

Like other kinds of list items, definitions can be numbered, using either an
option or a leading C<#>:

=begin code :allow<B>
    =for defn B<:numbered>
    SELFISH
    Devoid of consideration for the selfishness of others.

    =defn B<#> SUCCESS
    The one unpardonable sin against one's fellows.
=end code


=head3 Nesting blocks

Any block can be nested by specifying a C<:nested> option on it:

=begin code :allow<B>
    =begin para B<:nested>
        We are all of us in the gutter,E<NL>
        but some of us are looking at the stars!
    =end para
=end code

However, qualifying each nested paragraph individually quickly becomes
tedious if there are many in a sequence, or if multiple levels of
nesting are required:

=begin code :allow<B>
    =begin para B<:nested>
        We are all of us in the gutter,E<NL>
        but some of us are looking at the stars!
    =end para
    =begin para B<:nested(2)>
            -- Oscar Wilde
    =end para
=end code

So Podlite provides a C<=nested> block that marks all its contents as being
nested:

=begin code :allow<B>
    B<=begin nested>
    We are all of us in the gutter,E<NL>
    but some of us are looking at the stars!
        B<=begin nested>
        -- Oscar Wilde
        B<=end nested>
    B<=end nested>
=end code

Nesting blocks can contain any other kind of block, including implicit
paragraph and code blocks. Note that the relative physical indentation
of the blocks plays no role in determining their ultimate nesting.
The preceding example could equally have been specified:

=begin code :allow<B>
    B<=begin nested>
    We are all of us in the gutter,E<NL>
    but some of us are looking at the stars!
    B<=begin nested>
    -- Oscar Wilde
    B<=end nested>
    B<=end nested>
=end code


=head3 Tables

Simple tables can be specified in Podlite using a C<=table> block.
The table may be given an associated description or title using the
C<:caption> option.

Columns are separated by two or more consecutive whitespace characters
(double-space),
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
(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<every> 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 have the same number
of cells.

This means you can create tables compactly, line-by-line:

=begin code
    =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

With header:

=begin code
 =begin table

    Directive           Specifies
    _________           ____________________________________________________
    C<=begin>           Start of an explicitly terminated block
    C<=config>          Lexical modifications to a block or markup code
    
 =end table
=end code

Or:

=begin code
 =begin table

    Energy Source                Benefit

    Solar power                  Reduces electricity bills
    Wind energy                  Clean power source
    Hydroelectric power          Highly efficient
    Geothermal energy            Low emissions
    Biomass                      Reduces waste

=end table
=end code

or line-by-line with multi-line headers:

=begin code
    =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<and> multi-line data:

=begin code
    =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

=head4 Advanced Table Format

Tables may construct using C<=row> and C<=cell> blocks.
The C<=row> blocks represent individual rows within the table.

The C<=cell> blocks exist within rows and contain the actual content of the table.
These cells can contain text, data, or other blocks.

=begin code 
  =begin table

  =begin row
    =cell Fruits
    =cell Bananas
    =cell Yellow and ripe
  =end row

  =begin row
    =cell Vegetables
    =cell Carrots
    =begin cell
     =para Crunchy and orange
    =end cell
  =end row

  =end table
=end code

Each C<=row> block may have an optional C<:header> attribute, designating
it as a header row. Header rows typically contain labels or titles
for columns and are visually distinct.


=begin code :allow<B>
  =begin table

  =begin row B<:header>
    =cell Category
    =cell Product
    =cell Description
  =end row

  =begin row
    =cell Fruits
    =cell Bananas
    =cell Yellow and ripe
  =end row

  =begin row
    =cell Vegetables
    =cell Carrots
    =cell Crunchy and orange
  =end row
  
  =end table
=end code

The C<=cell> blocks can also have two important attributes:

=begin defn
C<:colspan>

This attribute specifies the number of columns a cell should span horizontally.
It allows cells to merge and occupy multiple adjacent columns, creating a visually
unified cell.
=end defn

=begin defn
C<:rowspan>

This attribute determines how many rows a cell should span vertically.
Cells with C<:rowspan> can cover multiple rows in a table, creating a vertical merge effect.
=end defn

These example demonstrate how C<:colspan> and C<:rowspan> attributes can be used
to create tables with merged cells, which is especially useful for complex
data structures.

=begin code
    =begin table

    =begin row :header
      =for cell :colspan(2)
      Item and Quantity 
      =cell Description
    =end row

    =begin row
      =cell Apples
      =cell 5
      =for cell :rowspan(2)
      Fruit for snacking
    =end row

    =begin row
      =cell Bananas
      =cell 3
    =end row

    =end table
=end code


It draw somethink like this: 

    ---------------------------------------------------------------
    |         Item and Quantity        |     Description          |
    |----------------------------------|--------------------------|
    |   Apples     |      5            |                          |
    |--------------|-------------------|    Fruit for snacking    |
    |   Bananas    |      3            |                          |
    ---------------------------------------------------------------

Each C<=row> block may only contain C<=cell> blocks or blank lines as delimiters.
All other types of blocks within the C<=row> are implicitly wrapped
by C<=cell> blocks.

For example: 

=begin code

 =begin table

  =begin row :header
    =cell Diagram or Picture
    =cell Description
  =end row

  =begin row
    =picture spacecraft_in_orbit.jpg
    =para
    A vehicle designed for space travel
  =end row

  =begin row
   =Mermaid
       graph TD;
       A[Space Station] --> B[Mars Base]
   
   A space station connected to a Mars base
  =end row
 
 =end table

=end code

=head4 Table from CSV files or data blocks

It is possible to create tables from files or data blocks. 
To do this, use the C<file:> or C<data:> schema in the first non-blank line
to specify the source of the table data.
For example:

=begin code :allow<B>
  =table B<file:recipe_ingredients.csv>
  
  =for table :caption('Basic cake recipe ingredients')
  B<data:recipe_ingredients>

  =begin data B<:key<recipe_ingredients>> :mime-type<text/csv>
    ingredient,quantity,unit
    flour,2,cups
    sugar,1,cups
    eggs,2,items
    butter,0.5,cups
    baking powder,2,teaspoons
  =end data
=end code


=for head3 :id<Custom blocks>
Named or modular custom blocks

D<Blocks|Named block> whose names contain at least one uppercase and one lowercase
letter are assumed to be destined for specialized renderers or parser
plug-ins. For example:

=begin code
    =begin Xhtml
    <object type="video/quicktime" data="onion.mov">
    =end Xhtml
=end code

or:

=begin code
  =Image http://www.perlfoundation.org/images/perl_logo_32x104.png
=end code

=begin nested :notify<note>
Named or modular blocks are defined within separate modules 
and integrated into the core system through a defined interface or API.

The interface or API for external modules depends on the implementation. 
=end nested

Ideally, each named block should have a corresponding handler responsible
for its rendering and processing.

In the absence of a handler for named block, the implementation should 
allow the content to degrade gracefully, ensuring that the core message
or functionality remains accessible even if some advanced features cannot
be rendered. As result, that blocks my be displayed as verbatim or
placeholder content or even not rendered at all.

Alongside the verbatim or placeholder content, the renderer could provide
an unobtrusive yet informative error message, explaining that the named block
could not be processed.

Note that all block names consisting entirely of lowercase or entirely of
uppercase letters are reserved. See L<#Semantic blocks>.

To check custom markup codes, refer to L<#Custom markup codes>. 


=head3 Podlite comments

D<Podlite comments|Podlite comment> refers to Podlite blocks that should not
be displayed by any renderer. However, they are still may be part of the
internal Podlite representation. However, they can still be part of internal
Podlite representation.

Comments are useful for meta-documentation (documenting the documentation):

=begin code
    =comment Add more here about the algorithm
=end code

and for temporarily removing parts of a document:

=begin code :allow<B>
  =item # Retreat to remote Himalayan monastery

  =item # Learn the hidden mysteries of space and time

  =item # Achieve enlightenment

  B<=begin comment>
  =item # Prophet!
  B<=end comment>
=end code


=head3 Data blocks

The C<=data> block is used to embed various types of data directly into a document.

For example, to include a CSV file in a document, it is possible to 
use the following syntax:

=begin code :allow<B>

  =begin data :key<sales_data> :mime-type<text/csv>
    name,month,amount
    John Doe,January,1000
    Jane Doe,February,1500
  =end data

=end code

Each C<=data> block can be given a C<:key> option, to name it. The contents
of any C<=data> block with a key are addressable via
the C<data:> schema. For example:

=begin code :allow<B>
  =begin data B<:key<employee_data>> :mime-type<text/csv>
    id,name,position,department
    1,John Doe,Manager,Marketing
    2,Jane Smith,Developer,Engineering
    3,Bob Brown,Designer,Product
  =end data

  =table B<data:employee_data>

=end code

Each C<=data> block can include several attributes to provide additional information
about the contained data:

=begin defn
C<:filename>

This option specifies the original file name of the embedded data, which 
can be used to hint at the type of data contained if the C<:mime/type> is not 
explicitly provided.
=end defn

=begin defn
C<:mime-type>

This option indicates the MIME type of the data, such as C<image/png> for PNG images,
which helps in determining how the data should be interpretered and processed.

Here is a list of few well-known mime types and their corresponding file extensions:

=table
    MIME Type                      | File Extension
    ------------------             | --------------
    text/plain                     | .txt
    text/markdown                  | .md, .markdown
    text/podlite                   | .podlite, .pod6
    application/json               | .json
    application/xml                | .xml
    image/jpeg                     | .jpg, .jpeg
    image/png                      | .png
    application/pdf                | .pdf
    application/zip                | .zip
    audio/mpeg                     | .mp3
    video/mp4                      | .mp4
    application/msword             | .doc, .docx
    text/csv                       | .csv
    text/tab-separated-values      | .tsv, .tab

=end defn

=begin defn
C<:access-time> and C<:modify-time>

This attributes record time for when the data was last accessed or
edited.

=end defn

=begin defn
C<:encoding>

This option specifies the encoding method used to store the data.
For non-text data, such as images in the PNG format, 
the encoding method C<base64> is used.
=end defn

Example of storing images in C<=data> blocks:

=begin code :allow<B>

  =begin B<data> B<:key<Logo>> :filename<Logo.png> :mime-type<image/png>
  = :access-time<2022-01-01T00:00:00Z>  :modify-time<2022-01-02T10:00:00Z>
  = :encoding<base64>
  iVBORw0KGgoAAAANSUhEUgAAAAMAAAAFCAYAAACAcVaiAAAAS0lEQVR4AWPOPfjpvWZSW4db
  ZLk+kwTHP24HUQYGfi4WTiZVAcYfDtIMDCJc/38xK6TWth37wcrw7cufF8yeeWUGrL8Z33Ey
  /t0HAMBnF2nt5sNRAAAAAElFTkSuQmCC
  =end data

  =picture B<data:Logo>

=end code

In the example above, we have a C<=data> block with C<:id> C<Logo> that stores
the base64-encoded image data. We also specify the filename, mime type,
access time, and edit time as attributes of the C<=data> block.

The image can then be referenced using the `=picture` block with the scheme
C<data:> and the block name C<Logo>.


The C<=data> blocks are just regular Podlite blocks and may appear anywhere
within a source file, and as many times as required.

Note that in Podlite, it is possible to specify C<=data> blocks
I<after> the point in the source where their contents will be used.

C<=data> blocks are never rendered by the standard Podlite renderers.


=head3 Semantic blocks

All uppercase block typenames are reserved for specifying standard
documentation, publishing, source components, or meta-information of a
compunit it needs to be able to be selected for loading.

Standard semantic blocks include:

=begin code
    =NAME
    =AUTHOR
    =VERSION
    =CREATED
    =EMULATES
    =EXCLUDES
    =SYNOPSIS
    =DESCRIPTION
    =USAGE
    =INTERFACE
    =METHOD
    =SUBROUTINE
    =OPTION
    =DIAGNOSTIC
    =ERROR
    =WARNING
    =DEPENDENCY
    =BUG
    =SEE-ALSO
    =ACKNOWLEDGEMENT
    =COPYRIGHT
    =DISCLAIMER
    =LICENCE
    =LICENSE
    =TITLE
    =SECTION
    =CHAPTER
    =APPENDIX
    =TOC
    =INDEX
    =FOREWORD
    =SUMMARY
=end code

The plural forms of each of these keywords are also reserved, and are
aliases for the singular forms.

Most of these blocks would typically be used in their full delimited forms:

=begin code
    =begin SYNOPSIS
        use Magic::Parser;

        my Magic::Parser $parser .= new();

        my $tree = $parser.parse($fh);
    =end SYNOPSIS
=end code

Semantic blocks can be considered to be variants of the C<=head1> block
in most respects (and most renderers will treat them as such). The main
difference is that, in a C<=head1> block, the heading is the contents of
the block; whereas, in a semantic block, the heading is derived from the
typename of the block itself and the block contents are instead treated as
the C<=para> or C<=code> block(s) belonging to the heading.

The use of these special blocks is not required; you can still just write:

=begin code
    =head1 SYNOPSIS
    =begin code :lang<raku>
        use Magic::Parser

        my Magic::Parser $parser .= new();

        my $tree = $parser.parse($fh);
    =end code
=end code

However, using the keywords adds semantic information to the
documentation, which may assist various renderers, summarizers, coverage
tools, document refactorers, and other utilities. This is because a
semantic block I<encloses> the text it controls (unlike a C<=head1>,
which merely precedes its corresponding text), so using semantic blocks
produces a more explicitly structured document.

Note that there is no requirement that semantic blocks be rendered in
a particular way (or at all). Specifically, it is not necessary to
preserve the capitalization of the keyword. For example, the
C<=SYNOPSIS> block of the preceding example might be rendered like so:

=begin nested
B<3.E<nbsp;nbsp>I<Synopsis>>

=begin code :lang<raku>
    use Raku::Magic::Parser;

    my $rep = Raku::Magic::Parser.parse($fh, :all_pod);
=end code
=end nested


=head3 Table of contents

The C<=toc> block is used to make an autogenerated table of contents (TOC)
in a document. The TOC is an index of section titles within the document, 
and its structure is determined by the document's organization. 

The first non-blank line of C<=toc> content is treated as a L<selector|#Selectors>

For example:

=begin code
 =toc head1, head2, head3, item1, item2, table
=end code

or

=begin code
  =toc  head1, head2, head3 
=end code

The TOC is, by default, displayed without a caption.
However, the value assigned to the C<:caption> 
attribute of the C<=toc> block is used to generate a caption for the TOC.

For example:

=begin code :allow<B>
  =for toc B<:caption('Table of contents')>
  head1, head2, head3 
=end code

To build the entries in the TOC, the content of the C<:caption> attribute
within the block is used. If this attribute does not exist, then the text
presentation of the block's content is utilized as the TOC entry.

The depth of the generated TOC is determined by the L<"Selector"|#Selectors> argument.
The selector processed, and headers or filtered blocks that 
allow levels are used to build the TOC levels. If a block does not have an 
associated level, it is rendered at a level one higher than the previous 
block with a level in the TOC.

Note also that all L<semantic blocks|#Semantic
blocks> are treated as equivalent to C<head1> headings, and the
C<=item1>/C<=item> equivalence is preserved.

The C<:folded-levels> attribute indicates which level of the TOC should
be folded. 

=begin code :allow<B>
 =for toc B<:folded-levels[2,3]> :caption('Table of contents')
    head1, head2, item1
=end code

If the C<:folded-levels> attribute is provided with a set 
of key-value pairs, it indicates the folding state of each 
specified level. 

For example: 

=begin code :allow<B>
  =for toc B« :folded-levels< 2=>1, 4 => 1, 3=>0 > »
    head1, head2, head3, item1, item2
=end code

The value C<0> for to level C<3> indicates that this level should 
remain unfolded. Levels C<2> and C<4> are folded.

This allows for a highly customized folding configuration within the TOC.

The TOC is inserted at the location of the C<=toc> block.

To enable the autogenerated TOC, controlled and maintained by render, set the C<:toc>
document attribute for C<=pod> block. In this case, the specific configuration 
and outcome of the TOC are influenced by the settings of the concrete render implementation.


=head3 Include block

The C<=include> block is a powerful tool that allows to reuse specific
parts of documents within project sources. This is particularly handy
when dealing with complex documents that require to include certain 
sections from different files while keeping the overall context and 
structure intact.

The C<=include> block is followed by an L<"Selector"|#Selectors> that specifies the 
content to be included.

In this example, the content of the file C<chapter01.pod6> located in the 
C<./includes> directory is included:

=begin code 
=include file:./includes/chapter01.pod6
=end code

A wildcard L<"Selector"|#Selectors> serves this purpose, enabling inclusion 
of content from all the Markdown files:

=begin code
  =include file:./includes/*.md
=end code

It's possible to include blocks from the same document being worked on.
This feature proves valuable when reusing parts of existing content.

For instance, a semantic block C<=VERSION> can be included as demonstrated:

=begin code :allow<B>
B<=include VERSION>
=VERSION 1.0.0
=end code

or, equivalently:

=begin code
=VERSION 1.0.0
=VERSION 1.0.0
=end code

Podlite detects type of the included file by its extension.
For example, if the included file has a C<.md> extension, 
it is treated as a Markdown file.

To override the type of the included file by extension, you can use the C<:mime-type>
attribute. This attribute allows you to specify the MIME type of the included file.
For example:

=begin code
  =for include :mime-type('text/podlite')
  file:./includes/text.txt 
=end code

The C<:mime-type> attribute is particularly useful when including files with 
extensions that do not match their actual MIME type.

It's crucial to think about security concerns, as adding content from external
sources could potentially create vulnerabilities such as injecting harmful code
or malicious material. Tools responsible for displaying and handling the content
should be able to provide a warning in such situations.


=head3 Inserting pictures
 
Podlite allows to include images using a C<=picture> block with an inline version
represented as C<P<alternative text|source of the image>>:

=begin code :allow<B>
 B<=picture astronaut.png>
 =para In the vast expanse of the cosmos, an intrepid B<P<astronaut|astronaut.png>>
 floats weightlessly above the Earth.
=end code

The first non-blank line of content within the C<=picture> block specifies the
source of the image and the remaining content is treated as caption.

This source can be either local or remote, and it can be
indicated using different schemas: C<https:> for remote images, C<file:> for
local ones, or C<data> for L<embedded images|#Data blocks> in to the document.
If no schema is provided, it defaults to C<file:>.

=begin code :allow<B>
 =picture https://example.com/image.jpg
 =picture file:/local/image.png
 =picture /local/image.png
 =picture ../image.png
 =picture data:Logo
=end code

Following the source line, it possible to include an image caption.

=begin code 
 =picture astronaut.png
 In the vast expanse of the cosmos, an intrepid B<astronaut>
 floats weightlessly above the Earth.
=end code

in delimited form of C<=picture> it possible to include as match texts as needed:

=begin code 
 =begin picture
 astronaut.png
 
 In the vast expanse of the cosmos, an intrepid B<astronaut>
 floats weightlessly above the Earth.

 This astronaut explores the vastness of space.
 
 =end picture
=end code

It possible to use all inline markup codes that are 
supported by L<ordinary paragraph blocks|#Ordinary paragraph blocks>.

Alternatively, you can define the image caption using the C<:caption> attribute.

=begin code :allow<B>
 =for picture B<:caption<diagram>>
 diag01.png
=end code


=head3 Mathematical formulas

To include mathematical formulas, use a C<=formula> block with an inline version
represented as C<F<>>.

To insert mathematical expressions, use LaTeX-style syntax, which is
a commonly used format for writing mathematical equations.

=begin code :allow<B>
  B<=formula>
  x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

  In a right triangle, the length of the hypotenuse can be calculated 
  using the Pythagorean theorem: B<F<a^2 + b^2 = c^2>>.

  Euler's identity, B<F<e^{i\pi} + 1 = 0>>, is a fundamental equation in
  complex analysis.

=end code

It possible to define the formule caption using the C<:caption> attribute.

=begin code :allow<B>
  =formula B< :caption<Quadratic Formula> >
  x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
=end code


=head3 Markdown support

Podlite includes built-in support for Markdown, making it easy to include Markdown
content within Podlite documents. This is achieved using the C<=markdown> block.

=begin code :allow<B>
  B<=begin markdown>

  ## Markdown Example

  You can use all the standard Markdown syntax within this block. For example:

  - *Italic text* using asterisks or underscores: *italic* or _italic_.
  - **Bold text** using double asterisks or underscores: **bold** or __bold__.
  - [Links](https://example.com) with the `[text](url)` syntax.
  - Unordered lists using `-`, `*`, or `+`:

  - Item 1
  - Item 2

  - Ordered lists using numbers:

  1. First item
  2. Second item

  - Code blocks with backticks:

  ```python
  def hello_world():
      print("Hello, World!")
  ```

  - Blockquotes with the `>` symbol:
  
    > This is a blockquote.

  B<=end markdown>
=end code

This block allows to seamlessly combine Podlite's structured blocks with
the flexibility of Markdown.


=head2 Markup codes

Markup codes enable inline markup within the text of (most) Podlite block types.
They are a form of block that can contain only other markup codes. Specifically,
markup codes can nest:

=begin code :allow<B V>
    V<B><I shall say this loudly
    B<Z<and repeatedly>>
    and with emphasis.>
=end code

All Podlite markup codes consist of a single capital letter followed
immediately by a set of angle brackets. The brackets contain the text or
data to which the markup code applies. You can use a set of single
angles (C«<...>»), a set of double angles (C<«...»>), or multiple
single-angles (C«<<<...>>>»).

Within angle delimiters, you cannot use sequences of the same angle
characters that are longer than the delimiters:

=begin code :allow<B>
    =comment
        These are errors...

    C< $fooB«<<»barB«>>» >
    The Perl 5 heredoc syntax was: C< B«<<»END_MARKER >
=end code

You I<can> use sequences of angles that are the same length as
the delimiters, but they must be balanced. For example:

    C<  $foo<bar>   >
    C<< $foo<<bar>> >>

If you need an unbalanced angle, either use different delimiters:

=begin code :allow<B>
    CB<«>$foo < $barB<»>
    The Perl 5 heredoc syntax was: CB<«> <<END_MARKER B<»>
=end code

or delimiters with more consecutive angles than your text contains:

=begin code :allow<B>
    CB«<<»$foo < $barB«>>»
    The Perl 5 heredoc syntax was: CB«<<<» <<END_MARKER B«>>>»
=end code

A markup code ends at the matching closing angle bracket(s), or at
the end of the enclosing block or markup code in which the opening
angle bracket was specified, whichever comes first (this includes paragraph
and abbreviated blocks, ending with blank a line). Podlite parsers are
required to issue a warning whenever a markup code is terminated by
the end of an outer block rather than by its own delimiter (unless the
user explicitly disables the warning).


=head3 Significance indicators

Podlite provides three markup codes that flag their contents with
increasing levels of significance:

=item
The C<U<>> markup code specifies that the contained text is
B<unusual> or distinctive; that it is of I<minor significance>. Typically
such content would be rendered in an underlined style.

=item
The C<I<>> markup code specifies that the contained text is
B<important>; that it is of I<major significance>. Such content would
typically be rendered in italics or in C< <em>...</em> > tags

=item
The C<B<>> markup code specifies that the contained text is the
B<basis> or focus of the surrounding text; that it is of I<fundamental
significance>. Such content would typically be rendered in a bold style or
in C< <strong>...</strong> > tags.


=head3 Mistake marking

It possible strikethrough words using the code C<O<>>, where 'O' stands
for "Overstrike." This is a way to indicate that certain words are a
mistake and should not be included in the document.

 O<The sky is green.> Our planet's sky is usually blue.


=head3 Text positioning

Podlite provides two markup codes that allow positioning characters or words.

=begin item
To create subscript text, you can use the C<J<>> markup code, where 'J' represents 
"Junior text." Subscript positions one or more characters slightly below the normal
line of type.

 HJ<2>O

This code renders as C<H<sub>2</sub>O>, which signifies that the '2' is positioned 
slightly below the baseline, as is often seen in chemical formulas like C<H₂O> (water).
=end item

=begin item
To create superscript text, it possible to use the C<H<>> markup code, where 'H'
stands for "High text." Superscript positions one or more characters slightly
above the normal line of type

 XH<2>

This code renders as C<X<sup>2</sup>>, indicating that the C<'2'> is positioned 
slightly above the baseline. This is commonly used for mathematical exponents, as in C<X²>.
=end item
    

=head3 Definitions

The C<D<>> markup code indicates that the contained text is a
B<definition>, introducing a term that the adjacent text
elucidates. It is the inline equivalent of a C<=defn> block.
For example:

=begin code :allow<B>
    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

A definition may be given synonyms, which are specified after a vertical bar
and separated by semicolons:

=begin code :allow<B>
    A B<D<markup code|markup codes;formatters>> provides a way
    to add inline mark-up to a piece of text.
=end code

A definition would typically be rendered in italics or C< <dfn>...</dfn> >
tags and will often be used as a link target for subsequent instances of the
term (or any of its specified synonyms) within a hypertext.


=head3 Example specifiers

Podlite provides markup codes for specifying inline examples of input,
output, code, and metasyntax:

=begin item
The C<T<>> markup code specifies that the contained text is
B<terminal output>; that is: something that a program might print out.
Such content would typically be rendered in a T<fixed-width font> or with
C< <samp>...</samp> > tags. The contents of a C<T<>> code are always
L<space-preserved | #Space-preserving text> (as if they had an implicit
C<S<...>> around them). The C<T<>> code is the inline equivalent of the
C<=output> block.
=end item

=begin item
The C<K<>> markup code specifies that the contained text is
B<keyboard input>; that is: something that a user might type in. Such
content would typically be rendered in a K<fixed-width font> (preferably a
different font from that used for the C<T<>> markup code) or with
C< <kbd>...</kbd> > tags. The contents of a C<K<>> code are always
L<space-preserved| #Space-preserving text>. The C<K<>> code is the
inline equivalent of the C<=input> block.
=end item

=begin item
The C<C<>> markup code specifies that the contained text is B<code>;
that is, something that might appear in a program or specification. Such
content would typically be rendered in a C<fixed-width font> (preferably
a different font from that used for the C<T<>> or C<K<>> markup
codes) or with C< <code>...</code> > tags. The contents of a C<C<>> code
are L<space-preserved| #Space-preserving text> and L<verbatim| #Verbatim text>.
The C<C<>> code is the inline equivalent of the C<=code> block.

To include other markup codes in a C<C<>> code, you can lexically
L<reconfigure|#Block pre-configuration> it:

=begin code :allow<B>
  =begin para
  B<=config C<> :allow<E I>>
  Raku makes extensive use of the C<B<E<laquo>>> and C<B<E<raquo>>>
  characters, for example, in a hash look-up:
  C<%hashB<I<E<laquo>>>keyB<I<E<raquo>>>>
  =end para
=end code

To enable entities in I<every> C<C<...>> put a C<=config C<> :allow<E>>
at the top of the document
=end item

=begin item
The C<R<>> markup code 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 :allow<B>
  The basic C<ln> command is: C<ln> B<R<source_file> R<target_file>>
=end code

or:

=begin code :allow<B>
  Then enter your details at the prompt:
  =for input
      Name: B<R<your surname>>
        ID: B<R<your employee number>>
      Pass: B<R<your 36-letter password>>
=end code

Typically replaceables would be rendered in R<fixed-width italics> or with
C< <var>...</var> > tags. The font used should be the same as that used for
the C<C<>> code, unless the C<R<>> is inside a C<K<>> or C<T<>> code (or
the equivalent C<=input> or C<=output> blocks), in which case their
respective fonts should be used.
=end item


=head3 Verbatim text

The C<V<>> markup code treats its entire contents as being B<verbatim>,
disregarding every apparent markup code within it. For example:

    The B<V< V<> >> markup code 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 codes surrounding the C<V<>> code
are still applied to its contents. For example the previous example
is rendered:

=nested
The B<V< V<> >> markup code disarms other codes
such as V< I<>, C<>, B<>, and M<> >.

You can prespecify markup codes that remain active within
a C<V<>> code, using the L<C<:allow>|#Formatting within code blocks>
option.


=head3 Inline comments

The C<Z<>> markup code indicates that its contents constitute a
B<zero-width comment>, which should not be rendered by any renderer.
For example:

=begin code :allow<B>
  The "exeunt" command B<Z<Think about renaming this command?>> is used
  to quit all applications.
=end code

In certain scenarios, the C<Z<>> code is used to break up text that 
would otherwise be considered mark-up:
=begin code :allow<B>
  In certain scenarios, the ZB<Z<>><> code is used to break up text that 
  would otherwise be considered mark-up.
=end code

That technique still works, but it's now easier to accomplish the same goal
using a verbatim markup code:

=begin code :allow<B>
  In certain scenarios, the B«V<V<Z<>>>» code is used to break up text that 
  would otherwise be considered mark-up.
=end code

Moreover, the C<C<>> code automatically treats its contents as being
verbatim, which often eliminates the need for the C<V<>> as well:

=begin code :allow<B>
  In certain scenarios, the B«V<C<Z<>>>» code was widely used to break up text
  that would otherwise be considered mark-up.
=end code

The C<Z<>> markup code is the inline equivalent of a
L<C<=comment> block|#Comments>.


=head3 Links

The C<L<>> code is used to specify all kinds of links, filenames, citations,
and cross-references (both internal and external).

A link specification consists of a I<scheme specifier> terminated by a
colon, followed by an I<external address> (in the scheme's preferred
syntax), followed by an I<internal address> (again, in the scheme's syntax).
All three components are optional, though at least one must be present in
any link specification.

Usually, in schemes where an internal address makes sense, it will be
separated from the preceding external address by a C<#>, unless the
particular addressing scheme requires some other syntax. When new
addressing schemes are created specifically for Podlite it is strongly
recommended that C<#> be used to mark the start of internal addresses.

Standard schemes include:

=begin defn
C<http:> and C<https:>

A standard web URL. For example:

=begin code :allow<B>
  This module needs the LAME library
  (available from L<B<http://www.mp3dev.org/mp3/>>)
=end code

If the link does not start with C<//> it is treated as being relative to
the location of the current document:

=begin code :allow<B>
  See also: L<B<http:tutorial/faq.html>> and
  L<B<http:../examples/index.html>>
=end code

=end defn

=begin defn
C<file:>

A filename on the local system. For example:

=begin code :allow<B>
  Next, edit the global config file (that is, either
  L<B<file:/usr/local/lib/.configrc>> or L<B<file:~/.configrc>>).
=end code

Filenames that don't begin with a C</> or a C<~> are relative
to the current document's location:

=begin code :allow<B>
    Then, edit the local config file (that is, either
    L<B<file:.configrc>> or L<B<file:CONFIG/.configrc>>.
=end code

=end defn

=begin defn
C<mailto:>

An email address. Typically, activating this type of link invokes a mailer.
For example:

=begin code :allow<B>
  Please forward bug reports to L<B<mailto:devnull@rt.cpan.org>>
=end code

=end defn

=begin defn
C<man:>

A link to the system manpages. For example:

=begin code :allow<B>
  This module implements the standard
  Unix L<B<man:find(1)>> facilities.
=end code

=end defn

=begin defn
C<doc:>

A link to other documents by utilizing semantic blocks 
such as C<=TITLE> or C<=NAME> as anchor points for these links.

For example:

=begin code :allow<B>
  B<=NAME Dumper>
  
  You may wish to use L<B<doc:Dumper>> to
  view the results.
=end code

Moreover, the C<doc:> scheme allows the use of an C<:id> attribute within
the C<=TITLE> or C<=NAME> blocks to create unique identifiers for document
linking. This ensures precision in navigation, as each identifier
corresponds to a specific part of the document set. An example would be:

=begin code :allow<B>
    =for TITLE :id<Specification>
    The Specification of Podlite
    
    ...
    
    Read the L<spec|doc:Specification>.
    
    ...
=end code

When Podlite processes a link, it can automatically use the document's title
from the C<=TITLE> or C<=NAME> blocks as the display text for the hyperlink if no
explicit text is provided. For example:

=begin code :allow<B>

   =for TITLE :id<Specification>
       The Specification of Podlite

   =para
   Please read "B<L<doc:Specification>>".

=end code

... will be rendered as:

=begin code :allow<B>

 Please read "B<The Specification of Podlite>".

=end code

=end defn

=begin defn
C<defn:>

A link to the L<block-form|#Definition lists> or L<inline|#Definitions>
definition of the specified term within the current document. For example:

=begin code :allow<B>
  He was highly prone to B<D<lexiphania>>: an unfortunate proclivity
  for employing grandiloquisms (for example, words such as "proclivity",
  "grandiloquism", and indeed "lexiphania").

  B<=defn glossoligation>
  Restraint of the tongue (voluntary or otherwise)
=end code

and later, to link back to the definition

=begin code :allow<B>
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

=end defn

=begin defn
C<isbn:> and C<issn:>

The International Standard Book Number or International Standard
Serial Number for a publication. For example:

=begin code :allow<B>
  The Perl Journal was a registered
  serial publication (L<B<issn:1087-903X>>)
=end code

=end defn

To refer to a specific section within a webpage, manpage, or Podlite
document, add the name of that section after the main link, separated by
a C<#>. For example:

=begin code :allow<B>
  Also see: L<man:bash(1)B<#Compound Commands>>,
  L<doc:perlsynB<#For Loops>>, and
  L<http://dev.perl.org/perl6/syn/S04.htmlB<#The_for_statement>>
=end code

To refer to a section of the current document, omit the external address:

=begin code :allow<B>
  This mechanism is described under L<doc:B<#Special Features>> below.
=end code

The scheme name may also be omitted in that case:

=begin code :allow<B>
  This mechanism is described under L<B<#Special Features>> below.
=end code

Podlite include the possibility of assigning a unique identifier to a block.
These identifiers can be explicitly assigned to any blocks using 
the C<:id> attribute. Later, these identifiers are utilized for adressing blocks
and creating links.

=begin code :allow<B>
  =for head1 :id<intro>
  Introduction
  =for para B<:id<id1>>
  This is an introductory paragraph.
  
  For more information, see L<here|B<#intro>> and L<here|B<#id1>>
=end code

In this example, the link reference to the header block identified by "intro"
rather than the name "Introduction" and to the paragrapth block with identifier "id1".

Normally a link is presented as some rendered version of the link
specification itself. However, you can specify an alternate
presentation by prefixing the link with the desired text and a
vertical bar. Whitespace is not significant on either side of the bar.
For example:

=begin code :allow<B>
  This module needs the L<B<LAME library|>http://www.mp3dev.org/mp3/>.

  You could also write the code
  L<B<in Latin |> doc:Lingua::Romana::Perligata>

  His L<B<lexiphanic|>defn:lexiphania>> tendencies were, alas, incurable.
=end code


=head3 Contextual backlinks

Podlite introduces the concept of contextual backward links C<W<>> (or contextual backlinks),
enhancing the traditional L<linking|#Links> mechanism by allowing to not
only reference another location but also provide specific
context around that reference. This context can take the form of opinions,
additional information, or any relevant commentary that enhances the understanding 
of the referenced material.

For example:

=begin code :allow<B>
  This text can reveal the meaning of B<W<glossoligation|defn:glossoligation>>
=end code

or:

=begin code :allow<B>
  We discuss here about B<W<doc:perldata>>.
=end code

Contextual backlinks on the destination page can be displayed in various ways.
They may appear with surrounding text chunks, providing context within
the flow of the content. Alternatively, they can be placed at the end
of the text, in the margin of the page, or highlighted in other visually
distinctive ways.

Like traditional L<links|#Links>, contextual backlinks allows the use of
all available link schemes, including C<https:> and C<doc:>, to link to external content.

Contextual backlinks might be visually distinguished from
standard links through color coding.


=head3 Alias placements

The C<A<>> code is replaced by the contents of the named alias or object
specified within its delimiters.
For example:

=begin code
  =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

See L<#Aliases> for further details of the aliasing macro mechanism.


=head3 Space-preserving text

Any text enclosed in an C<S<>> code is formatted normally, except that
every whitespace character in itE<mdash>including any newlineE<mdash>is
preserved. These characters are also treated as being non-breaking
(except for the newlines, of course). For example:

    The emergency signal is: S<
    dot dot dot   dash dash dash   dot dot dot>.

would be formatted like so:

=nested
The emergency signal is:E<0x85>
dotE<nbsp>dotE<nbsp>dotE<nbsp>E<nbsp>E<nbsp>dashE<nbsp>dashE<nbsp>dashE<nbsp>E<nbsp>E<nbsp>E<nbsp>dotE<nbsp>dotE<nbsp>dot.

rather than:

=nested
The emergency signal is: dot dot dot dash dash dash dot dot dot.


=head3 Entities

To include Unicode code points or HTML5 character references in a
Podlite document, specify the required D<entity|entities> using the C<E<>> code.

If the C<E<>> contains a number, that number is treated as the decimal
Unicode value for the desired code point. For example:

    Podlite makes considerable use of E<171> and E<187>.

You can also use explicit binary, octal, decimal, or hexadecimal numbers:

    Podlite makes considerable use of E<0b10101011> and E<0b10111011>.
    Podlite makes considerable use of E<0o253> and E<0o273>.
    Podlite makes considerable use of E<0d171> and E<0d187>.
    Podlite makes considerable use of E<0xAB> and E<0xBB>.

If the C<E<>> contains anything that is not a number, the contents are
interpreted as a Unicode character name (which is always uppercase), or
else as an HTML5 named character reference. For example:

    Podlite makes considerable use of E<LEFT DOUBLE ANGLE BRACKET>
    and E<RIGHT DOUBLE ANGLE BRACKET>.

or, equivalently:

    Podlite makes considerable use of E<laquo> and E<raquo>.

To include emoji codes, you can use the C<E<>> code along 
with the colon-prefixed and postfix emoji shortname:

    Podlite uses emoji codes to express emotions and actions,
    such as E<:thumbsup:> for approval and E<:smile:> for happiness.

In this example, C<:smile:> and C<:thumbsup:> are emoji codes representing
the respective emojis. You can use any valid emoji code in this format 
to include emojis in your Podlite document.

Note that the specific emoji codes and the emojis they represent may vary
depending on the platform or system you are using. 

Multiple consecutive entities (in any format) can be specified in a
single C<E<>> code, separated by semicolons:

    Podlite makes considerable use of E<LEFT DOUBLE ANGLE BRACKET;hellip;0xBB;:smile:>.


=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<B>
    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<B>
  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<B>
  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<B>
  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<B>
  B<X<|puns, deliberate>>This is called the "Orcish Manoeuvre"
  because you "OR" the "cache".
=end code


=head3 Annotations

Anything enclosed in an C<N<>> code is an inline B<note>.
For example:

=begin code :allow<B>
  Space stations feature hydroponic gardens B<N<Plants grow without soil,
  using mineral nutrient solutions.>>, a necessity for long-term missions.
=end code

Renderers may render such annotations in a variety of ways: as
footnotes, as endnotes, as sidebars, as pop-ups, as tooltips, as
expandable tags, etc. They are never, however, rendered as unmarked
inline text. So the previous example might be rendered as:

=nested
Space stations feature hydroponic gardens E<dagger>, a necessity for 
long-term missions.
and later:

=begin nested
B<Footnotes>

=para
E<dagger> Plants grow without soil, using mineral nutrient solutions.
=end nested


=for head3 :id('Custom markup codes')
Module-defined handler for extends markup features

The C<M<>> code in Podlite extends the language's capabilities by allowing users 
to specify additional processing instructions within their documents. 
This is achieved by combining content text with a custom plug-in specifier, 
followed by optional configuration information that is passed to a handler function.

The structure of the C<M<>> markup code as follows: 

    M< CONTENT-TEXT| R<MODULE_NAME> R<OPTIONAL CONFIG INFO>>

This syntax includes C<CONTENT-TEXT> section, followed by a
name specifier C<MODULE_NAME> and then the C<OPTIONAL CONFIG INFO>
(see L<"Configuration syntax options"|#configuration_syntax>).
The name specifier should follow the same rules as for 
L<named blocks|#Custom blocks>.

The C<M<>> formatting code is the inline equivalent of a
L<named block|#Custom blocks>.

An example of how this code might be used is :

=for code :allow<B>
    B«M<» This text is highlighted in yellow B«|Marker :color('yellow') >».

In this example, the text C<"This text is highlighted in yellow"> is subject
to special handling specified by the C<Marker> module and
C<:color('yellow')>, indicating that the text should be highlighted in yellow.

If the C<MODULE_NAME> is unrecognized, the content text C<CONTENT-TEXT> should be
rendered as ordinary text. This ensures that documents remain readable even 
if specific processing instructions cannot be executed. The renderer could provide
an unobtrusive yet informative error message, explaining that the custom 
markup block could not be processed.


=head2 Block pre-configuration

The C<=config> directive allows you to prespecify standard configuration
information that is applied to every block of a particular type.

=begin code

  =config code     :lang<python> :allow<B>
  =config head1    :numbered
  =config head2    :folded
    
=end code

Here, two configurations are outlined. The first one sets 
the language for code blocks to C<python> and allows bold markup.
The second establishes that all level 1 headings will be numbered.

The general syntax for configuration directives is:

=begin code  :allow< R >
    =config R<BLOCK_TYPE>  R<CONFIG OPTIONS>
    =                   R<OPTIONAL EXTRA CONFIG OPTIONS>
=end code

A C<=config> is a directive, not a block. Hence,
there is no paragraph or delimited form of the C<=config> directive.
Each C<=config> specification is lexically scoped to the surrounding
block or file in which it is specified.

Note that, if a particular block later explicitly specifies a
configuration option with the same key, that option overrides the
pre-configured option. For example, given the code blocks configurations in the
previous example, to specify another language for code block:

=begin code
  =for code :lang<javascript>
  print(JSON.stringify([1,2]]));
=end code


=head3 Pre-configuring markup codes

You can also lexically preconfigure a L<markup code|#Markup codes>,
by naming it with a pair of angles as a suffix. For example:

=begin code :allow<B>
  =comment  Always allow E<> codes in any (implicit or explicit) V<> code...
  B«=config V<>  :allow<E>»
  =comment  All inline code allows I<>
  B«=config C<>  :allow<I>»
=end code

Note that, even though the markup code is named using single-angles,
the preconfiguration applies regardless of the actual delimiters used on
subsequent instances of the code.


=head2 Aliases

The C<=alias> directive provides a way to define lexically scoped
synonyms for longer Podlite sequences, (meta)object declarators from the
code, or even entire chunks of ambient source. These synonyms can then
be inserted into subsequent Podlite using the
L<C<A<> markup code>|#Alias placements>.

Note that C<=alias> is a fundamental Podlite directive, like C<=begin> or
C<=for>; there are no equivalent paragraph or delimited forms.

Macro aliases are lexically scoped to the surrounding Podlite block.

The simplest form of alias takes two arguments. The first is an
identifier (which is usually specified in uppercase, though this is
certainly not mandatory). The second argument consists of one or more
lines of replacement text.

This creates a lexically scoped Podlite macro that can be invoked during
document generation by placing the identifier (i.e. the first argument
of the alias) in an C<A<>> markup code. This markup code is then
replaced by the text returned by new macro.

The replacement text returned by the alias macro begins at the first
non-whitespace character after the alias's identifier, and continues to
the end of the line. You can extend the replacement text over multiple
lines by starting the following line(s) with an C<=> (at the same level
of indentation as the C<=alias> directive itself) followed by at least
one whitespace. Each addition line of replacement text uses the original
line's (virtual) left margin, as specified by the indentation of the
replacement text on the C<=alias> line.

For example:

=begin code
    =alias PROGNAME    Earl Irradiatem Evermore
    =alias VENDOR      4D Kingdoms
    =alias TERMS_URLS  =item L<http://www.4dk.com/eie>
    =                  =item L<http://www.4dk.co.uk/eie.io/>
    =                  =item L<http://www.fordecay.ch/canttouchthis>

    The use of A<PROGNAME> is subject to the terms and conditions
    laid out by A<VENDOR>, as specified at:

        A<TERMS_URLS>

=end code

would produce:

=begin para :nested
    The use of Earl Irradiatem Evermore is subject to the terms and
    conditions laid out by 4D Kingdoms Inc, as specified at:

        =item L<http://www.4dk.com/eie>
        =item L<http://www.4dk.co.uk/eie.io/>
        =item L<http://www.fordecay.ch/canttouchthis>

=end para

The advantage of using aliases is, obviously, that the same alias can be
reused in multiple places in the documentation. Then, if the replacement
text ever has to be changed, it need only be modified in a single place:

=begin code
    =alias PROGNAME    Count Krunchem Constantly
    =alias VENDOR      Last Chance Receivers Intl
    =alias TERMS_URLS  L<http://www.c11.com/generic_conditions>
=end code


=head2 Notification blocks

These blocks, often referred to as admonitions, callouts, or alerts,
serve to draw the reader's attention to different types of content, 
such as tips, warnings, or important notes. 

To create specially formatted blocks to highlight information in Podlite 
the C<=nested> block and C<:notice> attribute are utilized.

For example:

=begin code :allow<B>
    B<=begin nested> B<:notify<tip>>
    Remember to always use oven mitts when handling hot bakeware
    to prevent burns.
    B<=end nested>
=end code

Below is a table that outlines the different types of notification blocks
along with a brief description of each type.

=begin table :caption<"Types of Notification blocks">
    
    Type          Description
    ----------    ------------------------------------------------------
    note          Provides additional information and context without
                  interrupting the flow of the main content
                  
    tip           Offers advice for doing things better or more easily
    
    important     Signifies that the information is crucial for 
                  understanding or success
    
    warning       Indicates urgent information that requires immediate 
                  attention to avoid potential problems
    
    caution       Advises readers about potential negative outcomes or 
                  risks associated with certain actions

=end table

=begin comment
TODO:
custom (e.g. `faq`, etc.)???       Allows for specifying the specific context or content.

    =begin nested :caption<"Foldable FAQ: Question 1"> :notice<faq> :folded
    This is how you make content foldable for a cleaner look.
    =end nested

=end comment

By default, the title of the notification block is its type identifier in title case.
It is possible to customize the title of the block and control the visibility 
of the information using the C<:caption> and C<:folded> options.

=begin code :allow<I B Z> 
  =begin nested B<:caption<"Astronaut's Reminder">> :notify<important> B<:folded>
    Space missions require meticulous planning and adherence to safety protocols.
    Neglecting these can lead to mission failure or, worse, endanger lives.
  =end nested
=end code

It is possible to create title-only callouts by omitting the body.

=begin code 
  =for nested :notify<important> :folded :caption<"Title-only callout">
=end code

Notification blocks are displayed with distinctive colors and 
icons that indicate the significance of the content.

=begin SUMMARY

=head2 Directives
=begin table :nested

    Directive           Specifies
    _________           ____________________________________________________
    C<=begin>           Start of an explicitly terminated block
    C<=config>          Lexical modifications to a block or markup code
    C<=end>             Explicit termination of a C<=begin> block
    C<=for>             Start of an implicitly (blank-line) terminated block
    C<=alias>           Define a Podlite macro

=end table


=head2 Blocks
=begin table :nested

    Block typename      Specifies
    _______________     ____________________________________________________
    C<=code>            Verbatim pre-formatted sample source code
    C<=comment>         Content to be ignored by all renderers
    C<=defn>            Definition of a term
    C<=head>R<N>        I<N>th-level heading
    C<=input>           Pre-formatted sample input
    C<=item>            First-level list item
    C<=item>R<N>        I<N>th-level list item
    C<=nested>          Nest block contents within the current context
    C<=output>          Pre-formatted sample output
    C<=para>            Ordinary paragraph
    C<=pod>             No "ambient" blocks inside
    C<=table>           Simple rectangular table
    C<=data>            Data section
    C<=toc>             Autogenerated table of contents 
    C<=include>         Include other blocks, documents
    C<=picture>         Inserting pictures
    C<=formula>         Mathematical formulas
    C<=markdown>        Markdown support
    C<=>R<RESERVED>     Semantic blocks (C<=SYNOPSIS>, C<=BUGS>, etc.)
    C<=>R<Typename>     User-defined block

=end table

=head2 Inline markup codes
=config C<> :allow<R V>
=begin table :nested

    Formatting code       Specifies
    ___________________   ___________________________________________________
    C<A<...>>             Replaced by contents of specified macro/object
    C<B<...>>             Basis/focus of sentence (typically rendered bold)
    C<C<...>>             Code (typically rendered fixed-width)
    C<D<...|...;...>>     Definition (C<D<R<defined term>|R<synonym>;R<synonym>;...>>)
    C<E<...;...>>         Entity names or numeric codepoints (C<E<R<entity1>;R<entity2>;...>>), emoji
    C<F<...>>             Mathematical formula
    C<G<...>>             reserved
    C<H<...>>             Superscript
    C<I<...>>             Important (typically rendered in italics)
    C<J<...>>             Subscript
    C<K<...>>             Keyboard input (typically rendered fixed-width)
    C<L<...|...>>         Link (C<L<R<display text>|R<destination URI>>>)
    C<M<...:...>>         Module-defined code (C<M<R<scheme>:R<contents>>>)
    C<N<...>>             Note (not rendered inline)
    C<O<...>>             Strikethrough
    C<P<...>>             Inline eqivalent for C<=picture> block
    C<Q<>>                reserved
    C<V<R><...>>          Replaceable component or metasyntax
    C<S<...>>             Space characters to be preserved
    C<T<...>>             Terminal output (typically rendered fixed-width)
    C<U<...>>             Unusual (typically rendered with underlining)
    C«V<V><...>»          Verbatim (internal markup codes ignored)
    C<W<...|...>>         Contextual backlinks
    C<Y<>>                reserved
    C<X<...|..,..;...>>   Index entry (C<X<R<display text>|R<entry>,R<subentry>;...>>)
    C<Z<...>>             Zero-width comment (contents never rendered)

=end table

=end SUMMARY

=LICENSE Artistic license 2.0

=end pod