Skip to content

Latest commit

 

History

History
executable file
·
453 lines (326 loc) · 13.5 KB

perlpod.pod

File metadata and controls

executable file
·
453 lines (326 loc) · 13.5 KB

NAME

perlpod - plain old documentation

DESCRIPTION

pod������篏������吾�勉����í�潟�鴻�㋘�若�帥��pod�����<�ゃ�˨��罧笈�醇����̬˛�� 莨若�帥�������������ï����ɱ�阪�������í�若����������吾��紊���������障�����罧笈�純�˨� verbatim, command, ordinary text ��勌��腮勰�������������障�����

Verbatim Paragraph

�����勉�障�障�勖侊��純����������壔�ゃ�潟����潟��(��ゃ�障�����腥榊�純����帥���� 紮���障�c�⓾��������������������)��˨����c�☀��茘���������障�������帥�����8��˨�í���������� 篁勐����������⓾����勉�障�上�阪����������障�������号����ŝ����í�若�������������鴻�宴�若���� ��������障����������������ゃ�帥�ŝ����壔�˨�������������c����������壔�с����障��������\���\��с�� �����勌����勖����潟�壔�������障��������

Command Paragraph

�����鴻�⓾�勉�潟����潟��罧笈�純�壎��=�����у����障�c�⓾����勐����̬����ュ�����膓������� ��������˨�潟����潟��������綽�荀���������������㏍�鴻�����膓������障����� �憜��篏帥�������潟����潟����壚札筝���勰�������с�����

=head1 heading
=head2 heading
=item text
=over N
=back
=cut
=pod
=for X
=begin X
=end X
=pod
=cut

���=pod��������c�㋘�壔����c����壔��罨<�勈��=cunt�����障�с�潟�若����勤В������筝㊥�㏍����� ��ŝ�˨�������ŝ�������������潟�潟����ゃ�í�若�����腓冴����障�������������壔�潟�若�����pod��� 羞激����������翫����˨����㏍�ャ�<�潟�������ャ�勖侊��純��篁������������勉�˩梢��í�с�����

=head1
=head2

head1���head2��壔�����������膃㋙����㋘����˨��膃㋙����㋘����˨�勉����������若����� �����勉����c�㋘�壔����c�����������罧笈�純�˨����������㏍�鴻�����篏帥�c�☎����������障�����

=over
=back
=item

item, over, back��˨�壔�������<����c�◑ą������綽�荀���с��������=over�����壎��=item��� ��潟����潟�����篏帥�c�⓾�ŝ�鴻�������������������������勉�祉�壔�激�с�潟�����紮������障����� ��ŝ�鴻����勖��絨障�с�壔����祉�壔�激�с�潟��腟���������������������˧��=back�����潟����潟����� 篏帥����障�����筝������勉����í�若�������帥�若����ゃ�潟����潟����˩戎��������⓾��������4������ ���=over������絲障�������違�������☖�������������ŝ����с����������� ��ゃ�潟����潟����勖�違�壔�ŝ����激�с�潟�с����� ��違�����絎���������ŝ����c����翫����� �����í�若����������激�鴻����������ñ����������ɾ�吟�ŝ�ゃ�潟����潟�������������������障����� =item���篏帥�����綵�������綛障�ゃ����勐�堺�㋜����ŝ�˨�若�˨�� ���������������羈���������⓾��������������=over/=back�����㏍����壔�勐����眼�т戎��c�⓾� ��������障��������=over/=back�����㏍����壔�勌賢������篏�筝����=item������������������ ��ŝ�鴻����������˨����㏍�ャ�<�潟�����run off��������������ŝ��=back�����˨�����綽�荀���壔�������障�������� ��������⓾�����������紊�������������荀���ŝ�������с����������≪�ゃ�������˩��莢���с����������������������с����� ���=item *��������ゃ����c��bullets���篏帥�������� ���=item 1.���������=item 2.�����⓾�������〠�医�����篏帥�������� �����������壎��=item foo���������=item bar�����勉�������˨�í�<����с����ŝ�������勉�� 篏帥����˨�������� �����鴻�⓾�勉�≪�ゃ��������絲障����☗��腮勉�勉����勉��篏帥�c�⓾�������������� bullet ��ŝ����医�������������˩戎��c��������紊������勉����í�若�������帥�若����������勈��=item��� ��帥�ゃ�������ŝ�鴻�����篏���˩戎�����������˨��������篏帥����ゃ�ャ����⓾��������������

=for
=begin
=end

for, begin, end���pod�����㏍�鴻����������☀В��������������������勉�ŝ����祉�壔�激�с�潟�� ������莨若�帥�障�������������������������夌�劫����勉����í�若�������帥�若�̥�贋・羝<�������障����� �����í�若�������帥�若�壔����勉�������ŝ����í�若����������勉�祉�壔�激�с�潟����ñ�������������������с����障����� �����������壠�������̥�∴�������������������������с��������������=for��� �����c�㋘�壔����c����壔����������̥����閬笈�遵��篏�������=for�����勛�翫����˨����� ���茯���˨����c�〠��絎���������������í�若����������с�����������������絎������障�����箴������������障�����������

=for html <br>
 <p> This is a raw HTML paragraph </p>

腟������ŝ�c�⓾�������潟����潟�����=begin���������=end�����壎��=for�����◒��絽吾�̬�壔� 篌若�⓾����障�����������������筝���ゃ�勖侊��純��絲障����⓾�勉�翠�ñ�������������勉�с�壔�ŝ����� ���=begin���������=end�����勰����˨�����罧笈�純�������劫����勉����í�若���������� �����������������������宴����障�����

���������篏帥�c��箴����綛障�ゃ����������障�����������

=begin html

<br>Figure 1.<IMG SRC="figure1.png"><br>

=end html

=begin text

  ---------------
  |  foo        |
  |        bar  |
  ---------------

^^^^ Figure 1. ^^^^

=end text

�憜��篏帥����������勉�с����������í�若�������帥�若�勐��������"roff", "man", "latex", "tex", "text", "html"��с��(筝������勉����í�若�������帥�若�壚����勉����勉�勐�ュ���� �����〠�宴�������障��)���

��������☗�������ŝ����ф⓲��������������壔�������������勉�潟����潟�����篏帥�c����翫���������� ��潟����潟�����綵演�帥�������勉�壔�潟����潟�����臀勉��������茵���с�壔�ŝ����� ��潟����潟�����������罧笈����勛��腴壔�障�с�������������������с�������с�������������勌����˨�壔�� �����潟����潟����勐��������罧笈�純��腟�篋������������������̥Ã茵������������勉�с�����

綛障�ゃ��箴������������障��������:

=over 4

=item *

��������勉�≪�ゃ�����

=item *

篋���ɾ�勉�勉�≪�ゃ�����

=back

=over 4

=item Foo()

��∽�� Foo��勤ą��

=item Bar()

��∽�� Bar��勤ą��

=back

Ordinary Block of Text

(���絽吾�勉����㏍�鴻�������㏍�����)

荅違��莨若�帥��茵������������������������壠��膈���蚊��篁����(justified)���茵���������障����� �����眼�勉�激�若�宴�潟�鴻�勐江��ゃ����壔�潟����潟��筝㏍�с��茯�茘���������障��:

I<text>     �����㏍�鴻�������ゃ�帥�ŝ����壔�˨����障�����綣決Ě���紊���違�˩戎�����障��
B<text>     �����㏍�鴻����������若�˨����˨����障�������鴻�ゃ�������������㏍�違�í����˩戎�����障��
S<text>     �����俄���櫝�純�ŝ�鴻����若�鴻����˨�������㏍�鴻��
C<code>     ��潟�若�������帥�ゃ����í�ゃ�帥����í�潟�������障����
            �����勌����勉����㏍�違�í�������㏍�鴻�����茵◐憗��������羈���ф����祉����障��
L<name>     name���絲障�������ŝ�潟��(��壔�㏍�鴻�ŝ����<�㋘�潟��)
                    L<name>             ��������ャ�≪�˨����若�
                    L<name/ident>       ��������ャ�≪�˨�冴�若�娯賢��勉�≪�ゃ�����
                    L<name/"sec">       篁���勉�������ャ�≪�˨����若�吾�˨�������祉�壔�激�с�
                    L<"sec">            ��������������ャ�≪�˨����若�吾�勉�祉�壔�激�с�
                                        (��壔�í�若����夌����ュ櫝��)
                    L</"sec">           ���筝�
                筝���勉����勉�������������� 'text' �����������阪����˩戎���������
                (�����㏍�鴻����˨�� '/' ��� '>'�����˨�������������壔�с����障����������������
                '<'���'>'��勉����í�潟�鴻����������⓾����ŝ�������違�ŝ����障�����)
                    L<text|name>
                    L<text|name/ident>
                    L<text|name/"sec">
                    L<text|"sec">
                    L<text|/"sec">

F<file> �����<�ゃ�������˩戎�����障��
X<index>        膣√����勉����潟����
Z<>             綛���若�㏍�勉�㏍�c�í�壔�帥�
E<escape>   ������篁������勉�㏍�c�í�壔�帥��(HTML��勉����鴻�宴�若����̹�隙室)
                    E<lt>               ��ŝ����í�˨�� <
                    E<gt>               ��ŝ����í�˨�� >
                    E<sol>              ��ŝ����í�˨�� /
                    E<verbar>           ��ŝ����í�˨�� |
                    (�����������壔��篁���勐����眼�勉�激�若�宴�潟�鴻�с����c�����紊ф��絖����
                    ���茵������⓾�������翫����с�ŝ�������亥����ュ櫝��)
                    E<n>                ��㏍�c�í�壔�帥�主�ɱ�� n (������������ASCII)
                    E<html>             E<Agrave>��勉�������ŝ�������医�ゃ��HTML�����潟����c����

��������⓾����勐�翫�������������激�若�宴�潟�鴻�勖�����������緇���勉����ŝ����帥������� 1 腟���勐臼��㋚磁��勉�帥��綽�荀���с����� ��������������������激�若�宴�潟�鴻�勌賢����勀臼��㋚磁(��障����壠ぇ��ŝ��荐����'>')��� ��ャ����������翫�������������障�������������壔�潟�若����勖�㊦����勌賢��ч����������í�潟����帥�ゃ����� 篏帥����������������˨�������������障����� Perl ��̹�≪�����篁���勉�����������罕���˨����������������壔�蚊����ゃ�с�壔�������障�������� ��蚊����ゃ�勖�号����壠��膣���̹�������㋚磁��� E ��激�若�宴�潟�鴻��篏帥�c� �����鴻�宴�若����������号����с��:

C<$a E<lt>=E<gt> $b>

��������� "$a <=> $b" �����ŝ����障�����

������茯㏍�帥�������������������⓾�����������������"�����純��"��号����壔����ャ�勉����ŝ����帥�� 篏帥�c�⓾��">"��������鴻�宴�若�������ŝ����⓾����������������˨�������号����с����� Perl5.5.660 篁ラ�����2 �����勐臼��㋚磁 ("<<" and ">>")���篏帥����障����� 篏����������紮������ŝ����帥�勛�翫����◐��篋������ŝ����帥�勛�翫����̥Ã��純����������������������с��! 箴������違��篁ヤ����壔����勉����ŝ����壔��篏帥�c�⓾����障��:

C<< $a <=> $b >>

絎������勉��������������紮������ŝ����帥�◐��篋������ŝ����帥�勖�違����������c�⓾�������� ���紮������ŝ����帥�勖��緇���� '<' ��勛�翫����� 腟�篋������ŝ����帥�勖�������� '>' �� ��翫����̥Ã��純����ャ�c�⓾�������違�� 絮掩�㋚磁��勖�違�壔�������ゃ�с�������障����障�������� 緇���c�⓾��篁ヤ����勉����勉��罩c��������篏������障��:

C<<< $a <=> $b >>>
C<<<< $a <=> $b >>>>

��������夌憜����勉�������� pod2text (Pod::Text), pod2man (Pod::Man), �������� Pod::Parser 1.093 篁ラ�����篏睡�������⓾����������勌���� pod2xxx ��� Pod::Xxxx ���絲上�������⓾����障�����

The Intent

(��勛��)

��������������с�����綣桁����ŝ����勉�с�壔�ŝ�靎≦����ŝ����勉����勖�������⓾����障����� 罧笈�純�壩侊��純��������(��ï就���)荀������〠⓲��������勉�с��荀������勉�̥�勛����<�� fmt ��х亜�����������翫就��с�������������˨�ŝ�c�⓾����障�� (腱���� vi ��с� F7 ��˨�ŝ�c�⓾����障��)��� 腱����羆������⓾�������勉�壔��������莨若�障����������㏍�鴻����勌賢��� " ��� ' ���綏⓾�勉�壔�í�若�������� �劻�勉�壔�í�若�������� (腱���勌撮���������) 羂���c�c�⓾�������� �����í�潟�鴻�㋘�若�帥�с��verbatim ��≪�若����с�壔�壔�í�若����������勉�障�障�˨����⓾������� 罨蚊�������c����勉�с�������������������違��篏������������勉����㏍�違�í�������障��莨若����с�� 4 ��˨�í�������������⓾����������������勉�障�上�医�激�������違�������勉�с����������吟����� ��阪��綛���勉����í�潟����с��

��鴻�˨��篁ヤ����勉�������ŝ����勉�壔�������㏍�鴻��筝㏍�˨����勉�障�障�˨����⓾����������������с����障��:

Perl
FILEHANDLE
$variable
function()
manpage(3r)

��������������ャ�勉�潟����潟�������激�若�宴�潟�鴻��篁����莇潟����ŝ�������違�ŝ����ŝ����ŝ���������� ��������������勉�ŝ����������с����������������障�с�勉��������腱���壩�鎀���˨���������������� �����c�⓾�������勉�с�����

�����������㋘��篏������勉����������������ŝ�í�◑�������ゃ�������壠�������������障�������� 腱���壔����������ŝ�潟�í�ゃ�潟����㏍�ャ�<�潟����˩戎���nroff ���TeX��������c�������若�壔�≪�����荐�茯��� ��������勉��茯違�˨�с��篏帥�������演����勉�純�若�鴻��篏���������������⓾�������勉�с����� �憜�������������í�潟�鴻�㋘�若�帥�˨��pod2man (nroff(1) ��� troff(1)���), pod2text, pod2html, pod2latex, pod2fm�����������障�����

Embedding Pods in Perl Modules

(Perl��≪�吾�ャ�若�˨�吾��pod��勐�����莨若��)

Perl��鴻�壔�ŝ��������pod�����㏍�ャ�<�潟�����������莨若�������������с����障����� �����㏍�ャ�<�潟��������=head1�����潟����潟����у�����������=cut�����х�������障����� Perl��壔����勉��������pod�����㏍�鴻�������∴�������障����� 絎�箴���壔����ŝ����勌戎��c�⓾�������í�ゃ����í�ŝ�≪�吾�ャ�若�˨�˨�������障����� ������pod�����㏍�鴻����������<�ゃ�˨�勖��絨障�̥舟��������������������勉�с�������違�� __END__���__DATA__�����������˨����������若�壔��臀勉����� �����������������̥憗�����pod�����c�㋘�壔����c����勐����̥Ã茵����臀勉����������ц����������������с����障�����

__END__

=head1 NAME

modern - I am a modern module

腥肴�����臀勉����ŝ����c����翫����������í�潟�鴻�㋘�若�帥��pod�����㏍�鴻����� 荀�紊宴�c�⓾����障����с�����������

Common Pod Pitfalls

  • pod�����í�潟�鴻�㋘�若�帥�壔�����絽吾�壩侊��純�勐����蚊��絎������ɾÃ茵����綽�荀���������障����� 腥榊�純�勐�ャ�c��荀������勛Ã茵���勉�������ŝ����勉����ャ����������� ��阪�������������������ŝ����������������障��������

  • �����í�潟�鴻�㋘�若�帥�壔�祉�������í�勐�翫�� L<> ��ŝ�潟�壔�̬����勤申������茵������障����� �����勉�������������������� L<foo(1)> ��壎��the foo(1) manpage����� ��ŝ����障��(荅潟��������pod2man���������)��� �����������c�⓾�������ŝ����壠�������������������㏍�ャ�<�潟�����茯㏍�帥�������������勉�˨�������������˨�� the L<foo> manpage�����������吾����鴻�壔����鴻����с�壔�ŝ����勉�с�����

    �����ŝ����������㏍�鴻����勐�九勝�����⓾��綽�荀���������⓾�������ŝ����� ��阪����ŝ�潟�壔�勉�������˨� L<show this text|foo>���篏帥����障�����������

  • podchecker ��潟����潟����� pod ��勖��羈���̹�≪����������í�若�◑⑥������ �����с����壔�����������������箴���������⓾����障����� 箴������違��pod ��勐����蚊��絎������ɾÃ茵����篏帥�������⓾�������������� 筝������ŝ����鴻�宴�若����激�若�宴�潟�鴻�ŝ�í�������с����壔����障����� ��������с��筝���ゃ�障����虁����違�勉����í�潟�鴻�㋘�若�帥�̹�������☎�������������с����壔����������� 腟���������医�激����⓾�������������с����壔�������������������с�������障����� ��肴����������馹���勌賢��˨�壔�������帥����������������c�������������ŝ����c������������������� �����í�潟�鴻�㋘�若�帥�勉����違����������с�����������

SEE ALSO

pod2man, "PODs: Embedded Documentation" in perlsyn, podchecker

AUTHOR

Larry Wall