From bfddbcd5d6256c9a9c6706c6b64bbb01b99b2a2b Mon Sep 17 00:00:00 2001 From: Naoum Hankache Date: Sat, 4 Mar 2017 17:43:18 +0200 Subject: [PATCH] Add Pod tutorial --- doc/Language/pod.pod6 | 426 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 426 insertions(+) create mode 100644 doc/Language/pod.pod6 diff --git a/doc/Language/pod.pod6 b/doc/Language/pod.pod6 new file mode 100644 index 000000000..407fab08b --- /dev/null +++ b/doc/Language/pod.pod6 @@ -0,0 +1,426 @@ +=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 demonstarted 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 rejustification, +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 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. + +=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 + +This is a common myth and an unconscionable slur on the Spanish +people, the majority of whom are extremely attractive. +=end item + +=begin item +I + +In deciding whether to become an early riser, it is worth +considering whether you would actually enjoy annelids +for breakfast. +=end item + +As you can see, folk wisdom is often of dubious value. +=end code + +Let's consider two common proverbs: + +=begin item +I + +This is a common myth and an unconscionable slur on the Spanish +people, the majority of whom are extremely attractive. +=end item + +=begin item +I + +In deciding whether to become an early riser, it is worth +considering whether you would actually enjoy annelids +for breakfast. +=end item + +As you can see, folk wisdom is often of dubious value. + +=head2 Tables + +Check out this page for documentation related to L +Z + +=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> +=code Perl 6 is B + +Perl 6 is B + +=head2 Italic + +To format a text in italic enclose it in C> +=code Perl 6 is I + +Perl 6 is I + +=head2 Underlined + +To underline a text enclose it in C> +=code Perl 6 is U + +Z + +=head2 Code + +To flag text as Code and treat it verbatim enclose it in C> +=code C + +C + +=head2 Links + +To create a link enclose it in C> +=code Perl 6 homepage L + +Perl 6 homepage L + +=head2 Comments + +A comment is text that is never rendered. + +To create a comment enclose it in C> +=code Perl 6 is awesome Z + +Perl 6 is awesome Z + +=head2 Notes + +Notes are rendered as footnotes. + +To create a note enclose it in C> +=code Perl 6 is multi-paradigmatic N + +Z > + +=head2 Keyboard input + +To flag text as keyboard input enclose it in C> +=code Enter your name K + +Z + +=head2 Terminal Output + +To flag text as terminal output enclose it in C> +=code Hello T + +Z + +=head2 Unicode + +To include Unicode code points or HTML5 character references in a Pod document, enclose them in C> + +C> 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 and E 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 E<171> and E<187> characters. + +=head1 Rendering Pod + +=head2 HTML + +In order to generate HTML from Pod, you need the C module. + +If it is not already installed, install it by running the following command: +C + +Using the terminal run the following command: +=begin code +perl6 --doc=HTML filecontaining.pod6 > outputfilename.html +=end code + +=head2 Markdown + +In order to generate Markdown from Pod, you need the C module. + +If it is not already installed, install it by running the following command: +C + +Using the terminal run the following command: +=begin code +perl6 --doc=Markdown filecontaining.pod6 > outputfilename.md +=end code + +=end pod