프로그래머들은 보통 문서작업을 싫어합니다. 그 이유 중 하나는 프로그램은 평범한 텍스트 파일인데 많은 경우 문서 작업을 워드 프로세서로 하도록 개발자에게 요구하기 때문입니다.
그러면 워드 프로세서를 배워야 하고, "좋은 내용을 담는" 것 대신에 "보기 좋게 만드는 것"에 많은 에너지를 소모하게 됩니다.
Perl에선 그렇지 않습니다. 보통은 여러분의 모듈의 문서를 그 모듈 소스 코드 안에 바로 적고, 보기 좋게 만드는 것은 외부의 도구에 의존합니다.
Perl 튜토리알의 이번 기사에서는 Perl 개발자들이 사용하는 마크업 언어인 POD - Plain Old Documentation에 대해 알아보겠습니다.
POD가 포함된 간단한 펄 코드 일부를 보면 다음과 같이 되어 있습니다:
#!/usr/bin/perl
use strict;
use warnings;
=pod
=head1 DESCRIPTION
이 스크립트는 2개의 파라메터를 받는다. 시스템의 이름 또는 주소와
명령어이다. 스크립트는 지정한 시스템 위에서 그 명령을 실행한 후
결과를 스크린에 출력한다.
=cut
print "Here comes the code ... \n";
이 코드를 script.pl 파일로 저장하고 perl script.pl처럼 실행하면
perl은 =pod와 =cut 사이의 내용을 무시하고 실제 코드만을 실행합니다.
반면에, 여러분이 perldoc script.pl라고 하면, perldoc 명령은 모든 코드를 무시하고
=pod와 =cut 사이의 내용을 가져와서, 특정한 규칙에 따라 서식을 맞춘 후, 스크린에
출력할 것입니다.
이 규칙들은 여러분이 사용하는 운영체제에 따라 달라지지만, 여러분이 Perl의 표준 문서에서 봤던 것들과 정확히 동일합니다.
코드에 포함되는 POD의 또다른 장점은, 문서가 모듈과 스크립트 안에 있기 때문에, 실수로 문서 없이 코드만 배포되는 일이 없다는 것입니다. 또한 여러분은 오픈 소스 펄 커뮤니티에서 직접 사용하려 만든 도구와 설비들을 재사용할 수 있습니다. 집에서 혼자 쓰는 경우에조차도 말이죠.
너무 간단한가요?
여기서 가정하고 있는 것은 문서를 작성하는데 걸림돌이 되는 것들 대부분을 제거하면 더 많은 사람들이 문서를 작성할 것이라는 점입니다. 보기에 멋있는 문서를 만들기 위해 워드 프로세서를 사용하는 법을 배우는 대신, 그저 몇 개의 기호가 추가된 텍스트로 작성하여 충분히 볼 만한 문서를 만들어낼 수 있습니다. (POD를 멋있게 가공한 형태를 보려면 Meta CPAN에 있는 문서들을 살펴보세요.)
마크업 언어
POD 마크업 언어의 상세 내용은 perldoc perlpod라고 입력하면 볼 수 있습니다만 매우 간단합니다.
=head1와 =head2 같은 몇 가지 태그가 있어서 "매우 중요함"과 "조금 덜 중요함"을
나타내는 헤더를 표시하는 데 쓰입니다. 들여쓰기를 제공하는 =over와 원형 강조점을 표시하는
=item, 그 외 몇 가지 태그가 더 있습니다.
=cut을 사용하여 POD 구간의 끝을 표시할 수 있고 =pod로 새 구간을 시작할 수
있습니다. 그러나 시작 태그는 엄격하게 요구되지는 않습니다.
한 행의 첫 글자가 등호 =로 시작하며 문자열이 이어질 경우 POD 마크업으로 해석되고
POD구역이 시작되며, =cut 태그가 나오면 끝나게 됩니다.
POD는 심지어 L<some-link> 표기를 써서 하이퍼링크를 넣을 수도 있습니다.
마크업 태그들 사이의 텍스트는 평범한 텍스트 단락으로 표시될 것입니다.
텍스트가 줄의 첫 글자부터 시작되지 않을 경우 이것은 수정 없이 다뤄집니다. 이 말은 여러분이 입력한 그대로 보이게 될 것이라는 뜻입니다: 긴 줄은 길게 짧은 줄은 짧은 채로 남아 있을 것입니다. 이것은 예제 코드를 표시하는 데 사용됩니다.
기억하셔야 할 점은 POD에서는 태그 앞뒤로 빈 줄이 있어야 한다는 점입니다. 따라서
=head1 Title
=head2 Subtitle
Some Text
=cut
위 코드는 기대한 대로 동작하지 않을 것입니다.
외양
POD는 마크업 언어이고 이 자체로는 내용이 어떻게 표시될지는 정의하고 있지 않습니다.
=head1는 뭔가 중요한 것을, =head2는 그보다는 덜 중요하다는 것을 의미할 뿐입니다.
POD를 출력하는 데 사용되는 도구들은 통상적으로 head1의 텍스트를 표시할 때는 head2의 텍스트를 표시할 때보다 더 큰 글자를 사용하고, head2의 내용 역시도 보통의 텍스트들 보다는 큰 글꼴로 표시됩니다. 이런 결정은 출력용 도구의 손에 달려 있습니다.
Perl에 딸려 있는 perldoc 명령어는 POD를 man 페이지처럼 출력합니다. 이것은 리눅스에는
꽤 유용합니다. 윈도우에서는 그렇게까지 좋지는 않습니다.
Pod::Html 모듈은 pod2html라는 명령행 도구를
제공합니다. 이것은 POD를 HTML 문서로 만들어서 브라우저에서 볼 수 있게 해줍니다.
POD를 가지고 pdf나 mobi 파일을 만드는 도구들도 있습니다.
청중이 누구인가?
기술적인 부분을 봤으니, 이제 문서를 읽을 대상이 누구인지 살펴봅시다.
주석(#으로 시작하는 내용)은 유지보수 담당 프로그래머를 위한 설명입니다. 기능을 추가하거나 버그를 수정할 사람이죠.
POD로 작성된 문서의 대상은 사용자입니다. 소스 코드를 들여다봐서는 안 될 사람들입니다. 응용프로그램의 경우는 "최종 사용자"라고 불리는 사람들일 것입니다. 누구든 될 수 있습니다.
Perl 모듈의 경우는, 모듈의 사용자는 응용프로그램이나 다른 모듈을 만들어야 하는
다른 Perl 프로그래머들입니다. 그들 역시도 여러분의 소스 코드를 들여다 봐야만 하는 일이
있어서는 안 됩니다. 단지 perldoc 명령어를 사용하여 문서를 읽어본 것만으로
여러분의 모듈을 사용할 수 있어야 합니다.
결론
Perl에서 문서를 만들고 그 문서를 보기 좋게 만드는 것은 그렇게 어렵지 않습니다.
