Skip to content

Commit

Permalink
Standardizes Pod name
Browse files Browse the repository at this point in the history
To Pod6, which is exactly the same as the extension. It's bound to change eventually, so it's better if we always use the same thing.

I have changed Perl 6 Pod to Pod6 everywhere. Still, the official name with pod <non-breaking whitespace>6 is going to be used somewhere.

Pod has also been changed to Pod6, to avoid confusion with Perl 5's Pod. Several versions of the name, with or without capital, were used, so this also standardizes that.

This closes #1923
  • Loading branch information
JJ committed Aug 21, 2019
1 parent d10938e commit ca2534f
Showing 1 changed file with 24 additions and 23 deletions.
47 changes: 24 additions & 23 deletions doc/Language/pod.pod6
@@ -1,28 +1,29 @@
=begin pod :kind("Language") :subkind("Language") :category("reference")
=TITLE Perl 6 pod
=TITLE Pod6
=SUBTITLE An easy-to-use markup language for documenting Perl modules and programs
Perl 6 pod is an easy-to-use markup language. Pod can be used for
Pod6 is an easy-to-use markup language. It 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>.
Every Pod6 document has to begin with C<=begin pod> and end with C<=end pod>.
Everything between these two delimiters will be processed and used to generate
documentation.
=begin code :lang<pod6>
=begin pod
A very simple Perl 6 Pod document
A very simple Pod6 document
=end pod
=end code
=head1 Block structure
A Pod document may consist of multiple Pod blocks. There are four ways to define
A Pod6 document may consist of multiple Pod6 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.
Expand Down Expand Up @@ -73,7 +74,7 @@ outside of strings. Hash keys need not be quote-delimited unless they contain
significant whitespace. Strings entered inside angle brackets become lists if
any whitespace is used inside the angle brackets.
All option keys and values must, of course, be constants since Pod is a
All option keys and values must, of course, be constants since Pod6 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.
Expand All @@ -87,7 +88,7 @@ line as the C<=begin> marker line or C<=for name> for paragraph blocks.>
=head2 Paragraph blocks
Paragraph blocks begin by a C<=for> marker and end by
the next Pod directive or the first blank line.
the next Pod6 directive or the first blank line.
The C<=for> marker is followed by the C<typename> of the block
plus, optionally, any configuration data as in the delimited
blocks described above.
Expand All @@ -102,7 +103,7 @@ Top Level Heading
Abbreviated blocks begin by an C<'='> sign, which is followed immediately by the
C<typename> of the block. All following data are part of the contents of the
block, thus configuration data B<cannot> be specified for an I<abbreviated>
block. The block ends at the next Pod directive or the first blank line.
block. The block ends at the next Pod6 directive or the first blank line.
=begin code :lang<pod6>
=head1 Top level heading
Expand All @@ -127,7 +128,7 @@ Since declarator blocks are attached to source code, they can be used to
document classes, roles, subroutines and in general any statement or block.
The C<WHY> method can be used on these classes, roles, subroutines etc. to
return the attached Pod value.
return the attached Pod6 value.
=begin code
#| Base class for magicians
Expand Down Expand Up @@ -171,7 +172,7 @@ a multi-line display by C<perl6 -doc>.
=head1 Block types
Pod offers a wide range of standard block types.
Pod6 offers a wide range of standard block types.
=head2 Headings
Expand Down Expand Up @@ -282,7 +283,7 @@ and C<=end code>
=head2 I/O blocks
Pod provides blocks for specifying the input and output of programs.
Pod6 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.
Expand All @@ -294,7 +295,7 @@ which should also be rendered without re-justification or whitespace-squeezing.
=head3 Unordered lists
Lists in Pod are specified as a series of C<=item> blocks.
Lists in Pod6 are specified as a series of C<=item> blocks.
For example:
Expand Down Expand Up @@ -414,9 +415,9 @@ As you can see, folk wisdom is often of dubious value.
Check out this page for documentation related to L<Tables|/language/tables>
Z<Eventually copy everything from tables.pod6 and put it here>
=head2 Pod comments
=head2 Pod6 comments
Pod comments are comments that Pod renderers ignore.
Pod6 comments are comments that Pod6 renderers ignore.
Comments are useful for meta-documentation (documenting the documentation).
Single-line comments use the C<=comment> marker:
Expand Down Expand Up @@ -451,7 +452,7 @@ documentation, publishing, source components, or meta-information.
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
All Pod6 formatting codes consist of a single capital letter followed immediately
by a set of single or double angle brackets; Unicode double angle brackets may
be used.
Expand Down Expand Up @@ -498,7 +499,7 @@ To create a link enclose it in C<L< >>
A vertical bar (optional) separates label and target.
The target location can be an URL (first example) or a local POD document
The target location can be an URL (first example) or a local Pod6 document
(second example). Local file names are relative to the base of the project, not
the current document.
Expand Down Expand Up @@ -646,7 +647,7 @@ Z<If used will bust Pod::To::BigPage>
=head2 Unicode
To include Unicode code points or HTML5 character references in a Pod document,
To include Unicode code points or HTML5 character references in a Pod6 document,
enclose them in C<E< >>
C<E< >> can enclose a number, which is treated as the decimal Unicode
Expand Down Expand Up @@ -787,7 +788,7 @@ You can omit the C<=Text> portion:
perl6 --doc input.pod6 > output.txt
=end code
You can even embed Pod directly in your program and add the
You can even embed Pod6 directly in your program and add the
traditional Unix command line "--man" option to your program with a
multi MAIN subroutine like this:
Expand All @@ -797,20 +798,20 @@ multi MAIN(Bool :$man) {
}
=end code
Now C<myprogram --man> will output your Pod rendered as a man page.
Now C<myprogram --man> will output your Pod6 rendered as a man page.
=head1 Accessing Pod
In order to access Pod documentation from within a Perl 6 program the
In order to access Pod6 documentation from within a Perl 6 program the
special C<=> twigil, as documented
in the L<variables section|/language/variables#The_=_twigil>, must be used.
The C<=> twigil provides the introspection over the Pod structure,
The C<=> twigil provides the introspection over the Pod6 structure,
providing a L<Pod::Block|/type/Pod::Block> tree root from which it is possible
to access the whole structure of the Pod document.
to access the whole structure of the Pod6 document.
As an example, the following piece of code introspects
its own Pod documentation:
its own Pod6 documentation:
=begin code
=begin pod
Expand Down

0 comments on commit ca2534f

Please sign in to comment.