Perl POD

I made this for work.

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!!