home *** CD-ROM | disk | FTP | other *** search
/ Amiga Magazin: Amiga-CD 1996 July / AMIGA_1996_7.BIN / ausgabe_7_96 / pd-programmierung / perl5_002bin.lha / man / catp / perlpod.0 < prev    next >
Text File  |  1996-03-02  |  12KB  |  265 lines
  1.  
  2.  
  3.  
  4. PERLPOD(1)     User Contributed Perl Documentation     PERLPOD(1)
  5.  
  6.  
  7. NNNNAAAAMMMMEEEE
  8.        perlpod - plain old documentation
  9.  
  10. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  11.        A pod-to-whatever translator reads a pod file paragraph by
  12.        paragraph, and translates it to the appropriate output
  13.        format.  There are three kinds of paragraphs:
  14.  
  15.        +o   A verbatim paragraph, distinguished by being indented
  16.            (that is, it starts with space or tab).  It should be
  17.            reproduced exactly, with tabs assumed to be on
  18.            8-column boundaries.  There are no special formatting
  19.            escapes, so you can't italicize or anything like that.
  20.            A \ means \, and nothing else.
  21.  
  22.        +o   A command.  All command paragraphs start with "=",
  23.            followed by an identifier, followed by arbitrary text
  24.            that the command can use however it pleases.
  25.            Currently recognized commands are
  26.  
  27.                ====hhhheeeeaaaadddd1111 hhhheeeeaaaaddddiiiinnnngggg
  28.                ====hhhheeeeaaaadddd2222 hhhheeeeaaaaddddiiiinnnngggg
  29.                ====iiiitttteeeemmmm tttteeeexxxxtttt
  30.                ====oooovvvveeeerrrr NNNN
  31.                ====bbbbaaaacccckkkk
  32.                ====ccccuuuutttt
  33.                ====ppppoooodddd
  34.  
  35.            The "=pod" directive does nothing beyond telling the
  36.            compiler to lay off of through the next "=cut".  It's
  37.            useful for adding another paragraph to the doc if
  38.            you're mixing up code and pod a lot.
  39.  
  40.            Head1 and head2 produce first and second level
  41.            headings, with the text on the same paragraph as
  42.            "=headn" forming the heading description.
  43.  
  44.            Item, over, and back require a little more
  45.            explanation: Over starts a section specifically for
  46.            the generation of a list using =item commands. At the
  47.            end of your list, use =back to end it. You will
  48.            probably want to give "4" as the number to =over, as
  49.            some formatters will use this for indention.  This
  50.            should probably be a default. Note also that there are
  51.            some basic rules to using =item: don't use them
  52.            outside of an =over/=back block, use at least one
  53.            inside an =over/=back block, you don't _have_ to
  54.            include the =back if the list just runs off the
  55.            document, and perhaps most importantly, keep the items
  56.            consistent: either use "=item *" for all of them, to
  57.            produce bullets, or use "=item 1.", "=item 2.", etc.,
  58.            to produce numbered lists, or use "=item foo", "=item
  59.            bar", etc., i.e., things that looks nothing like
  60.            bullets or numbers. If you start with bullets or
  61.  
  62.  
  63.  
  64. 23/Jan/96                perl 5.002 with                        1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PERLPOD(1)     User Contributed Perl Documentation     PERLPOD(1)
  71.  
  72.  
  73.            numbers, stick with them, as many formatters you the
  74.            first =item type to decide how to format the list.
  75.  
  76.            And don't forget, when using any command, that that
  77.            command lasts up until the end of the ppppaaaarrrraaaaggggrrrraaaapppphhhh, not
  78.            the line. Hence in the examples below, you can see the
  79.            blank lines after each command to end it's paragraph.
  80.  
  81.            Some examples of lists include:
  82.  
  83.             ====oooovvvveeeerrrr 4444
  84.  
  85.             ====iiiitttteeeemmmm ****
  86.  
  87.             FFFFiiiirrrrsssstttt iiiitttteeeemmmm
  88.  
  89.             ====iiiitttteeeemmmm ****
  90.  
  91.             SSSSeeeeccccoooonnnndddd iiiitttteeeemmmm
  92.  
  93.             ====bbbbaaaacccckkkk
  94.  
  95.             ====oooovvvveeeerrrr 4444
  96.  
  97.             ====iiiitttteeeemmmm FFFFoooooooo(((())))
  98.  
  99.             DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn ooooffff FFFFoooooooo ffffuuuunnnnccccttttiiiioooonnnn
  100.  
  101.             ====iiiitttteeeemmmm BBBBaaaarrrr(((())))
  102.  
  103.             DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn ooooffff BBBBaaaarrrr ffffuuuunnnnccccttttiiiioooonnnn
  104.  
  105.             ====bbbbaaaacccckkkk
  106.  
  107.  
  108.        +o   An ordinary block of text.  It will be filled, and
  109.            maybe even justified.  Certain interior sequences are
  110.            recognized both here and in commands:
  111.  
  112.                IIII<<<<tttteeeexxxxtttt>>>>     iiiittttaaaalllliiiicccciiiizzzzeeee tttteeeexxxxtttt,,,, uuuusssseeeedddd ffffoooorrrr eeeemmmmpppphhhhaaaassssiiiissss oooorrrr vvvvaaaarrrriiiiaaaabbbblllleeeessss
  113.                BBBB<<<<tttteeeexxxxtttt>>>>     eeeemmmmbbbboooollllddddeeeennnn tttteeeexxxxtttt,,,, uuuusssseeeedddd ffffoooorrrr sssswwwwiiiittttcccchhhheeeessss aaaannnndddd pppprrrrooooggggrrrraaaammmmssss
  114.                SSSS<<<<tttteeeexxxxtttt>>>>     tttteeeexxxxtttt ccccoooonnnnttttaaaaiiiinnnnssss nnnnoooonnnn----bbbbrrrreeeeaaaakkkkiiiinnnngggg ssssppppaaaacccceeeessss
  115.                CCCC<<<<ccccooooddddeeee>>>>     lllliiiitttteeeerrrraaaallll ccccooooddddeeee
  116.                LLLL<<<<nnnnaaaammmmeeee>>>>     AAAA lllliiiinnnnkkkk ((((ccccrrrroooossssssss rrrreeeeffffeeeerrrreeeennnncccceeee)))) ttttoooo nnnnaaaammmmeeee
  117.                                LLLL<<<<nnnnaaaammmmeeee>>>>             mmmmaaaannnnppppaaaaggggeeee
  118.                                LLLL<<<<nnnnaaaammmmeeee////iiiiddddeeeennnntttt>>>>       iiiitttteeeemmmm iiiinnnn mmmmaaaannnnppppaaaaggggeeee
  119.                                LLLL<<<<nnnnaaaammmmeeee////""""sssseeeecccc"""">>>>       sssseeeeccccttttiiiioooonnnn iiiinnnn ooootttthhhheeeerrrr mmmmaaaannnnppppaaaaggggeeee
  120.                                LLLL<<<<""""sssseeeecccc"""">>>>            sssseeeeccccttttiiiioooonnnn iiiinnnn tttthhhhiiiissss mmmmaaaannnnppppaaaaggggeeee
  121.                                                    ((((tttthhhheeee qqqquuuuooootttteeeessss aaaarrrreeee ooooppppttttiiiioooonnnnaaaallll))))
  122.                                LLLL<<<<////""""sssseeeecccc"""">>>>           ddddiiiittttttttoooo
  123.                FFFF<<<<ffffiiiilllleeee>>>>     UUUUsssseeeedddd ffffoooorrrr ffffiiiilllleeeennnnaaaammmmeeeessss
  124.                XXXX<<<<iiiinnnnddddeeeexxxx>>>>    AAAAnnnn iiiinnnnddddeeeexxxx eeeennnnttttrrrryyyy
  125.                ZZZZ<<<<>>>>         AAAA zzzzeeeerrrroooo----wwwwiiiiddddtttthhhh cccchhhhaaaarrrraaaacccctttteeeerrrr
  126.  
  127.  
  128.  
  129.  
  130. 23/Jan/96                perl 5.002 with                        2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PERLPOD(1)     User Contributed Perl Documentation     PERLPOD(1)
  137.  
  138.  
  139.            That's it.  The intent is simplicity, not power.  I
  140.            wanted paragraphs to look like paragraphs (block
  141.            format), so that they stand out visually, and so that
  142.            I could run them through fmt easily to reformat them
  143.            (that's F7 in my version of vvvviiii).  I wanted the
  144.            translator (and not me) to worry about whether " or '
  145.            is a left quote or a right quote within filled text,
  146.            and I wanted it to leave the quotes alone dammit in
  147.            verbatim mode, so I could slurp in a working program,
  148.            shift it over 4 spaces, and have it print out, er,
  149.            verbatim.  And presumably in a constant width font.
  150.  
  151.            In particular, you can leave things like this verbatim
  152.            in your text:
  153.  
  154.                PPPPeeeerrrrllll
  155.                FFFFIIIILLLLEEEEHHHHAAAANNNNDDDDLLLLEEEE
  156.                $$$$vvvvaaaarrrriiiiaaaabbbblllleeee
  157.                ffffuuuunnnnccccttttiiiioooonnnn(((())))
  158.                mmmmaaaannnnppppaaaaggggeeee((((3333rrrr))))
  159.  
  160.            Doubtless a few other commands or sequences will need
  161.            to be added along the way, but I've gotten along
  162.            surprisingly well with just these.
  163.  
  164.            Note that I'm not at all claiming this to be
  165.            sufficient for producing a book.  I'm just trying to
  166.            make an idiot-proof common source for nroff, TeX, and
  167.            other markup languages, as used for online
  168.            documentation.  Translators exist for ppppoooodddd2222mmmmaaaannnn  (that's
  169.            for _n_r_o_f_f(1) and _t_r_o_f_f(1)), ppppoooodddd2222hhhhttttmmmmllll, ppppoooodddd2222llllaaaatttteeeexxxx, and
  170.            ppppoooodddd2222ffffmmmm.
  171.  
  172. EEEEmmmmbbbbeeeeddddddddiiiinnnngggg PPPPooooddddssss iiiinnnn PPPPeeeerrrrllll MMMMoooodddduuuulllleeeessss
  173.        You can embed pod documentation in your Perl scripts.
  174.        Start your documentation with a =head1 command at the beg,
  175.        and end it with an =cut command.  Perl will ignore the pod
  176.        text.  See any of the supplied library modules for
  177.        examples.  If you're going to put your pods at the end of
  178.        the file, and you're using an __END__ or __DATA__ cut
  179.        mark, make sure to put a blank line there before the first
  180.        pod directive.
  181.  
  182.            ________EEEENNNNDDDD________
  183.  
  184.            ====hhhheeeeaaaadddd1111 NNNNAAAAMMMMEEEE
  185.  
  186.            mmmmooooddddeeeerrrrnnnn ---- IIII aaaammmm aaaa mmmmooooddddeeeerrrrnnnn mmmmoooodddduuuulllleeee
  187.  
  188.        If you had not had that blank line there, then the
  189.        translators wouldn't have seen it.
  190.  
  191. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  192.        the _p_o_d_2_m_a_n manpage and the section on _P_O_D_s_: _E_m_b_e_d_d_e_d
  193.  
  194.  
  195.  
  196. 23/Jan/96                perl 5.002 with                        3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PERLPOD(1)     User Contributed Perl Documentation     PERLPOD(1)
  203.  
  204.  
  205.        _D_o_c_u_m_e_n_t_a_t_i_o_n in the _p_e_r_l_s_y_n manpage
  206.  
  207. AAAAUUUUTTTTHHHHOOOORRRR
  208.        Larry Wall
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262. 23/Jan/96                perl 5.002 with                        4
  263.  
  264.  
  265.