diff options
Diffstat (limited to 'perl6-pod.html.markdown')
| -rw-r--r-- | perl6-pod.html.markdown | 622 |
1 files changed, 0 insertions, 622 deletions
diff --git a/perl6-pod.html.markdown b/perl6-pod.html.markdown deleted file mode 100644 index 80a501b8..00000000 --- a/perl6-pod.html.markdown +++ /dev/null @@ -1,622 +0,0 @@ ---- -language: Pod -contributors: - - ["Luis F. Uceta", "https://uzluisf.gitlab.io/"] -filename: learnpod.pod6 ---- - -Pod is an easy-to-use and purely descriptive mark-up language, -with no presentational components. Besides its use for documenting -Raku Perl 6 programs and modules, Pod can be utilized to write language -documentation, blogs, and other types of document composition as well. - -Pod documents can be easily converted to HTML and many other formats -(e.g., Markdown, Latex, plain text, etc.) by using the corresponding -variant of the `Pod::To` modules (e.g. `Pod::To::HTML` for HTML conversion). - -- [General Info](#general-info) -- [Pod Basics](#pod-basics) - - [Basic Text Formatting](#basic-text-formatting) - - [Headings](#headings) - - [Ordinary Paragraphs](#ordinary-paragraphs) - - [Lists](#lists) - - [Code Blocks](#code-blocks) - - [Comments](#comments) - - [Links](#links) - - [Tables](#tables) -- [Block Structures](#block-structures) - - [Abbreviated Blocks](#abbreviated-blocks) - - [Delimited Blocks](#delimited-blocks) - - [Paragraph Blocks](#paragraph-blocks) -- [Configuration Data](#configuration-data) - - [Standard Configuration Options](#standard-configuration-options) - - [Block Pre-configuration](#block-pre-configuration) -- [Semantic Blocks](#semantic-blocks) -- [Miscellaneous](#miscellaneous) - - [Notes](#notes) - - [Keyboard Input](#keyboard-input) - - [Terminal Output](#terminal-output) - - [Unicode](#unicode) -- [Rendering Pod](#rendering-pod) -- [Accessing Pod](#accessing-pod) - -## General Info - -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 Raku Perl 6 Pod document. All the other directives go here! - -=end pod -``` - -Pod documents usually coexist with Raku Perl 6 code. If by themselves, -Pod files often have the `.pod6` suffix. Moving forward, it's assumed that -the constructs being discussed are surrounded by the `=begin pod ... =end pod` -directives. - -## Pod Basics - -### Basic Text Formatting - -Text can be easily styled as bold, italic, underlined or verbatim (for code -formatting) using the following formatting codes: `B<>`, `I<>`, `U<>` -and `C<>`. - -``` -B<This text is in Bold.> - -I<This text is in Italics.> - -U<This text is Underlined.> - -The function C<sub sum { $^x + $^y}> is treated as verbatim. -``` - -There are more formatting codes (e.g., `L<>`, `T<>`, etc.) but they'll be -discussed later throughout the document. You'll recognize them because they're -just a single capital letter followed immediately by a set of single or double -angle brackets. The Unicode variant («») of the angle brackets can also be -used. - -### Headings - -Headings are created by using the `=headN` directive where `N` is the -heading level. - -``` -=head1 This is level 1 -=head2 This is level 2 -=head3 This is level 3 -=head4 This is level 4 -=head5 This is level 5 -=head6 This is level 6 -``` - -### Ordinary Paragraphs - -Ordinary paragraphs consist of one or more adjacent lines of text, each of -which starts with a non-whitespace character. Any paragraph is terminated -by the first blank line or block directive. - -``` -=head1 First level heading block - -=head2 Paragraph 1 - -This is an ordinary paragraph. Its text will be squeezed and -short lines filled. It is terminated by the first blank line. - -=head2 Paragraph 2 - -This is another ordinary paragraph albeit shorter. -``` - -Alternatively, the `=para` directive can be used to explicitly mark adjacent -lines of text as a paragraph. - -``` -=head1 First level heading block - -=head2 Paragraph 1 - -=para -This is an ordinary paragraph. Its text will be squeezed and -short lines filled. It is terminated by the first blank line. - -=head2 Paragraph 2 - -=para -This is another ordinary paragraph albeit shorter. -``` - -### Lists - -Unordered lists can be created using the `=item` directive. - -``` -=item Item -=item Item -=item Another item -``` - -Sublists are achieved with items at each level specified using the `=item1`, -`=item2`, `=item3`, `...`, `=itemN` etc. directives. The `=item` directive -defaults to `=item1`. - -``` -=item1 Item one -=item1 Item two -=item1 Item three - =item2 Sub-item - =item2 Sub-item -=item1 Item four -``` - -Definition lists that define terms or commands use the `=defn` directive. -This is equivalent to the `<dl>` element in HTML. - -``` -=defn Beast of Bodmin -A large feline inhabiting Bodmin Moor. - -=defn Morgawr -A sea serpent. - -=defn Owlman -A giant owl-like creature. -``` - -### Code Blocks - -A code block is created (which uses the HTML `<code>` element) by starting each -line with one or more whitespace characters. - -``` - #`( this is comment ) - my $sum = -> $x, $y { $x + $y } - say $sum(12, 5); -``` - -As shown in the [Basic Text Formatting](#basic-text-formatting) section, -inline code can be created using the `C<>` code. - -``` -In Raku Perl 6, there are several functions/methods to output text. Some of them -are C<print>, C<put> and C<say>. -``` - -### Comments - -Although Pod blocks are ignored by the Raku Perl 6 compiler, everything -indentified as a Pod block will be read and interpreted by Pod renderers. In -order to prevent Pod blocks from being rendered by any renderer, use the -`=comment` directive. - -``` -=comment Add more here about the algorithm. - -=comment Pod comments are great for documenting the documentation. -``` - -To create inline comments, use the `Z<>` code. - -``` -Pod is awesome Z<Of course it is!>. And Raku Perl 6 too! -``` - -Given that the Perl interpreter never executes embedded Pod blocks, -comment blocks can also be used as an alternative form of nestable block -comments in Raku Perl 6. - -### Links - -Creating links in Pod is quite easy and is done by enclosing them in -a `L<>` code. The general format is `L<Label|Url>` with `Label` -being optional. - -``` -Raku Perl 6 homepage is L<https://perl6.org>. -L<Click me!|http://link.org/>. -``` - -Relative paths work too. - -``` -L<Go to music|/music/>. -``` - -Linking to a section in the same document works as well. - -``` -L<Link to Headings|#Headings> -``` - -### Tables - -The Pod specifications are not completely handled properly yet and this -includes the handling of table. For simplicity's sake, only one way of -constructing tables is shown here. To learn about good practices and see -examples of both good and bad tables, please visit -<https://docs.perl6.org/language/tables>. - -``` -=begin table -Option | Description -============|================ -data | path to data files. -engine | engine to be used for processing templates. -ext | extension to be used for dest files. -=end table -``` - -## Block Structures - -As mentioned earlier, Pod documents are specified using directives, which are -used to delimit blocks of textual content and declare optional -[configuration information](#configuration-data). Every directive starts with -an equals sign (`=`) in the first column. The content of a document is -specified within one or more blocks. Every Pod block may be declared in any of -three equivalent forms: delimited style, paragraph style, or abbreviated style. - -Up to this point, we have only used the abbreviated style for the block -types (e.g., `=head1`, `=para`, `=comment`, `=item`, etc). - -### Abbreviated Blocks - -Abbreviated blocks are introduced by an `=` sign in the first column, which -is followed immediately by the `typename` of the block and then the content. -The rest of the line is treated as block data, rather than as configuration. -The content terminates at the next Pod directive or the first blank line -(which is not part of the block data). The general syntax is - -``` -=BLOCK_TYPE BLOCK_DATA -``` -For example: - -``` -=head1 Top level heading -``` - -### Delimited Blocks - -Delimited blocks are bounded by `=begin` and `=end` markers, both of which are -followed by a valid Pod identifier, which is the `typename` of the block. -The general syntax is - -``` -=begin BLOCK_TYPE -BLOCK_DATA -=end BLOCK_TYPE -``` - -For example: - -``` -=begin head1 -Top level heading -=end head1 -``` - -This type of blocks is useful for creating headings, list items, code blocks, -etc. with multiple paragraphs. For example, - -* a multiline item of a list - -``` -=begin item -This is a paragraph in list item. - -This is another paragraph in the same list item. -=end item -``` - -* a code block - -``` -=begin code -#`( -A non-efficient recursive implementation of a power function using multi subs. -) - -multi pow( Real $base, 0 ) { 1 } - -multi pow( Real $base, Int $exp where * ≥ 0) { - $base * pow($base, $exp - 1) -} - -multi pow( Real $base ) { - pow($base, 2) -} - -say pow(3, 0); #=> 1 -say pow(4.2, 2); #=> 17.64 -say pow(6); #=> 36 -=end code -``` - -### Paragraph Blocks - -Paragraph blocks are introduced by a `=for` marker and terminated by -the next Pod directive or the first blank line (which is not considered to -be part of the block's contents). The `=for` marker is followed by the -`typename` of the block. The general syntax is - -``` -=for BLOCK_TYPE -BLOCK DATA -``` - -For example: - -``` -=for head1 -Top level heading -``` - -## Configuration Data - -Except for abbreviated blocks, both delimited blocks and paragraph -blocks can be supplied with configuration information about their -contents right after the `typename` of the block. Thus the following -are more general syntaxes for these blocks: - -* Delimited blocks - -``` -=begin BLOCK_TYPE OPTIONAL_CONFIG_INFO -= ADDITIONAL_CONFIG_INFO -BLOCK_DATA -=end BLOCK_TYPE -``` - -* Paragraph blocks - -``` -=for BLOCK_TYPE OPTIONAL_CONFIG_INFO -= ADDITIONAL_CONFIG_INFO -BLOCK DATA -``` - -The configuration information is provided in a format akin to the -["colon pair"](https://docs.perl6.org/language/glossary#index-entry-Colon_Pair) -syntax in Raku Perl 6. The following table is a simplified version of the -different ways in which configuration info can be supplied. Please go to -<https://docs.perl6.org/language/pod#Configuration_information> for a more -thorough treatment of the subject. - -| Value | Specify with... | Example | -| :-------- | :------ | :------ | -| List | :key($elem1, $elem2, ...) | :tags('Pod', 'Perl6') | -| Hash | :key{$key1 => $value1, ...} | :feeds{url => 'perl6.org'} | -| Boolean | :key/:key(True) | :skip-test(True) | -| Boolean | :!key/:key(False) | :!skip-test | -| String | :key('string') | :nonexec-reason('SyntaxError') | -| Int | :key(2) | :post-number(6) | - - -### Standard Configuration Options - -Pod provides a small number of standard configuration options that can -be applied uniformly to built-in block types. Some of them are: - -* `:numbered` - -This option specifies that the block is to be numbered. The most common -use of this option is to create numbered headings and ordered lists, but it -can be applied to any block. - -For example: - -``` -=for head1 :numbered -The Problem -=for head1 :numbered -The Solution -=for head2 :numbered -Analysis -=for head3 :numbered -Overview -``` - -* `:allow` - -The value of the `:allow` option must be a list of the (single-letter) names -of one or more formatting codes. Those codes will then remain active inside -the code block. The option is most often used on `=code` blocks to allow -mark-up within those otherwise verbatim blocks, though it can be used in any -block that contains verbatim text. - -Given the following snippet: - -``` -=begin code :allow('B', 'I') -B<sub> greet( $name ) { - B<say> "Hello, $nameI<!>"; -} -=end code -``` - -we get the following output: - -<pre><strong>sub</strong> greet( $name ) { - <strong>say</strong> "Hello, $name<em>!</em>"; -} -</pre> - -This is highly dependent on the format output. For example, while this works -when Pod is converted to HTML, it might not be preserved when converted -to Markdown. - -### Block Pre-configuration - -The `=config` directive allows you to prespecify standard configuration -information that is applied to every block of a particular type. -The general syntax for configuration directives is: - -``` -=config BLOCK_TYPE CONFIG OPTIONS -= ADDITIONAL_CONFIG_INFO -``` - -For example, to specify that every heading level 1 be numbered, bold -and underlined, you preconfigure the `=head1` as follows: - -``` -=config head1 :formatted('B', 'U') :numbered -``` - -## Semantic Blocks - -All uppercase block typenames are reserved for specifying standard -documentation, publishing, source components, or meta-information. -Some of them are: - -``` -=NAME -=AUTHOR -=VERSION -=CREATED -=SYNOPSIS -=DESCRIPTION -=USAGE -``` - -Most of these blocks would typically be used in their full -delimited forms. For example, - -``` -=NAME B<Doc::Magic> - -=begin DESCRIPTION -This module helps you generate documentation automagically. -Not source code needed! Most of it is outsourced from a black hole. -=end DESCRIPTION - -=begin SYNOPSIS -=begin code - use Doc::Magic; - - my Doc::Magic $doc .= new(); - - my $result = $doc.create-documentation($fh); -=end code -=end SYNOPSIS - -=AUTHOR Authorius Docus -=VERSION 42 -``` - -## Miscellaneous - -### Notes - -Notes are rendered as footnotes and created by enclosing a note in a -`N<>` code. - -``` -In addition, the language is also multi-paradigmatic N<According to Wikipedia, -this means that it supports procedural, object-oriented, and functional -programming.> -``` - -### Keyboard Input - -To flag text as keyboard input enclose it in a `K<>` code. - -``` -Enter your name K<John Doe> -``` - -### Terminal Output - -To flag text as terminal output enclose it in `T<>` code. - -``` -Hello, T<John Doe> -``` - -### Unicode - -To include Unicode code points or HTML5 character references in -a Pod document, enclose them in a `E<>` code. - -For example: - -``` -Raku Perl 6 makes considerable use of the E<171> and E<187> characters. -Raku Perl 6 makes considerable use of the E<laquo> and E<raquo> characters. -``` - -is rendered as: - -Raku Perl 6 makes considerable use of the « and » characters. -Raku Perl 6 makes considerable use of the « and » characters. - -## Rendering Pod - -To generate any output (i.e., Markdown, HTML, Text, etc.), you need to -have the Raku Perl 6 compiler installed. In addition, you must install -a module (e.g., `Pod::To::Markdown`, `Pod::To::HTML`, `Pod::To::Text`, etc.) -that generates your desired output from Pod. - -For instructions about installing Raku Perl 6, -[look here](https://perl6.org/downloads/). - -Run the following command to generate a certain output: - -``` -perl6 --doc=TARGET input.pod6 > output.html -``` - -with `TARGET` being `Markdown`, `HTML`, `Text`, etc. Thus to generate -Markdown from Pod, run this: - -``` -perl6 --doc=Markdown input.pod6 > output.html -``` - -## Accessing Pod - -In order to access Pod documentation from within a Raku Perl 6 program, -it is required to use the special `=` twigil (e.g., `$=pod`, `$=SYNOPSIS`,etc). - -The `$=` construct provides the introspection over the Pod structure, -producing a `Pod::Block` tree root from which it is possible to access -the whole structure of the Pod document. - -If we place the following piece of Raku Perl 6 code and the Pod documentation -in the section [Semantic blocks](#semantic-blocks) in the same file: - -``` -my %used-directives; -for $=pod -> $pod-item { - for $pod-item.contents -> $pod-block { - next unless $pod-block ~~ Pod::Block::Named; - %used-directives{$pod-block.name} = True; - } -} - -say %used-directives.keys.join("\n"); -``` - -we get the following output: - -``` -SYNOPSIS -NAME -VERSION -AUTHOR -DESCRIPTION -``` - -## Additional Information - -* <https://docs.perl6.org/language/pod> for the Pod documentation. -* <https://docs.perl6.org/language/tables> for advices about Pod tables. -* <https://design.perl6.org/S26.html> for the Pod specification. |