Perl POD 스타일 가이드
Perl POD 스타일 가이드 (perlpodstyle)
Perl 스크립트나 모듈의 문서를 POD로 작성할 때 어떻게 쓰면 좋을지를 정리한 스타일 가이드예요. 좋은 UNIX man 페이지를 쓰기 위한 일반 지침을 바탕으로 해요. 물론 이 모든 규칙은 권장 사항일 뿐 필수는 아니지만, 따르다 보면 문서가 시스템의 다른 문서들과 훨씬 일관성 있게 보여요.
본문
설명 (DESCRIPTION)
문서화하는 프로그램의 이름은 어디에 등장하든 관례상 B<>로 굵게 써요. 프로그램 옵션도 마찬가지예요. 인자(arguments)는 I<>로 이탤릭으로 써요. 함수 이름도 전통적으로 이탤릭으로 쓰는데, 함수를 function()처럼 괄호를 붙여 쓰면 Pod::Man이 알아서 정리해 줘요. 리터럴 코드나 명령어는 C<>로 감싸요.
다른 man 페이지를 참조할 때는 manpage(section) 또는 L<manpage(section)> 형태를 써요. 두 번째 형태(L<>)는 POD 포맷터가 가능하면 해당 man 페이지로 링크를 걸어 달라고 요청하는 거예요. 예외적으로, 모듈 문서를 참조할 때는 어떤 섹션에 들어갈지가 명확하지 않으므로 섹션을 생략하는 게 보통이에요. 모듈 참조는 L<Module::Name> 형태를 써요.
다른 프로그램이나 함수에 대한 참조는 보통 man 페이지 참조 형태로 써요. 그래야 교차 참조 도구가 사용자에게 링크를 제공할 수 있거든요. 다만 너무 과하게 쓰면 문서가 마크업으로 어수선해질 수 있으니 주의해야 해요. man 페이지 참조로 주지 않는 다른 프로그램 이름은 B<>로 감싸요.
주요 헤더는 =head1 지시어로 쓰고, 역사적으로는 다소 놀라운 전부 대문자(ALL UPPER CASE) 형식을 써 왔어요. 이것은 필수는 아니지만, 여러 소프트웨어 패키지 간에 섹션 이름을 일관되게 유지하려면 강력히 권장돼요. 하위 헤더는 =head2로 쓰고 보통 대소문자 혼용이에요.
man 페이지의 표준 섹션
NAME
필수 섹션이에요. 이 POD 페이지가 문서화하는 프로그램이나 함수의 쉼표로 구분된 목록이어야 해요. 예를 들면:
foo, bar - programs to do something
man 페이지 인덱서는 이 섹션의 형식에 유난히 까다로워요. 그래서 이 한 줄 외에는 아무것도 넣지 않는 게 좋아요. 이 POD 페이지가 문서화하는 모든 프로그램·함수를 쉼표와 공백으로 구분해 나열해야 해요. Perl 모듈이면 그냥 모듈 이름만 주면 돼요. 프로그램·함수 목록과 설명을 구분하는 대시는 단 하나만 써야 해요. 이 줄 어디에도 C<>나 B<> 같은 마크업을 쓰지 마세요. 함수 이름에 () 같은 걸 붙이지도 마세요. 설명은 가능하면 한 줄에 들어가게 쓰는 게 좋아요(man 프로그램이 대시를 몇 개의 탭으로 바꾸더라도요).
SYNOPSIS
프로그램과 함수의 짧은 사용 요약이에요. 섹션 3 페이지에는 필수예요. Perl 모듈 문서에서는 모듈의 전형적인 사용법을 보여주는 (간단한) 예시 몇 개를 verbatim 블록으로 넣는 게 보통 편해요.
DESCRIPTION
프로그램이나 함수에 대한 자세한 설명이자 논의예요. 또는 man 페이지의 본문이에요. 특히 길다면 =head2 지시어로 하위 섹션을 나누는 게 좋아요:
=head2 Normal Usage
=head2 Advanced Features
=head2 Writing Configuration Files
모듈이라면 보통 이 섹션에서 모듈이 제공하는 인터페이스를 문서화해요. 보통 각 인터페이스마다 =item 하나씩을 갖는 목록 형태예요. 인터페이스가 많다면 그 문서를 별도의 METHODS, FUNCTIONS, CLASS METHODS, INSTANCE METHODS 섹션에 넣고, DESCRIPTION 섹션은 개요(overview)용으로 남겨 두는 게 나을 수도 있어요.
OPTIONS
프로그램이 받는 각 명령줄 옵션에 대한 자세한 설명이에요. Pod::Usage 같은 파서가 사용할 수 있도록 이건 DESCRIPTION과 분리하는 게 좋아요. 보통 목록 형태로, 각 옵션을 별도의 =item으로 제시해요. 옵션 문자열은 B<>로 감싸고, 옵션이 받는 값은 I<>로 감싸요. 예를 들어 옵션 --section=manext의 섹션은 이렇게 시작해요:
=item B<--section>=I<manext>
동의어 옵션(짧은 형식과 긴 형식 같은)은 같은 =item 줄에서 쉼표와 공백으로 구분하거나, 각각을 자기 항목으로 두고 정식 이름을 참조하게 할 수도 있어요. --section이 -s로도 쓸 수 있다면 위는 이렇게 돼요:
=item B<-s> I<manext>, B<--section>=I<manext>
짧은 옵션을 먼저 쓰는 걸 권장해요. 읽기 쉽기 때문이에요. 긴 옵션은 어차피 길어서 눈에 띄고, 짧은 옵션은 시각적 잡음 속에 파묻힐 수 있거든요.
RETURN VALUE
프로그램이나 함수가 성공했을 때 무엇을 돌려주는지에 대한 설명이에요. 정확한 종료 코드가 중요하지 않은 프로그램이라면, 표준대로 성공 시 0을 반환하고 실패 시 0이 아닌 값을 반환한다는 전제 아래 이 섹션을 생략해도 돼요. 함수 문서에는 항상 있어야 해요. 모듈이라면 모듈 인터페이스의 반환 값을 여기 요약하는 게 유용할 수도 있고, 모듈이 제공하는 각 함수·메서드 문서에서 별도로 다루는 게 나을 수도 있어요.
ERRORS
예외, 오류 반환 코드, 종료 상태, errno 설정 등을 다뤄요. 보통 함수나 모듈 문서에 써요. 프로그램 문서는 대신 DIAGNOSTICS를 써요. 대략의 규칙은 이래요: 최종 사용자에게 보여주기 위해 STDOUT·STDERR로 출력되는 오류는 DIAGNOSTICS에, 호출 프로그램 내부로 전달되어 다른 프로그래머에게 전해지는 오류는 ERRORS에 기록해요. errno를 설정하는 함수를 문서화할 때는 가능한 errno 값 전체 목록을 여기 제시해야 해요.
DIAGNOSTICS
프로그램이 출력할 수 있는 모든 메시지와 그 의미예요. Perl 문서와 같은 문서 스타일을 따르고 싶다면 perldiag(1)을 보세요. 해당된다면, 사용자가 오류를 고치려면 어떻게 해야 하는지도 함께 적어 주세요. "입력 버퍼가 너무 작다"라고만 적고 버퍼 크기를 어떻게 늘리는지(또는 늘릴 수 없다는 것) 알려주지 않으면 그리 유용하지 않아요.
EXAMPLES
프로그램이나 함수의 사용 예시를 몇 개 주세요. 아끼지 마세요. 사용자들이 문서에서 가장 유용하다고 여기는 부분인 경우가 많아요. 예시는 보통 verbatim 문단으로 제시해요.
예시만 던져 놓지 말고 그것이 무엇을 하는지 설명해 주세요. 예시가 무엇을 하는지를 알려주는 짧은 문단 하나만 붙여도 예시의 가치가 엄청나게 올라가요.
ENVIRONMENT
프로그램이 신경 쓰는 환경 변수예요. 보통 =over, =item, =back으로 목록을 만들어 제시해요. 예:
=over 6
=item HOME
Used to determine the user's home directory. F<.foorc> in this
directory is read for configuration details, if it exists.
=back
환경 변수는 보통 전부 대문자라 별도의 특별한 포맷이 필요 없어요. 어차피 눈에 잘 띄거든요.
FILES
프로그램이나 함수가 사용하는 모든 파일과 그 용도예요. 보통 목록으로 제시하고, 파일 이름은 F<>로 감싸요. 특히 잠재적으로 수정될 수 있는 파일은 문서화하는 게 중요해요.
CAVEATS
특별히 주의할 점이에요. WARNINGS라고 부르기도 해요.
BUGS
깨져 있거나 제대로 동작하지 않는 것들이에요.
RESTRICTIONS
고칠 생각이 없는 버그들이에요. :-)
NOTES
잡다한 논평이에요.
AUTHOR
누가 썼는지(여러 명이면 AUTHORS)예요. 현재 이메일 주소(또는 버그 리포트를 보낼 이메일 주소)나 다른 연락처를 포함하는 게 좋아요. 문서는 예상보다 훨씬 오래 세상을 떠돌기 마련이니, 오래 지속될 연락 수단을 고르세요.
HISTORY
다른 소스에서 파생된 프로그램이 가끔 갖는 섹션이에요. 어떤 사람들은 여기 수정 로그를 남기는데, 보통 길어지기 쉬워서 별도 파일로 관리하는 게 낫죠.
COPYRIGHT AND LICENSE
저작권은:
Copyright YEAR(s) YOUR NAME(s)
(아니요, (C)는 필요 없어요. "all rights reserved"도 필요 없어요.)
라이선스의 가장 쉬운 방법은 Perl 자체와 같은 라이선스를 쓰는 거예요:
This library is free software; you may redistribute it and/or
modify it under the same terms as Perl itself.
이렇게 하면 사람들이 Perl과 함께 모듈을 쓰기 쉬워져요. 이 라이선스 예시는 권유도 요구도 아니라는 점을 기억하세요. 물론 어떤 라이선스든 자유롭게 고를 수 있어요.
SEE ALSO
확인할 다른 man 페이지들이에요. man(1), man(7), makewhatis(8), catman(8) 같은 것들이죠. 보통 쉼표로 구분된 man 페이지 목록이거나, 참고 문헌 이름을 주는 문단이에요. 표준 name(section) 형식을 쓰는 man 페이지 참조는 (권장되지만) L<>로 감쌀 필요는 없어요.
패키지에 메일링 리스트가 있으면 URL이나 구독 방법을 여기 넣어요. 웹사이트가 있으면 URL을 여기 넣어요.
객체 지향 라이브러리나 모듈 문서는 CONSTRUCTORS·METHODS 섹션 또는 CLASS METHODS·INSTANCE METHODS 섹션을 써서 라이브러리 구성요소를 자세히 문서화하고, DESCRIPTION 섹션은 개요용으로 남겨 둘 수도 있어요. 함수 인터페이스가 있는 큰 모듈도 비슷한 이유로 FUNCTIONS를 쓸 수 있어요. 어떤 사람들은 설명이 꽤 길면 OVERVIEW로 요약하기도 해요.
섹션 순서는 다양하지만, NAME은 반드시 첫 섹션이어야 해요(그렇지 않으면 일부 man 페이지 시스템이 깨져요). 또 NAME, SYNOPSIS, DESCRIPTION, OPTIONS는 있다면 보통 항상 처음에 그 순서로 나와요. 일반적으로 SEE ALSO, AUTHOR 등 비슷한 자료는 마지막으로 남겨 두는 게 좋아요. 어떤 시스템은 WARNINGS와 NOTES도 마지막으로 옮기기도 해요. 위에 제시한 순서가 대부분의 목적에 합리적이에요.
어떤 시스템은 표준 준수 여부를 적는 CONFORMING TO와 스레드 프로그램·시그널 핸들러에서 안전한지 적는 MT-LEVEL을 쓰기도 해요. 이 헤더들은 주로 C 라이브러리의 일부를 문서화할 때 유용해요.
마지막으로, 일반적으로 마크업을 과도하게 쓰지 마세요. 이 문서와 Pod::Man에 설명된 대로, Perl 변수·함수 이름·man 페이지 참조 같은 것들은 마크업 없이 그대로 두어도 POD 변환기가 알아서 처리해 줘요. 이렇게 하면 나중에 문서를 수정하는 게 훨씬 쉬워져요. 다만 많은 기존 변환기가 L<>로 감싼 이메일 주소를 잘못 처리하니, 이메일 주소를 L<>로 감싸지 마세요.
더 알아보기 (SEE ALSO)
시스템별로 더 정확할 수 있는 추가 정보는 시스템 man 섹션 번호 규칙에 따라 man(5) 또는 man(7)을 보세요.
이 문서는 podlators 배포판의 일부로 유지돼요. 최신 버전은 https://www.eyrie.org/~eagle/software/podlators/에서 항상 구할 수 있어요.