Changeset 14098 for docs/Perl6/Spec

Show
Ignore:
Timestamp:
10/09/06 17:25:56 (2 years ago)
Author:
audreyt
Message:

* docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian?.

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • docs/Perl6/Spec/Documentation.pod

    r13320 r14098  
    1 =encoding UTF-8 
     1=for comment 
     2    This file is deliberately specified in Perl 6 Pod format 
     3    Clearly a Perl 6 -> Perl 5 documentation translator is a high priority ;-) 
     4 
    25 
    36=head1 TITLE 
    … …  
    58[DRAFT] Synopsis 26 - Documentation 
    69 
     10 
    711=head1 AUTHORS 
    812 
    9 Ingy dt Net <ingy@cpan.org> 
    10  
    1113Damian Conway <damian@conway.org> 
    1214 
    13 =for comment 
    14     I decided to go ahead and give this doc a cleaning up. I'm pulling 
    15     out the comments, that have been around for a while, and adding a 
    16     few of my own where need be. I'm doing my best to make sure the 
    17     comments are reflected in the new content. --ingy 
     15Ingy dE<ouml>t Net <ingy@cpan.org> 
     16 
    1817 
    1918=head1 VERSION 
    2019 
    21   Maintainer:    Ingy dÖt Net <ingy@cpan.org> 
    22   Date:          9 Apr 2005 
    23   Last Modified: 27 Mar 2006 
    24  
    25 This document describes the documentation capabilities of 
    26 Perl 6. It assumes familiarity with Perl 5 and its POD (Plain Old 
    27 Documentation) format. 
    28  
    29 Perldoc is a documentation format specification that is completely 
    30 orthogonal to the Perl 6 specification. Still, Perl 6 is the primary 
    31 target of intent for Perldoc, so this specification refers to Perl 6 as 
    32 necessary. 
    33  
    34 =begin comment 
    35  
    36     Added this because, imho, it is of utmost importance that Perldoc be 
    37     able to be processed outside of Perl contexts, and without invoking 
    38     Perl. For example, a documentation editing tool written in Python 
    39     should be able to edit 98% of all Perl's documentation. It is not 
    40     acceptable for Perldoc to be unparsable because some Perl module 
    41     /needs/ to be loaded for it to be parsable. 
    42  
    43     This is not to say that the usage of Perldoc within Perl 6 is not 
    44     completely jacked up on Koolaid. %^D --ingy 
    45  
    46 =end comment 
    47  
    48 Throughout this document, the term "Perldoc" will be used as the generic 
    49 term to describe Perl Documentation. "Pod" now refers to a specific 
    50 I<dialect> of Perldoc. With Perl 6, there's more than one way to 
    51 document it. 
    52  
    53 See L</SYNTAX DIALECTS> to cut to the chase and read information on 
    54 the many ways in which you can annotate your code with Perldoc. 
    55  
    56 =head1 THE PERLDOC OBJECT MODEL (PDOM) 
    57  
    58 Perldoc has a Document Object Model. That is, all Perldoc documentation 
    59 in any dialect is modeled according to a schema. There are also standard 
    60 Perl runtime APIs for accessing, generating, and transforming the 
    61 content of documents. 
    62  
    63 Perldoc allows multiple documentation dialects, but requires that they 
    64 are parsed down to a single internal representation. This information can 
    65 then be exposed or transformed in a consistent manner, which facilitates 
    66 the creation of powerful Perldoc tools. 
    67  
    68 While a Perl 6 implementation might implement the PDOM such that it 
    69 exposes elements like Perl code blocks, comments and other parts of the 
    70 Perl AST as accesible through the PDOM, this document only describes 
    71 those elements that are specific to Perldoc model. 
    72  
    73 The information model (known as the Perldoc Object Model or PDOM) is 
    74 very nearly a superset the one that Perl 5's L<perlpod> implicitly defines. 
    75  
    76 A PDOM representation can be thought of as a tree of I<nodes>. There are 
    77 3 kinds of nodes: 
    78  
    79 =over 
    80  
    81 =item Text Nodes 
    82  
    83 Leaf nodes containing content text. 
    84  
    85 =item Collection Nodes 
    86  
    87 Nodes that contain other nodes. 
    88  
    89 =for comment 
    90     Changed "External" to "Opaque" meaning stuff that is recognized as 
    91     Perldoc, but is of a declared type for which there is no clarity to 
    92     inspect it any further. This clarity may come later, after which 
    93     point the node is then no longer opaque. --ingy 
    94  
    95 =item Opaque Nodes 
    96  
    97 Leaf nodes that are not recognized by the current state of the PDOM, but 
    98 may be resolved at some other time. This might include I<tables>, 
    99 I<images>, I<diagrams> or I<raw html>. Opaque nodes are typically 
    100 handled by PDOM extensions, described later on. 
    101  
    102 =for comment 
    103     Deleted Ignorable Nodes from the PDOM. The intent of ignorable is 
    104     significant whitespace for full roundtripping by syntax hilighters 
    105     an Perldoc editors. While this information should be reported by a 
    106     parser, its place in the PDOM is dubious, especially given that a 
    107     lot of other syntax level information is lost at this point. --ingy 
    108  
    109 =back 
    110  
    111 There are two categories of collection nodes: 
    112  
    113 =over 
    114  
    115 =item Block Nodes 
    116  
    117 These are nodes that correspond HTML C<DIV>s. They represent 
    118 things like I<paragraphs>, I<verbatim blocks>, and I<lists>. 
    119  
    120 =item Phrase Nodes 
    121  
    122 These are nodes that correspond to HTML C<SPAN>s. They represent 
    123 things like I<strong> or I<emphatic> text, I<inline code>, and I<links>. 
    124  
    125 =back 
    126  
    127 Each node has a I<type> that indicates what kind of data it holds. The 
    128 following is a list of standard nodes types that exist in the 
    129 PDOM model: 
    130  
    131     - Document      (the root container node) 
    132     - Blocks: 
    133         - Opaque        (some as yet opaque block content) 
    134         - Heading       (a section heading) 
    135         - Paragraph     (regular text to be formatted) 
    136         - Verbatim      (preformatted regular text) 
    137         - Annotation    (output as a footnote or other elaboration) 
    138         - Insertion     (documentation included from another file) 
    139         - Module        (the specification of a Perldoc extension) 
    140         - Data          (a data section for the surrounding code) 
    141         - Opaque        (an as yet unknown Perldoc block) 
    142         - Ulist         (an unordered, "bulleted" list) 
    143             - UlistItem     (an item in a Ulist) 
    144         - Olist         (an ordered, "numbered" list) 
    145             - OlistItem     (an item in a Olist) 
    146         - Dlist         (a list of term definitions) 
    147             - DlistItem     (an item in a Dlist) 
    148     - Phrases: 
    149         - Opaque        (some as yet opaque phrase content) 
    150         - Plaintext     (typically set in roman) 
    151         - Strong        (typically set in bold) 
    152         - Emphasis      (typically set in italic) 
    153         - Code          (typically set in fixed-width) 
    154         - Link          (an internal or external cross-reference) 
    155         - Nonbreaking   (preserves and doesn't break whitespace) 
    156         - Entity        (Unicode codepoint or XML entity) 
    157         - Indexer       (index entry, never shown inline) 
    158  
    159 =for comment 
    160     Lists need to be modeled as containers, even if the syntax to 
    161     specify them can be inferred. I'm modeling the exact 3 lists that 
    162     are modeled in Pod today. Also make a clear distinction between the 
    163     3 types of items which are semantically and syntacically different 
    164     from each other. I don't see the need to artificially conflate these 
    165     down to one node type. --ingy 
    166  
    167 Documents contain one or more blocks, which in turn contain one or more 
    168 phrases. Blocks may also contain nested blocks and phrases may contain nested 
    169 phrases. (Phrases do not contain nested blocks.) 
    170  
    171 =head1 PDOM API 
    172  
    173 PDOM defines both a serial API and a random access API for accessing 
    174 document content. 
    175  
    176 =head2 PDOM Serial API 
    177  
    178 Perldoc allows for SAX-style streamed parsing and emission of documents. 
    179 You can register callbacks on the various subclasses of Perldoc nodes, 
    180 which will be triggered whenever a component of the corresponding type 
    181 is parsed. 
    182  
    183 =for comment 
    184     Deleted the implementation specific PD class example, as it seems 
    185     not to be in scope here. --ingy 
    186  
    187 =head2 PDOM Random Access API 
    188  
    189 This API consists of functions that would likely look similar to 
    190 an XML/DOM API. 
    191  
    192 The various PDOMs will be available to Perl 6 at runtime through the 
    193 global variable C<%*DOC>, where each key of the hash will be a unique 
    194 identifier (likely a package or class name) and each value will be a 
    195 PDOM Document node. Also, the variable C<$*DOC> will contain a reference 
    196 to the current package's PDOM object, if available. 
    197  
    198 =head1 SYNTAX CONTAINMENT 
    199  
    200 Having discussed the information model that defines Perldoc, the 
    201 following sections detail the syntactic constraints necessary for using 
    202 Perldoc in various contexts, including Perl programs. 
    203  
    204 Various interpreters (including the Perl interpreter) need to 
    205 distinguish which characters in a file or stream are actual Perldoc 
    206 and which are irrelevant (typically because they're Perl code). 
    207  
    208 Regardless of the code or data in which it's embedded, every section of 
    209 Perldoc begins with a line whose first character (in column 1) is C<=>, 
    210 followed immediately by any Unicode identifier sequence, except 
    211 C<'cut'>. In other words, any line that matches the Perl 6 regex: 
    212  
    213      /^^ = <ident>/ 
    214  
    215 indicates the start of a section of Perldoc. 
    216  
    217 Each section of Perldoc ends at either: 
    218  
    219 =over 
    220  
    221 =item * 
    222  
    223 The Perldoc directive matching the directive that opened the section. For 
    224 example: at C<=end verbatim> if the section started with C<=begin verbatim>. 
    225  
    226 =item * 
    227  
    228 The first blank line, if the opening directive was not a C<=begin>, C<=doc>, 
    229 C<=pod>, or C<=kwid>. A blank line is a line that is either empty or that 
    230 contains only whitespace characters. 
    231  
    232 =item * 
    233  
    234 The special directive C<=cut> 
    235  
    236 =back 
    237  
    238 =for discussion 
    239     For that matter, I don't much like =pod, =doc, or =kwid either... 
    240  
    241  
    242 =head2 Explicit documentation regions 
    243  
    244 Perldoc also provides a directive that explicitly indicates the 
    245 start of an extended piece of documentation: 
    246  
    247      =doc <dialect> 
    248  
    249 =for discussion 
    250     Don't see the need for a =doc declarator.  Why not unify with =use, 
    251     and make modules powerful enough to do the general syntactic and 
    252     role-based switching. 
     20=for table 
     21    Maintainer:     Damian Conway <damian@conway.org> 
     22    Date:           9 Apr 2005 
     23    Last Modified:  7 Oct 2006 
     24 
     25 
     26=head1 Perldoc 
     27 
     28Perldoc is an easy-to-use markup language with a simple, consistent 
     29underlying document object model. Perldoc can be used for writing the 
     30documentation for Perl 5 and Perl 6, and for Perl programs and modules, 
     31as well as for other types of document composition. 
     32 
     33Perldoc allows for multiple syntactic I<dialects>, all of which map onto 
     34the same set of standard document objects. The standard dialect is named 
     35L<"Pod"|#The Pod Dialect>. 
     36 
     37 
     38=head1 The Pod Dialect 
     39 
     40I<Pod> is an evolution of Perl 5's Plain Ol' Documentation (POD) markup. 
     41Compared to Perl 5 POD, Perldoc's Pod dialect is much more uniform, 
     42somewhat more compact, and considerably more expressive. 
     43 
     44=head2 General syntactic structure 
     45 
     46Pod blocks are specified using I<directives>, which always start with an 
     47C<=> in the first column. Every Pod block directive may be written in 
     48any of three equivalent forms: I<delimited style>, I<paragraph style>, 
     49or I<abbreviated style>. 
     50 
     51 
     52=head3 Delimited blocks 
     53 
     54Delimited blocks are bounded by C<=begin> and C<=end> markers, both of 
     55which are followed by a valid identifierN<A valid identifier is a 
     56sequence of alphanumerics and/or underscores, beginning with an 
     57alphabetic or underscore>, which is the typename of the block. Typenames 
     58that are entirely lowercase (for example: C<=begin head1>) or entirely 
     59uppercase (for example: C<=begin SYNOPSIS>) are reserved. 
     60 
     61After the typename, the rest of the C<=begin> marker line is treated as 
     62configuration information for the block. This information is used in 
     63different ways by different types of blocks, and is specified using 
     64Perl6ish C<:key{value}> or C<< key=>value >> pairs (which must, of 
     65course, be constants since Perldoc is a specification language, not a 
     66programming language). 
     67See L<Synposis 2|http://dev.perl.org/perl6/doc/design/syn/S02.html#Literals> 
     68for a summary of the Perl 6 pair notation. 
     69 
     70The configuration section may be extended over subsequent lines by 
     71starting those lines with an C<=> in the first column followed by a 
     72horizontal whitespace character. 
     73 
     74The lines following the opening delimiter and configuration are the data 
     75or contents of the block, which continue until the block's C<=end> marker 
     76line. The general syntax is: 
     77 
     78=begin code :allow< R > 
     79     =begin R<BLOCK_TYPE>  R<OPTIONAL CONFIG INFO> 
     80     =                  R<OPTIONAL EXTRA CONFIG INFO> 
     81     R<BLOCK CONTENTS> 
     82     =end R<BLOCK_TYPE> 
     83=end code 
    25384 
    25485For example: 
    25586 
    256      =doc pod 
    257  
    258      =doc kwid 
    259  
    260      =doc markdown 
    261  
    262      =doc javadoc 
    263  
    264 If C<=doc> has no dialect qualifier, it is assumed to be the same dialect as 
    265 the previous C<=doc> region specified (it is an error if the first C<=doc> 
    266 doesn't specify a dialect). 
    267  
    268 =for discussion 
    269     I think bare =doc/=cut is just =begin/=end spelled badly.  All we need 
    270     to do is say that =use scopes to the end of the current =begin/=end block, 
    271     if any, or the rest of the file if not. 
    272  
    273  
    274 Normally a section of Perldoc finishes after the closing delimiter of its 
    275 directive, and the Perl interpreter goes back to parsing code: 
    276  
    277      sub foo { 
    278  
    279      =begin item * 
    280      The foo() subroutine has no useful purpose. 
    281      It's provided for backwards compatibility only. 
    282      Use the do_foo() sub instead. 
    283      =end item 
    284  
    285          goto &do_foo; 
    286      } 
    287  
    288 However, when a documentation region begins with a C<=doc> 
    289 directive, the documentation continues until the next C<=cut> directive 
    290 is encountered. That is, if the previous example had been written: 
    291  
    292      sub foo { 
    293  
    294      =doc pod 
    295      =begin item * 
    296      The foo() subroutine has no useful purpose. 
    297      It's provided for backwards compatibility only. 
    298      Use the do_foo() sub instead. 
    299      =end item 
    300  
    301          goto &do_foo; 
    302      } 
    303  
    304 then the last two lines would be treated as Pod, not Perl. 
    305  
    306  
    307 =for discussion 
    308     =begin without =end can do that too. 
    309  
    310  
    311 =head2 Code-specific regions 
    312  
    313 Perldoc defines two special directives that relate to the non-Perldoc 
    314 components of a file: C<=DATA> and C<=END>. 
    315  
    316 =for discussion 
    317     Why do they have to be special?  Data is not used often enough to 
    318     warrant short huffman coding.  And what if you want something to 
    319     be simultaneously data and a Perldoc component?  To me, data is just 
    320     a Perldoc component with a name or role that only the program is 
    321     (usually) interested in. 
    322  
    323 The C<DATA> directive creates a Perl DATA block within your document. Any Perl 
    324 code in the document can access this data via the special C<%=DATA> variable. 
    325 DATA blocks can be labelled (unlabelled DATA blocks have an empty string as 
    326 their implicit label): 
    327  
    328     =begin DATA Fibonacci 
    329     0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 
    330     1597, 2584, 4181, 6765, 10946, 17711, 28657, 46368, 75025, 121393, 
    331     196418, 317811, 514229, 832040, 1346269, 2178309, 3524578, 5702887, 
    332     9227465, 14930352, 24157817, 39088169 
    333     =end DATA 
    334  
    335     my $fib_seq = %DATA{Fibonacci}; 
    336  
    337 DATA blocks are included in the internal representation of a Perldoc document. 
    338 They are treated as a specific type of L<opaque block|"Opaque blocks">. 
    339  
    340 The C<=END> directive indicates the termination of the non-Perldoc component 
    341 of a file. Everything after that line until the end of the file is parsed 
    342 as Perldoc. In a sense, C<=END> is like C<=doc>, except that the Perldoc 
    343 region it introduces is not terminated by a C<=cut> (or anything else except 
    344 end-of-file). 
    345  
    346  
    347 =for discussion 
    348     more like: 
    349         =begin END 
    350     suppressing the warning of missing =end END 
    351  
    352  
    353 =head2 Standard Perldoc dialects 
    354  
    355  
    356 =begin question-for-damian 
    357  
    358 Why do we need this? 
    359  
    360 If: 
    361  
    362     =doc 
    363  
    364 means: 
    365  
    366     =doc kwid 
    367  
    368 after a previous `=doc kwid`, then we can just do: 
    369  
    370     =doc - Something 
    371  
    372     Some interesting point. 
    373     =cut 
    374  
    375 and we don't need to /bless/ Pod and Kwid as standard. 
    376  
    377  
    378 =end question-for-damian 
    379  
    380 =begin answer-from-larry 
    381     In my mental model that's just 
    382  
    383     =use  kwid 
    384     =begin 
    385     - Something 
    386     Some interesting point. 
    387     =end 
    388  
    389 =end answer-from-larry 
    390  
    391 The two standard Perldoc dialects (L<Pod|The Pod Dialect> 
    392 and L<Kwid|The Kwid Dialect>) have abbreviated markers: 
    393  
    394      =pod 
    395  
    396      =kwid 
    397  
    398 These are exactly equivalent in effect to: 
    399  
    400      =doc pod 
    401  
    402      =doc kwid 
    403  
    404 including the requirement for a C<=cut> to terminate their documentation 
    405 region. 
    406  
    407 However, any text following a C<=pod> or C<=kwid> marker on the same 
    408 line is considered to be the first line of the actual content. This 
    409 allows Kwid to do something like this: 
    410  
    411      =kwid - Something 
    412  
    413      Some interesting point. 
    414      =cut 
    415  
    416 which is semantically equivalent to: 
    417  
    418      =doc kwid 
    419      - Something 
    420  
    421      Some interesting point. 
    422      =cut 
    423  
    424 Note that the C<=doc>, C<=cut>, C<=pod>, and C<=kwid> lines are not 
    425 considered part of the Perldoc information (they are not seen by the API or 
    426 included in an internal representation). They are simply containment markers. 
    427  
    428  
    429 =for discussion 
    430     This seems like a relatively useless feature to me 
    431  
    432 =head2 File Containment 
    433  
    434 The above descriptions explain how how to distinguish the Perl from the 
    435 Doc, which assumes they are intertwingled in a Perl source code file. 
    436 Documentation can also live in a file by itself. 
    437  
    438 Perldoc considers files ending with C<.pod> to be documentation in the 
    439 Pod dialect and files ending with C<.kwid> to be in the Kwid dialect, 
    440 etc. A perldoc parser can look to the file extension for a dialect hint, 
    441 if no other clue is provided. 
    442  
    443 =for discussion 
    444     #!/usr/bin/pod 
    445     #!/usr/bin/kwid 
    446         vs 
    447     =use pod 
    448     =use kwid 
    449         as "first thing in file", or even P6-ish file-scoped declarator: 
    450     =use pod; 
    451     =use kwid; 
    452  
    453 This implies that the lines like: 
    454  
    455      =doc 
    456      =pod 
    457      =kwid 
    458      =cut 
    459  
    460 are not necessary in pure Perldoc files. In fact, in a Kwid file, they would 
    461 just be plain text. 
    462  
    463  
    464 =for discussion 
    465     Grumble, I don't think any of those are necessary in Pod files either... 
    466  
    467  
    468 =head1 SYNTAX DIALECTS 
    469  
    470 In the spirit of TMTOWTDI, Perldoc allows an author to choose a 
    471 documentation syntax that best suits them, without needing to worry 
    472 whether downstream processes and tools will be able to use it properly. 
    473 These variations of syntax are referred to as I<Perldoc Dialects>. 
    474  
    475 "Pod" is the Perldoc dialect that has evolved from Perl 5's "Plain Ol' 
    476 Documentation" markup. 
    477  
    478 "Kwid" is a Perldoc dialect that has evolved from wiki markup syntaxes. 
    479  
    480 Other dialects may be created or adapted by people who are fond of 
    481 neither Pod nor Kwid. 
    482  
    483 An XML dialect would be trivial to define since the PDOM can be thought 
    484 of as being an XML schema. Likewise an HTML dialect might be useful as a 
    485 formal syntax for creating Pod from HTML. 
    486  
    487 A WYSIWYG Perldoc editor could also be thought of as just another dialect. 
    488  
    489  
    490 =head1 The Pod Dialect 
    491  
    492 I<Pod> is an evolution of Perl 5's Plain Ol' Documentation markup. 
    493 Compared to Perl 5 POD, Perldoc's Pod dialect is much more uniform, 
    494 somewhat more compact, and slightly more expressive. 
    495  
    496  
    497 =head2 General syntactic structure 
    498  
    499 Pod blocks are specified using I<directives>. Every Pod block directive 
    500 may be written in any of three equivalent forms: I<delimited>, 
    501 I<paragraph>, and I<unlabelled>. 
    502  
    503  
    504 =head3 Delimited blocks 
    505  
    506 Delimited block directives are delimited by C<=begin> and C<=end> 
    507 markers, both of which are followed by the typename of the directive. 
    508 Typenames that are entirely upper-case or entirely lower-case are reserved for 
    509 Perldoc. External formatters (including users!) should use only mixed-case 
    510 typenames. 
    511  
    512 =for discussion 
    513     oops 
    514  
    515 The C<=begin> marker may also be followed by a multi-word label for the 
    516 block (which is used in different ways by different types of blocks). 
    517 The general syntax is: 
    518  
    519      =begin BLOCK_TYPE  OPTIONAL LABEL TEXT 
    520      BLOCK CONTENTS 
    521      =end BLOCK_TYPE 
    522  
    523 For example: 
    524  
    525      =begin Table  Table of Contents 
    526          Constants           1 
    527          Variables           10 
    528  
    529          Subroutines         33 
    530  
    531          Everything else     57 
    532      =end Table 
    533  
    534      =begin item Name 
    535      The applicant's full name 
    536      =end item 
    537  
    538      =begin item Contact 
    539      The applicant's contact details 
    540      =end item 
    541  
    542 Note that everything between the C<=begin> line and the C<=end> line is 
    543 considered to be the contents of the block. No blanks lines are 
    544 required around the directives, and blank lines within the contents are 
    545 treated as part of the contents. 
    546  
    547 =for discussion 
    548     I think we need to reserve some kind of modifier/adverbial syntax: 
    549         =begin Table :foo<bar> :title<Table of Contents> 
    550  
    551  
    552 =head3 Paragraph blocks 
    553  
    554 Paragraph block directives are introduced by a C<=for> marker and 
    555 terminated by the next Pod directive or the first blank line (which is 
    556 I<not> considered part of the block data). The C<=for> marker is 
    557 followed by the name of the directive and an optional label. The general 
    558 syntax is: 
    559  
    560      =for BLOCK_TYPE  OPTIONAL LABEL TEXT 
    561      BLOCK DATA 
    562  
    563 For example: 
    564  
    565      =for Table  Table of Contents 
     87     =begin table  :title<Table of Contents> 
    56688         Constants           1 
    56789         Variables           10 
    56890         Subroutines         33 
    56991         Everything else     57 
    570  
    571      =for item Name 
     92     =end Table 
     93 
     94     =begin Name  :required 
     95     =            :width(50) 
    57296     The applicant's full name 
    573  
    574      =for item Contact 
     97     =end Name 
     98 
     99     =begin Contact  :optional 
    575100     The applicant's contact details 
    576  
    577 =begin note-to-damian 
    578  
    579 I'm nervous about the ambiguity of =for. 
    580  
    581      =for item Blah Blah Blah Blah Blah 
    582      Blah Blah Blah Blah Blah Blah Blah 
    583  
    584 Where does the item element end and the description begin. Might be 
    585 wrap-fragile if you base it on newline. 
     101     =end Contact 
     102 
     103Note that no blank lines are required around the directives, and blank 
     104lines within the contents are always treated as part of the contents. 
     105 
     106Note also that in the following specifications, a "blank line" is a line that 
     107is either empty or that contains only whitespace characters. That is, a blank 
     108line matches C</^\s*?$/>. Pod uses blank lines, rather than empty lines, as 
     109delimiters (on the principle of least surprise). 
     110 
     111 
     112=head3 Paragraph blocks 
     113 
     114Paragraph blocks are introduced by a C<=for> marker and terminated by 
     115the next Pod directive or the first blank line (which is I<not> 
     116considered to be part of the block's contents). The C<=for> marker is 
     117followed by the name of the directive and optional 
     118configuration information. The general syntax is: 
     119 
     120=begin code :allow< R > 
     121     =for R<BLOCK_TYPE>  R<OPTIONAL CONFIG INFO> 
     122     =                R<OPTIONAL EXTRA CONFIG INFO> 
     123     R<BLOCK DATA> 
     124 
     125=end code 
    586126 
    587127For example: 
    588128 
    589     =head1 Surely this extra long wrapped line is really just one long 
    590     header line and: 
    591  
    592     This next paragraph doesn't start until here. 
    593  
    594 =end note-to-damian 
     129     =for table  :title<Table of Contents> 
     130         Constants           1 
     131         Variables           10 
     132         Subroutines         33 
     133         Everything else     57 
     134 
     135     =for Name  :required 
     136     =          :width(50) 
     137     The applicant's full name 
     138 
     139     =for Contact  :optional 
     140     The applicant's contact details 
    595141 
    596142Once again, blank lines are not required around the directive (this is a 
    … …  
    598144 
    599145 
    600 =for discussion 
    601     Unified handling of adverbials might help with this. 
    602  
    603  
    604 =head3 Unlabelled blocks 
    605  
    606 Unlabelled block directives are introduced by an C<'='> sign followed 
    607 immediately by the typename of the directive. The rest of the line is 
    608 treated as block data, rather than a block label. The content terminates at 
    609 the next Pod directive or the first blank line (which is not part of the 
    610 block data). The general syntax is: 
    611  
    612      =BLOCK_TYPE  BLOCK DATA 
    613      MORE BLOCK DATA 
     146=head3 Abbreviated blocks 
     147 
     148Abbreviated blocks are introduced by an C<'='> sign in the 
     149first column, which is followed immediately by the typename of the 
     150block. The rest of the line is treated as block data, rather than as 
     151configuration. The content terminates at the next Pod directive or the 
     152first blank line (which is not part of the block data). The general 
     153syntax is: 
     154 
     155=begin code :allow< R > 
     156     =R<BLOCK_TYPE>  R<BLOCK DATA> 
     157     R<MORE BLOCK DATA> 
     158 
     159=end code 
    614160 
    615161For example: 
    … …  
    621167         Everything else     57 
    622168 
    623      =item Name:    The applicant's full name 
    624      =item Contact: The applicant's contact details 
    625  
    626 Note that C<=begin>, C<=end>, C<=for>, and C<=cut> markers are 
    627 always considered to be intrinsic keywords, not unlabelled block 
    628 markers. Hence, you cannot specify unlabelled blocks of a type named 
    629 C<begin>, C<end>, or C<for>. Instead you have to write: 
    630  
    631      =begin cut 
    632      This is a C<cut> type block (whatever I<that> is!) 
    633      =end cut 
    634  
    635  
    636 =for discussion 
    637     So basically, 
    638         =foo bar 
    639     is simply sugar for 
    640         =for foo bar 
    641  
    642 The C<=pod> and C<=doc> markers are not labelled forms either (because 
    643 they are not terminated at the next blank line, but rather by a 
    644 C<=cut> directive). Nevertheless they I<do> each have fully delimited 
    645 forms as well: 
    646  
    647      =begin pod 
    648      ... 
    649      =end pod 
    650  
    651  
    652      =begin doc pod 
    653      ... 
    654      =end doc 
    655  
    656 These forms may be nested (see L<EMBEDDING DIALECTS>). 
     169     =Name     The applicant's full name 
     170     =Contact  The applicant's contact details 
    657171 
    658172 
    … …  
    660174 
    661175The three equivalent block specifications (delimited, paragraph, and 
    662 unlabelled) are treated identically by the documentation model, so you 
    663 can use whichever form is most convenient for a particular documentation 
    664 task. In the descriptions that follow, the unlabelled form will generally be 
    665 used, but should be read as standing for all three forms equally. 
    666  
    667 For example, although L<"Headings"> shows only: 
     176abbreviated) are treated identically by the underlying documentation 
     177model, so you can use whichever form is most convenient for a particul