플레인 올드 도큐멘테이션

플레인 올드 도큐멘테이션(Plain Old Documentation, 간단히 pod)은 펄 프로그래밍 언어를 문서화하는데 쓰이는 가벼운 마크업 언어이다.

디자인

Pod는 충분히 유용한 문법만으로 단순하고 깔끔한 언어를 지향하며 설계되었다. 글꼴, 그림, 색, 테이블은 의도적으로 포함하지 않는다. 목표에는 다음이 포함된다:

구문 분석을 하기 쉬울 것
XML, TeX, 마크다운과 같은 다른 형식으로의 변환이 쉬울 것
샘플 코드 통합이 쉬울 것
pod 포매터가 없어도 (소스 코드 형태에서도) 읽기 쉬울 것
작성하기 쉬울 것

Pod는 매뉴얼 페이지 작성을 쉽게 하므로 사용자 지향 문서에 적합하다. 반면, 파이썬의 Docstring이나 자바의 Javadoc과 같은 다른 문서화 시스템들은 사용자 문서화를 위해 사용될 수는 있지만, 소프트웨어 프로젝트의 소스 코드에 대한 개발자 지향 문서화를 만드는데 이용하도록 설계되었다.

이용

Pod는 펄 세계에서 대부분의 문서화에 사용되는 언어이다. 여기에는 펄 자신과 대중에게 공개된 거의 모든 모듈, 수많은 스크립트, 대부분의 디자인 문서, 수많은 Perl.com의 문서, 기타 펄 관련 웹사이트, 패럿 가상 머신을 포함한다.

Pod는 별도의 포매팅 도구의 도움 없이도 읽을 수 있게 설계되어 있으나, 그대로 읽히는 잉른 드물다. 대신, perldoc이라는 도구로 읽거나 유닉스 man page나 웹 표준 HTML 문서로 변환한다.

펄 외의 다른 문맥에서 pod를 사용할 수도 있다. 이를테면, 배시 스크립트에 단순한 문서화를 추가하여 man page로 쉽게 변환하는 일을 들 수 있다.^[1]

예

이 문서는 문법적으로 올바른 pod이다.^[2]

소스 코드

=head1 NAME

My::Module - An example module

=head1 SYNOPSIS

    use My::Module;
    my $object = My::Module->new();
    print $object->as_string;

=head1 DESCRIPTION

This module does not really exist, it
was made for the sole purpose of
demonstrating how POD works.

=head2 Methods

=over 12

=item C<new>

Returns a new My::Module object.

=item C<as_string>

Returns a stringified representation of
the object. This is mainly for debugging
purposes.

=back

=head1 LICENSE

This is released under the Artistic
License. See L<perlartistic>.

=head1 AUTHOR

Juerd - L<http://juerd.nl/>

=head1 SEE ALSO

L<perlpod>, L<perlpodspec>

=cut