Share
Embed
Transcript
16 slides
-
What is it? • POD - Plain Old Documentation •
A 'markup' language for writing documentation • Can be converted to plain text, HTML, man page, etc. -
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. -
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 -
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 -
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 -
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 -
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 -
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. -
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 -
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 -
Resources Cheat Sheet - M:/INTERDOC/Internet Programming Notes/POD cheat sheet.docx Documentation:
http://perldoc.perl.org/5.8.8 /perlpod.html