From: Kenneth Albanowski Date: Wed, 25 Dec 1996 04:00:10 +0000 (-0500) Subject: perlpod.pod patch for _16 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=c7c9f95670eaf6ce7e8b31208e8675de7ad925dc;p=p5sagit%2Fp5-mst-13.2.git 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: --- diff --git a/pod/perlpod.pod b/pod/perlpod.pod index 9fb6b4e..5485f6c 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
+

This is a raw HTML paragraph

+ +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 + +
Figure 1.
+ + =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, 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 Used for filenames X An index entry Z<> A zero-width character - E An HTML escape + E A named character (very similar to HTML escapes) E A literal < E A literal > (these are optional except in other interior sequences and when preceded by a capital letter) - E Character number n + E Character number n (probably in ASCII) E Some non-numeric HTML entity, such as E