Perl 6 pod

An easy-to-use markup language

Perl 6 pod is an easy-to-use markup language. Pod can be used for writing language documentation, for documenting programs and modules, as well as for other types of document composition.

Every Pod document has to begin with =begin pod and end with =end pod. Everything between these two delimiters will be processed and used to generate documentation.

=begin pod
 
A very simple Perl 6 Pod document
 
=end pod

Block structure

A Pod document may consist of multiple Pod blocks. There are four ways to define a block (delimited, paragraph, abbreviated, and declarator); the first three yield the same result but the fourth differs. You can use whichever form is most convenient for your particular documentation task.

Delimited blocks

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

=begin head1
Top Level Heading
=end head1

Configuration information

After the typename, the rest of the =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 Perl6-ish option pairs. That is, any of:

Value is... Specify with... Or with... Or with...
List :key[$e1, $e2, ...] :key($e1, $e2, ...)
Hash :key{$k1=>$v1, $k2=>$v2}
Boolean (true) :key :key(True) :key[True]
Boolean (false) :!key :key(False) :key[False]
String :key<str> :key('str') :key("str")
Int :key(42) :key[42]
Number :key(2.3) :key[2.3]

Where '$e1, $e2, ...' are list elements of type String, Int, Number, or Boolean. Lists may have mixed element types. Note that one-element lists are converted to the type of their element (String, Int, Number, or Boolean). Also note that "bigints" can be used if required.

For hashes, '$k1, $k2, ...' are keys of type Str and '$v1, $2, ...' are values of type String, Int, Number, or Boolean.

Strings are delimited by single or double quotes. Whitespace is insignificant outside of strings. Hash keys need not be quote-delimited unless they contain significant whitespace.

All option keys and values must, of course, be constants since Pod is a specification language, not a programming language. Specifically, option values cannot be closures. See Synopsis 2 for details of the various Perl 6 pair notations.

The configuration section may be extended over subsequent lines by starting those lines with an = in the first (virtual) column followed by a whitespace character. (NOTE: This feature is not yet implemented. All configuration information currently must be provided on the same line as the =begin marker line or =for name for paragraph blocks.)

Paragraph blocks

Paragraph blocks begin by a =for marker and end by the next Pod directive or the first blank line. The =for marker is followed by the typename of the block plus, optionally, any configuration data as in the delimited blocks described above.

=for head1
Top Level Heading

Abbreviated blocks

Abbreviated blocks begin by an '=' sign, which is followed immediately by the typename of the block. All following data are part of the contents of the block, thus configuration data cannot be specified for an abbreviated block. The block ends at the next Pod directive or the first blank line.

=head1 Top level heading 

Declarator blocks

Declarator blocks differ from the others by not having a specific type, instead they are attached to some source code.

Declarator blocks are introduced by a special comment: either #| or #=, which must be immediately followed by either a space or an opening bracket. If followed by a space, the block is terminated by the end of line; if followed by one or more opening brackets, the block is terminated by the matching sequence of closing brackets.

Blocks starting with #| are attached to the code after them, and blocks starting with #= are attached to the code before them.

Since declarator blocks are attached to source code, they can be used to document classes, roles, subroutines etc.

The WHY method can be used on these classes, roles, subroutines etc. to return the attached Pod value.

#| Base class for magicians 
class Magician {
  has Int $.level;
  has Str @.spells;
}
 
#| Fight mechanics 
sub duel(Magician $aMagician $b{
}
#= Magicians only, no mortals. 
 
say Magician.WHY# OUTPUT: «Base class for magicians␤» 
say &duel.WHY.leading# OUTPUT: «Fight mechanics␤» 
say &duel.WHY.trailing# OUTPUT: «Magicians only, no mortals.␤» 

These declarations can extend multiple blocks:

#|( This is an example of stringification: 
    * Numbers turn into strings
    * Regexes operate on said strings
    * C<with> topicalizes and places result into $_
)
sub search-in-seqInt $endInt $number ) {
    with (^$end).grep( /^$number/ ) {
        .say for $_<>;
    }
}
#=« Uses 
    * topic
    * decont operator
»

By using a matched pair of parenthesis constructs such as () or «» the comments can extend multiple lines. This format, however, will not translate to a multi-line display by perl6 -doc.

Block types

Pod offers a wide range of standard block types.

Headings

Headings can be defined using =headN, where N is greater than zero (e.g., =head1, =head2, …).

=head1 A top level heading 
 
=head2 A second level heading 
 
=head3 A third level heading 

Ordinary paragraphs

An ordinary paragraph consists of text that is to be formatted into a document at the current level of nesting, with whitespace squeezed, lines filled, and any special inline mark-up applied.

Ordinary paragraphs consist of one or more consecutive lines of text, each of which starts with a non-whitespace character. The paragraph is terminated by the first blank line or block directive.

For example:

=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

Ordinary paragraphs do not require an explicit marker or delimiters.

Alternatively, there is also an explicit =para marker that can be used to explicitly mark a paragraph.

=para
This is an ordinary paragraph.
Its text  will   be     squeezed     and
short lines filled.

In addition, the longer =begin para and =end para form can be used.

For example:

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

As demonstrated by the previous example, within a delimited =begin para and =end para block, any blank lines are preserved.

Code blocks

Code blocks are used to specify source code, which should be rendered without re-justification, without whitespace-squeezing, and without recognizing any inline formatting codes. 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. The implicit code block is then terminated by a blank line.

For example:

This ordinary paragraph introduces a code block:
 
    my $name = 'John Doe';
    say $name;

Code blocks can also be explicitly defined by enclosing them in =begin code and =end code

    =begin code
    my $name = 'John Doe';
    say $name;
    =end code

I/O blocks

Pod provides blocks for specifying the input and output of programs.

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

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

Lists

Unordered lists

Lists in Pod are specified as a series of =item blocks.

For example:

The three suspects are:
 
=item  Happy 
=item  Sleepy 
=item  Grumpy 

The three suspects are:

Definition lists

Lists that define terms or commands use =defn, equivalent to the DL lists in HTML

=defn Happy 
When you're not blue.
 
=defn Blue 
When you're not happy.

will be rendered with Pod::To::HTML this way:

Happy When you're not blue.

Blue When you're not happy.

Which, for the time being, is a simple HTML paragraph, but the format might change in the future.

Multi-level lists

Lists may be multi-level, with items at each level specified using the =item1, =item2, =item3, etc. blocks.

Note that =item is just an abbreviation for =item1.

For example:

=item1  Animal 
=item2     Vertebrate 
=item2     Invertebrate 
 
=item1  Phase 
=item2     Solid 
=item2     Liquid 
=item2     Gas 

Multi-paragraph lists

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

For example:

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 seefolk wisdom is often of dubious value.

Let's consider two common proverbs:

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

Tables

Check out this page for documentation related to Tables

Pod comments

Pod comments are comments that Pod renderers ignore.

Comments are useful for meta-documentation (documenting the documentation). Single-line comments use the comment keyword:

=comment Add more here about the algorithm 

For multi-line comments use a delimited comment block:

=begin comment
This comment is
multi-line.
=end comment

Semantic blocks

All uppercase block typenames are reserved for specifying standard documentation, publishing, source components, or meta-information.

=NAME
=AUTHOR
=VERSION
=TITLE
=SUBTITLE

Formatting codes

Formatting codes provide a way to add inline mark-up to a piece of text.

All Pod formatting codes consist of a single capital letter followed immediately by a set of angle brackets.

Formatting codes may nest other formatting codes.

Bold

To format a text in bold enclose it in B< >

Perl 6 is B<awesome>

Perl 6 is awesome

Italic

To format a text in italic enclose it in I< >

Perl 6 is I<awesome>

Perl 6 is awesome

Underlined

To underline a text enclose it in U< >

Perl 6 is U<awesome>

Code

To flag text as Code and treat it verbatim enclose it in C< >

C<my $var = 1; say $var;>

my $var = 1; say $var;

To create a link enclose it in L< >

Perl 6 homepage L<https://perl6.org>
L<Perl 6 homepage|https://perl6.org>

Perl 6 homepage https://perl6.org

Perl 6 homepage

To create a link to a section in the same document:

Comments L<#Comments>
L<Comments|#Comments>

Comments Comments

Comments

Comments

A comment is text that is never rendered.

To create a comment enclose it in Z< >

Perl 6 is awesome Z<Of course it is!>

Perl 6 is awesome

Notes

Notes are rendered as footnotes.

To create a note enclose it in N< >

Perl 6 is multi-paradigmatic N<Supporting Procedural, Object Oriented, and Functional programming>

Keyboard input

To flag text as keyboard input enclose it in K< >

Enter your name K<John Doe>

Terminal output

To flag text as terminal output enclose it in T< >

Hello T<John Doe>

Unicode

To include Unicode code points or HTML5 character references in a Pod document, enclose them in E< >

E< > can enclose a number, that number is treated as the decimal Unicode value for the desired code point. It can also enclose explicit binary, octal, decimal, or hexadecimal numbers using the Perl 6 notations for explicitly based numbers.

Perl 6 makes considerable use of the E<171> and E<187> characters.
 
Perl 6 makes considerable use of the E<laquo> and E<raquo> characters.
 
Perl 6 makes considerable use of the E<0b10101011> and E<0b10111011> characters.
 
Perl 6 makes considerable use of the E<0o253> and E<0o273> characters.
 
Perl 6 makes considerable use of the E<0d171> and E<0d187> characters.
 
Perl 6 makes considerable use of the E<0xAB> and E<0xBB> characters.

Perl 6 makes considerable use of the « and » characters.

Rendering Pod

HTML

In order to generate HTML from Pod, you need the Pod::To::HTML module.

If it is not already installed, install it by running the following command: zef install Pod::To::HTML

Using the terminal run the following command:

perl6 --doc=HTML input.pod6 > output.html

Markdown

In order to generate Markdown from Pod, you need the Pod::To::Markdown module.

If it is not already installed, install it by running the following command: zef install Pod::To::Markdown

Using the terminal run the following command:

perl6 --doc=Markdown input.pod6 > output.md

Text

In order to generate Text from Pod, you can use the default Pod::To::Text module.

Using the terminal, run the following command:

perl6 --doc=Text input.pod6 > output.txt

You can omit the =Text portion:

perl6 --doc input.pod6 > output.txt

You can even embed Pod directly in your program and add the traditional Unix command line "--man" option to your program with a multi MAIN subroutine like this:

multi MAIN(Bool :$man)
{
    run $*EXECUTABLE'--doc'$*PROGRAM;
}

Now myprogram --man will output your Pod rendered as a man page.

Accessing Pod

In order to access Pod documentation from within a Perl 6 program it is required to use the special = twigil, as documented in the variables section.

The = twigil provides the introspection over the Pod structure, providing a Pod::Block tree root from which it is possible to access the whole structure of the Pod document.

As an example, the following piece of code introspects its own Pod documentation:

=begin pod
 
=head1 This is an head1 title 
 
This is a paragraph.
 
=head2 Subsection 
 
Here some text for the subsection.
 
=end pod
 
for $=pod -> $pod-item {
    for $pod-item.contents -> $pod-block {
      $pod-block.perl.say;
    }
}

producing the following output:

Pod::Heading.new(level => 1config => {}contents => [Pod::Block::Para.new(config => {}contents => ["This is an head1 title"])]);
Pod::Block::Para.new(config => {}contents => ["This is a paragraph."]);
Pod::Heading.new(level => 2config => {}contents => [Pod::Block::Para.new(config => {}contents => ["Subsection"])]);
Pod::Block::Para.new(config => {}contents => ["Here some text for the subsection."]);