Perl ABCHow to write POD (Plain Old Documentation)
Perl allows you to embed documentation in your source code. This in-source document is called POD and has its own description method.
Perl has a site called CPAN where you can publish modules, but all module documentation published on CPAN is written in POD.
Let's think that POD can easily write HTML and is automatically converted to HTML.
Character code
If you want to include non-alphanumeric characters in the document, you need to set the character code. When writing in "UTF-8", write as follows at the beginning of the document.
= encoding utf8
Header
Corresponds to HTML h1 to h6.
=head1 Header 1 =head2 Header 2 =head3 header 3 =head4 Header 4 =head5 Header 5 =head6 Header 6
One thing to keep in mind when writing a POD is that you must insert a line break on the next line. For example, following statement does not work.
=head1 Header 1 =head2 Header 2
Source code
To write the source code, set a blank at the beginning of the source code. This corresponds to the HTML pre.
use DBIx::Custom; my $dbi = DBIx::Custom->connect(...);
The space can be 1, 2, or 4, and can be any width.
List
I will explain how to write a list.
Unordered list
The unordered list is written as follows:
After "= over", specify the indent width of the list. If you specify "*" after "= item", the list will be out of order. You must write "= back" at the end to indicate the end of "= over".
= over 4 = item * Item 1 = item * Item 2 = item * Item 3 = back
Order list
The sequence list is described as follows. It's almost the same as an unordered list, but if you specify a number after "= item", it becomes an ordered list.
= over 4 = item 1 Item 1 = item 2 Item 2 = item 3 Item 3 = back
Format
How to format with POD.
Bold
To set it in bold, use the description "B & lt; & gt;".
B <aiueo>
Italics
Use the description "I & lt; & gt;" to set italics.
I <aiueo>
Program text
You can use "C <>" if you want to format the function name in the text in a way that you can understand.
C <select>
Hyperlink
I will explain the notation of hyperlinks.
Other CPAN modules
To write a link to another CPAN module, use "L & lt; & gt;" and write:It will be a link to the Object::Simple page.
L <Object::Simple>
Links to general URLs
A general URL is described as "L & lt; text | URL & gt;".
L <Perl Seminar | http://d.hatena.ne.jp/perlcodeexample>
Start and end of POD
The start of POD ends with "=pod" and the end of POD ends with "=cut".
=pod document =cut
Generally, when even one description of POD such as "=head1" appears, POD starts, so it is rare to write "=pod". However, when using multi-line comment in the source code, this description method is used.
Character escape
If you want to use the symbols used in POD, you need to escape. Escape can be done using "".
E <lt> < E <gt >>
FAQ
FAQ about POD.
Is it possible to write a table in POD?
You cannot write a table in POD.
Is it possible to use images with POD?
Images are not available in POD.
What is the customary way to write on the CPAN module?
CPAN module documentation is generally written as follows:
=head1 NAME Module name-A brief description of the module =head1 SYNOPSIS Source code example =head1 DESCRIPTION Module description =head1 METHODS =head2 method 1 =head2 method 2 =head1 AUTHOR Author name =head1 COPYRIGHT & LICENSE Copyright notice =cut
Detailed POD documentation
For detailed POD documentation, see Perl's POD documentation.