Perl POD

Transcript

1. Perl's POD Craig Treptow, August 2013

2. What is it? • POD - Plain Old Documentation •

   A 'markup' language for writing documentation • Can be converted to plain text, HTML, man page, etc.

3. 3 Basic Kinds of Paragraphs • Ordinary • Verbatim •

   Command

4. Ordinary Paragraph • Just plain text • Optional formatting codes

   Most paragraphs will just be this. Some text that you have typed, with blank lines before and after.

5. Verbatim Paragraph • Usually used for code examples • No

   formatting codes are allowed • Won't wrap • First line begins with spaces and/or tabs ◦ Normally, all lines begin this way

6. Command Paragraph • Used for special treatment of "chunks" of

   text • These are usually 1 line long • Commands recognized: =pod =head1-4 Heading Text (four levels) =over indentlevel =item stuff =back =begin format =end format =for format text... =encoding type =cut

7. Command Paragraph We’ll probably only use these: =pod =head1-4 Heading

   Text (four levels) =over indentlevel =item stuff =back =begin format =end format =for format text... =encoding type =cut

8. Formatting Codes I<text> -- italic B<text> -- bold C<code> --

   code L<text|name> -- hyperlink (name should not contain spaces) L<scheme:> -- URL E<escape> -- character escape F<filename> -- file name S<text> -- text contains non-breaking spaces (don't break across lines) X<topic name> -- index entry Z<> -- null

9. Miscellaneous Notes • =items are only used inside =over /

   =back regions • The first thing after an =over should be an =item • Don't put =head inside =over / =back regions • =item * - bullets • =item 1 , =item 2 , etc. - numbered lists

10. Where Does POD Go? • In it's own .pod file

    • In the .pl / .pm file ◦ Anywhere in the file ◦ After __END__ , but before __DATA__ ▪ If you are using __DATA__ Currently, we put our POD inside our Perl module or script.

11. Example =head1 _should_medical_be_excluded If certain classes are the only classes

    on a policy, then Medical should be set to 'Excluded'. This routine makes that decision. =head2 Inputs =over 4 =item * Array Reference - contains a list of classes =back =head2 Returns =over 4 =item * TRUE - Medical should be set to Excluded =item * FALSE - Medical should NOT be set to Excluded =back =cut

12. Example - HTML _should_medical_be_excluded If certain classes are the only

    classes on a policy, then Medical should be set to 'Excluded'. This routine makes that decision. Inputs • Array Reference - contains a list of classes Returns • TRUE - Medical should be set to Excluded • FALSE - Medical should NOT be set to Excluded

13. Tools OptiPerl • Tools->POD Extractor • Ctrl-P Good to preview

14. Results Check out the results at: file:///T:/documentation/index.html Generated every day

    over lunch.

15. Resources Cheat Sheet - M:/INTERDOC/Internet Programming Notes/POD cheat sheet.docx Documentation:

    http://perldoc.perl.org/5.8.8 /perlpod.html

16. Thank you!!