1. Perl
  2. Syntax
  3. here

How 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


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.


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


How to format with POD.


To set it in bold, use the description "B & lt; & gt;".

B <aiueo>


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>


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".




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


  Source code example

Module description

=head1 METHODS

=head2 method 1

=head2 method 2

=head1 AUTHOR

Author name


Copyright notice


Detailed POD documentation

For detailed POD documentation, see Perl's POD documentation.

Related Informatrion