perlpod.pod patch for _16

diff --git a/pod/perlpod.pod b/pod/perlpod.pod

index 9fb6b4e..5485f6c 100644 (file)
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@@ -31,6 +31,9 @@ use however it pleases.  Currently recognized commands are
     =back
     =cut
     =pod
+    =for X
+    =begin X
+    =end X
 
 The "=pod" directive does nothing beyond telling the compiler to lay
 off of through the next "=cut".  It's useful for adding another 
@@ -53,6 +56,42 @@ or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use
 or numbers. If you start with bullets or numbers, stick with them, as many
 formatters use the first =item type to decide how to format the list.  
 
+For and begin/end let you include sections that are not interpreted as pod
+text, but in a format that a particular formatter is looking for. A
+formatter that can utilize that format will use the section, otherwise it
+will be completely ignored.  "=for" specifies that the entire paragraph
+should is in the format indicated by the first word after "=for", like this:
+
+ =for html <br> 
+  <p> This is a raw HTML paragraph </p>
+
+The paired commands "=begin" and "=end" work very similarly to =for, but
+instead of only accepting a single paragraph, all text from =begin to a
+paragraph with a matching =end are treated as a particular format. 
+
+Here are some examples of how to use these:
+
+ =begin html
+ 
+ <br>Figure 1.<IMG SRC="figure1.png"><br>
+ 
+ =end html
+ 
+ =begin text
+ 
+   ---------------
+   |  foo        |
+   |        bar  |
+   ---------------
+ 
+ ^^^^ Figure 1. ^^^^
+ 
+ =end text
+
+Some format names that formatters currently are known to accept include
+"roff", "man", "latex", "tex", "text", and "html". (Some formatters will
+treat some of these as synonyms.)
+
 And don't forget, when using any command, that that command lasts up until
 the end of the B<paragraph>, not the line. Hence in the examples below, you
 can see the blank lines after each command to end its paragraph.
@@ -103,12 +142,12 @@ here and in commands:
     F<file>    Used for filenames
     X<index>   An index entry
     Z<>         A zero-width character
-    E<escape>   An HTML escape
+    E<escape>   A named character (very similar to HTML escapes)
                    E<lt>               A literal <
                    E<gt>               A literal >
                    (these are optional except in other interior
                     sequences and when preceded by a capital letter)
-                   E<n>                Character number n
+                   E<n>                Character number n (probably in ASCII)
                    E<html>             Some non-numeric HTML entity, such
                                        as E<Agrave>