=begin pod

=TITLE Perl 6 Pod

=SUBTITLE An easy-to-use markup language

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 C<=begin pod> and end with C<=end pod>.
Everything between these 2 delimiters will be processed and used to generate documentation.

=begin code
=begin pod

A very simple Perl 6 Pod document

=end pod
=end code

=head1 Block Structure

A Pod document may consist of multiple Pod blocks.
There are three ways to define a block; all of which yield the same result.
You can use whichever form is most convenient for your particular documentation task.

=head2 Delimited blocks

Delimited blocks are bound by C<=begin> and C<=end> markers, both of
which are followed by the typename of the block.

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

=head2 Paragraph blocks

Paragraph blocks begin by a C<=for> marker and end by
the next Pod directive or the first blank line.
The C<=for> marker is followed by the typename of the block.

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

=head2 Abbreviated blocks

Abbreviated blocks begin by an C<'='> sign, which is followed immediately by the typename of the
block. The block ends at the next Pod directive or the
first blank line.

=begin code
=head1 Top Level Heading
=end code

=head1 Block types

Pod offers a wide range of standard block types.

=head2 Headings

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

=begin code
=head1 A Top Level Heading

=head2 A Second Level Heading

=head3 A Third Level Heading
=end code

=head2 Ordinary paragraphs

Ordinary paragraph 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 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:

=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

Ordinary paragraphs do not require an explicit marker or delimiters.

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

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

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

For example:

=begin code

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

This is still part of the same paragraph,
which continues until an...
=end para
=end code

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

=head2 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:

=begin code
This ordinary paragraph introduces a code block:

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

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

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


=head2 I/O blocks

Pod 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 re-justification or squeezing of whitespace.

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

=head2 Lists

=head3 Unordered Lists

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

For example:

=begin code
The three suspects are:

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

The three suspects are:

=item  Happy
=item  Sleepy
=item  Grumpy

=head3 Multi-level Lists

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

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

=item1  Animal
=item2     Vertebrate
=item2     Invertebrate

=item1  Phase
=item2     Solid
=item2     Liquid
=item2     Gas

=head3 Multi-paragraph Lists

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

For example:

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

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.

=head2 Tables

Check out this page for documentation related to L<Tables|https://docs.perl6.org/language/tables>
Z<Eventually copy everything from tables.pod6 and put it here>

=head2 Pod comments

Pod comments are comments that Pod renderers ignore.

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

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

=head2 Semantic blocks

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

=begin code
=NAME
=AUTHOR
=VERSION
=TITLE
=SUBTITLE
=end code

=head1 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.

=head2 Bold

To format a text in bold enclose it in C<B< >>
=code Perl 6 is B<awesome>

Perl 6 is B<awesome>

=head2 Italic

To format a text in italic enclose it in C<I< >>
=code Perl 6 is I<awesome>

Perl 6 is I<awesome>

=head2 Underlined

To underline a text enclose it in C<U< >>
=code Perl 6 is U<awesome>

Z<If used will bust Pod::To::BigPage>

=head2 Code

To flag text as Code and treat it verbatim enclose it in C<C< >>
=code C<my $var = 1; say $var;>

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

=head2 Links

To create a link enclose it in C<L< >>
=code Perl 6 homepage L<https://perl6.org>

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

=head2 Comments

A comment is text that is never rendered.

To create a comment enclose it in C<Z< >>
=code Perl 6 is awesome Z<Of course it is!>

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

=head2 Notes

Notes are rendered as footnotes.

To create a note enclose it in C<N< >>
=code Perl 6 is multi-paradigmatic N<Supporting Procedural, Object Oriented, and Functional programming>

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

=head2 Keyboard input

To flag text as keyboard input enclose it in C<K< >>
=code Enter your name K<John Doe>

Z<If used will bust Pod::To::BigPage>

=head2 Terminal Output

To flag text as terminal output enclose it in C<T< >>
=code Hello T<John Doe>

Z<If used will bust Pod::To::BigPage>

=head2 Unicode

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

C<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.

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

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

=head1 Rendering Pod

=head2 HTML

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

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

Using the terminal run the following command:
=begin code
perl6 --doc=HTML input.pod6 > output.html
=end code

=head2 Markdown

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

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

Using the terminal run the following command:
=begin code
perl6 --doc=Markdown input.pod6 > output.md
=end code

=end pod
