diff options
| author | Kenneth Albanowski <kjahds@kjahds.com> | 1996-12-24 23:00:10 -0500 |
|---|---|---|
| committer | Chip Salzenberg <chip@atlantic.net> | 1996-12-28 06:22:00 +1200 |
| commit | c7c9f95670eaf6ce7e8b31208e8675de7ad925dc (patch) | |
| tree | d028a428a6f66bde43dd876b868054d28fc0bd5a /pod/perlpod.pod | |
| parent | faed5253c819246b4a14ad96e661432a01a6974b (diff) | |
| download | perl-c7c9f95670eaf6ce7e8b31208e8675de7ad925dc.tar.gz | |
perlpod.pod patch for _16
This documents the new =for/=begin/=end behavior, and slightly changes the
emphasis on HTML in description of E<>, hopefully for the better.
p5p-msgid: <Pine.LNX.3.93.961224225906.337B-100000@kjahds.com>
Diffstat (limited to 'pod/perlpod.pod')
| -rw-r--r-- | pod/perlpod.pod | 43 |
1 files changed, 41 insertions, 2 deletions
diff --git a/pod/perlpod.pod b/pod/perlpod.pod index 9fb6b4e21b..5485f6c3b9 100644 --- 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> |