Merge pull request #2496 from finanalyst/master

formating codes in pod

Author: JJ

doc/Language/pod.pod6

@@ -451,6 +451,9 @@ angle brackets; Unicode double angle brackets may be used.
 
 Formatting codes may nest other formatting codes.
 
+The following codes are available: B<B>, B<C>, B<E>, B<I>, B<K>, B<L>, B<N>, B<P>,
+B<R>, B<T>, B<U>, B<V>, B<X>, and B<Z>.
+
 =head2 Bold
 
 To format a text in bold enclose it in C<B< >>
@@ -517,6 +520,64 @@ Comments L<#Comments>
 
 L<Comments|#Comments>
 
+=head2 Placement links
+
+This code is not implemented in C<Pod::To::HTML>, but is partially implemented in C<Pod::To::BigPage>.
+
+A second kind of linkE<mdash>the C<P<>> or B<placement link>E<mdash>works
+in the opposite direction. Instead of directing focus out to another
+document, it allows you to assimilate the contents of another document
+into your own.
+
+In other words, the C<P<>> formatting code takes a URI and (where possible)
+inserts the contents of the corresponding document inline in place of the
+code itself.
+
+C<P<>> codes are handy for breaking out standard elements of
+your documentation set into reusable components that can then be
+incorporated directly into multiple documents. For example:
+
+    =COPYRIGHT
+    C<P><file:/shared/docs/std_copyright.pod>
+
+    =DISCLAIMER
+    C<P><http://www.MegaGigaTeraPetaCorp.com/std/disclaimer.txt>
+
+might produce:
+
+=begin nested
+B<Copyright>
+
+This document is copyright (c) MegaGigaTeraPetaCorp, 2006. All rights reserved.
+
+B<Disclaimer>
+
+ABSOLUTELY NO WARRANTY IS IMPLIED. NOT EVEN OF ANY KIND. WE HAVE SOLD
+YOU THIS SOFTWARE WITH NO HINT OF A SUGGESTION THAT IT IS EITHER USEFUL
+OR USABLE. AS FOR GUARANTEES OF CORRECTNESS...DON'T MAKE US LAUGH! AT
+SOME TIME IN THE FUTURE WE MIGHT DEIGN TO SELL YOU UPGRADES THAT PURPORT
+TO ADDRESS SOME OF THE APPLICATION'S MANY DEFICIENCIES, BUT NO PROMISES
+THERE EITHER. WE HAVE MORE LAWYERS ON STAFF THAN YOU HAVE TOTAL
+EMPLOYEES, SO DON'T EVEN *THINK* ABOUT SUING US. HAVE A NICE DAY.
+=end nested
+
+If a renderer cannot find or access the external data source for a
+placement link, it must issue a warning and render the URI directly in
+some form, possibly as an outwards link. For example:
+
+=begin nested
+B<Copyright>
+
+See: L<std_copyright.pod|file:/shared/docs/std_copyright.pod>
+
+B<Disclaimer>
+
+See: L<http://www.MegaGigaTeraPetaCorp.com/std/disclaimer.txt>
+=end nested
+
+You can use any of the following URI forms (see L<#Links>) in a
+placement link.
+
 =head2 Comments
 
 A comment is text that is never rendered.
@@ -545,6 +606,28 @@ Enter your name K<John Doe>
 
 Z<If used will bust Pod::To::BigPage>
 
+=head2 Replaceable
+
+The C<R<>> formatting code specifies that the contained text is a
+B<replaceable item>, a placeholder, or a metasyntactic variable. It is
+used to indicate a component of a syntax or specification that should
+eventually be replaced by an actual value. For example:
+
+=begin code :allow<B>
+    The basic C<ln> command is: C<ln> B<R<source_file> R<target_file>>
+=end code
+
+or:
+
+=begin code :allow<B>
+    Then enter your details at the prompt:
+
+    =for input
+        Name: B<R<your surname>>
+          ID: B<R<your employee number>>
+        Pass: B<R<your 36-letter password>>
+=end code
+
 =head2 Terminal output
 
 To flag text as terminal output enclose it in C<T< >>
@@ -576,6 +659,77 @@ Perl 6 makes considerable use of the E<0xAB> and E<0xBB> characters.
 
 Perl 6 makes considerable use of the « and » characters.
 
+=head2 Verbatim text
+
+This code is not implemented by C<Pod::To::HTML>, but is implemented in C<Pod::To::BigPage>.
+
+The C<V<>> formatting code treats its entire contents as being B<verbatim>,
+disregarding every apparent formatting code within it. For example:
+
+    The B<V< V<> >> formatting code disarms other codes
+    such as V< I<>, C<>, B<>, and M<> >.
+
+Note, however that the C<V<>> code only changes the way its
+contents are parsed, I<not> the way they are rendered. That is, the
+contents are still wrapped and formatted like plain text, and the
+effects of any formatting codes surrounding the C<V<>> code
+are still applied to its contents. For example the previous example
+is rendered:
+
+=nested
+The B<V< V<> >> formatting code disarms other codes
+such as V< I<>, C<>, B<>, and M<> >.
+
+=head2 Indexing terms
+
+Anything enclosed in an C<X<>> code is an B<index entry>. The contents
+of the code are both formatted into the document and used as the
+(case-insensitive) index entry:
+
+=begin code :allow<B>
+    An B<X<array>> is an ordered list of scalars indexed by number,
+    starting with 0. A B<X<hash>> is an unordered collection of scalar
+    values indexed by their associated string key.
+=end code
+
+You can specify an index entry in which the indexed text and the index
+entry are different, by separating the two with a vertical bar:
+
+=begin code :allow<B>
+    An B<X<array|arrays>> is an ordered list of scalars indexed by number,
+    starting with 0. A B<X<hash|hashes>> is an unordered collection of
+    scalar values indexed by their associated string key.
+=end code
+
+In the two-part form, the index entry comes after the bar and is
+case-sensitive.
+
+You can specify hierarchical index entries by separating indexing levels
+with commas:
+
+=begin code :allow<B>
+    An X<array|B<arrays, definition of>> is an ordered list of scalars
+    indexed by number, starting with 0. A X<hash|B<hashes, definition of>>
+    is an unordered collection of scalar values indexed by their
+    associated string key.
+=end code
+
+You can specify two or more entries for a single indexed text, by separating
+the entries with semicolons:
+
+=begin code :allow<B>
+    A X<hash|B<hashes, definition of; associative arrays>>
+    is an unordered collection of scalar values indexed by their
+    associated string key.
+=end code
+
+The indexed text can be empty, creating a "zero-width" index entry:
+
+=begin code :allow<B>
+    B<X<|puns, deliberate>>This is called the "Orcish Manoeuvre"
+    because you "OR" the "cache".
+=end code
+
 =head1 Rendering Pod
 
 =head2 HTML
@@ -673,4 +827,4 @@ Pod::Heading.new(level => 2, config => {}, contents => [Pod::Block::Para.new(con
 Pod::Block::Para.new(config => {}, contents => ["Here some text for the subsection."]);
 =end pod
 
-# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
+# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6