Pod(plain old documentation format, 링크)를 이용하여 펄 스크립트의 도움말을 만들어 보았다. Pod는 펄 프로그램이나 모듈의 documentation에 쓰이는 간단한 마크업 언어이다. 코드 내부에 문서를 직접 작성한다는 것이 특징인데, 코드가 아닌 텍스트 정보만을 저장한 .pod 파일을 만들어 활용할 수도 있다. 순수한 pod 문서의 사례는 리눅스 배포본이라면 다 갖고 있을 /usr/share/perl5/pod/perlpod.pod 파일(펄 안내서)을 참조하면 된다. 이 파일을 확인하려면 리눅스 명령행에서 'perldoc perlpod'를 입력하자. 이 문서(perlko)의 한글판은 여기에 있다.
코드 내부에 작성해 넣는 문서는 어떤 용도인가? 당연히 그 코드의 설명을 위한 것이다. 가령 펄에서 '#'로 시작하는 줄(주석)은 인터프리터가 해석하지 않고 지나가므로, 코드의 특정 부분을 설명하는 용도로 쓰인다. 그러나 이러한 방식의 정보는 코드를 텍스트 편집기로 열어야만 보인다. Pod는 코드 안에 작성되지만 실행을 통해서 화면에 일정한 형식을 갖추어 보기 좋은 형태로 뿌려진다. 따라서 코드의 설명서를 별도로 작성하는 수고를 덜어준다. 한글 Perl Maven 웹사이트의 Pod 소개문을 읽어 보면 개념을 잡는데 도움이 될 것이다.
요즘 가장 인기 있는 마크업 언어는 아마도 간단하고 문법이 쉬운 경량의 Markdown이 아닐까 한다. LaTeX도 마크업 언어의 일종으로 간주된다. 생명과학 전공자로서 LaTeX으로 학위논문을 썼던 나도 상당한 수준의 '뻘짓러'가 아니었을까? 도대체 왜 그랬었지?
엇, perlko 문서의 저자에 '신정식'이란 이름이 보인다. 현재 구글의 소프트웨어 엔지니어로 일하는, 내가 아는 그 Jungshik Shin이 맞을 것이다. 그는 인터넷의 한글화에 큰 공헌을 했던 것으로 알고 있다. Nerd와 Geek가 득실거렸던 대학교 1학년 때의 기숙사가 생각난다. 신정식과는 몇 개의 수업을 같이 들었었던 것 같다.
펄 스크립트 또는 모듈 내에 심은 pod 문서를 보려면 'perldoc <script명>'을 입력하는 것이 일반적이다. 그러나 도움말을 보기 위하여 다른 명령어를 또 불러야 한다는 것이 성가시다. 그래서 명령행에 인수가 없거나 혹은 '-h' 또는 '--help'라는 단일 인수가 주어졌을 때 내부적으로 'perldoc <스크립트>'를 실행하여 스크립트 내에 심어놓은 도움말이 출력되게 하였다. 명령어 바로 뒤에 연달아 입력하는 문자열을 option, switch, flag, argument 등으로 세분해야 한다고 믿는 사람도 있겠지만, 그건 별로 중요하지 않다.
Pod 공식 설명 문서만으로는 그 문법을 이해하기가 어려워서 Bio::Seq.pm을 편집기로 열어서 실제 사례를 참조하였다. Bio::Seq 파일의 위치를 알고 싶다면 다음과 같이 입력한다. Bio와 Seq 사이의 연속된 콜론 두 개는 디렉토리('/')를 의미한다. 따라서 Bio::Seq.pm 모듈 파일의 실제 이름은 Seq.pm이다. 'perldoc -l Bio::Seq.pm'이라 입력해도 결과는 같다.
$ perldoc -l Bio::SeqIO
/usr/local/share/perl5/Bio/SeqIO.pm
기술 문서를 마크다운으로 배포하는 것은 이상할 것이 없지만, 요즘 분위기에서는 pod 파일로 배포하기는 적합하지 않다. 그저 펄 스크립트 내에 심어서 설명 용도로 쓰는 것이 최선일 것이다.
댓글 없음:
댓글 쓰기