Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Perl POD

Perl POD

I made this for work.

B559fa7e3fdd620222d18244c58f842c?s=128

Craig Treptow

August 15, 2013
Tweet

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