Perl POD 형식

Perl POD 형식 (perlpod)

POD(Plain Old Documentation)는 Perl, Perl 프로그램, Perl 모듈의 문서를 쓰기 위한, 사용하기 쉬운 마크업 언어예요.

출처: Perl 공식 문서 - perlpod

본문

설명 (DESCRIPTION)

Pod를 평문 텍스트, HTML, man 페이지 등 다양한 형식으로 변환하는 번역기(translator)가 제공돼요.

Pod 마크업은 세 가지 기본 종류의 문단으로 이루어져요: 보통 문단(ordinary), verbatim 문단, 명령 문단(command).

보통 문단 (Ordinary Paragraph)

문서의 대부분 문단은 이 예시 같은 보통 텍스트 블록이에요. 어떤 마크업도 없이 텍스트만 입력하고, 앞뒤에 빈 줄 하나만 두면 돼요. 포맷될 때 최소한의 포맷(리랩, 비례 폰트 적용, 경우에 따라 좌우 정렬)만 거쳐요.

보통 문단에서 굵게, 이탤릭, 코드 스타일, 하이퍼링크 등을 위한 포맷 코드를 쓸 수 있어요. 그런 코드는 아래 "Formatting Codes" 섹션에서 설명해요.

Verbatim 문단 (Verbatim Paragraph)

Verbatim 문단은 보통 코드 블록이나, 특별한 파싱·포맷이 필요 없고 래핑되면 안 되는 텍스트를 제시할 때 써요.

verbatim 문단은 첫 문자가 공백이나 탭이면 구분돼요. (그리고 보통 모든 줄이 공백·탭으로 시작해요.) 정확히 재현되어야 하고, 탭은 8열 경계로 가정돼요. 특별한 포맷 코드가 없으므로 이탤릭 같은 걸 할 수 없어요. \는 그냥 \이고, 그 이상도 이하도 아니에요.

명령 문단 (Command Paragraph)

명령 문단은 텍스트 덩어리 전체를 특별히 처리할 때 써요. 보통 제목이거나 목록의 일부죠.

모든 명령 문단(보통 한 줄)은 "="로 시작하고, 식별자가 오고, 그 뒤에 명령이 마음대로 쓸 수 있는 임의의 텍스트가 와요. 현재 인식되는 명령은 다음과 같아요.

=pod
=head1 Heading Text
=head2 Heading Text
=head3 Heading Text
=head4 Heading Text
=head5 Heading Text
=head6 Heading Text
=over indentlevel
=item stuff
=back
=begin format
=end format
=for format text...
=encoding type
=cut

각각을 자세히 설명할게요.

`=head1` ~ `=head6` Heading Text

head1부터 head6까지는 제목을 만들고, head1이 가장 높은 레벨이에요. 이 문단의 나머지 텍스트가 제목의 내용이 돼요. 예:

=head2 Object Attributes

여기서 "Object Attributes"라는 텍스트가 제목이 돼요. 이 제목 명령의 텍스트는 아래처럼 포맷 코드를 쓸 수 있어요.

=head2 Possible Values for C<$/>

그런 명령은 아래 "Formatting Codes" 섹션에서 설명해요.

참고로 head5와 head6는 2020년, Pod::Simple 3.41(2020년 10월 릴리스)에서 도입됐어요. 그래서 사용 중인 Pod 파서에서는 지원되지 않을 수 있어요.

`=over _indentlevel_`, `=item _stuff..._`, `=back`

item, over, back는 조금 더 설명이 필요해요. "=over"는 "=item" 명령으로 목록을 만들거나, (그룹의) 보통 문단을 들여쓰기 위한 영역을 시작해요. 목록 끝에서 "=back"으로 끝내요. "=over"의 indentlevel 옵션은 얼마나 들여쓸지 나타내는데, 보통 em 단위(여기서 1em은 문서 기본 폰트의 "M" 폭) 또는 그와 비슷한 단위예요. indentlevel 옵션이 없으면 기본값은 4예요. (그리고 일부 포맷터는 제공한 _indentlevel_을 무시할 수도 있어요.) =item _stuff..._의 _stuff_에서 아래처럼 포맷 코드를 쓸 수 있어요.

=item Using C<$|> to Control Buffering

그런 명령은 아래 "Formatting Codes" 섹션에서 설명해요.

또한 "=over" ... "=back" 영역을 쓰는 몇 가지 기본 규칙이 있어요:

"=over" ... "=back" 영역 밖에서는 "=item"을 쓰지 마세요.
"=over" 명령 다음의 첫 번째는 "=item"이어야 해요. 단, 이 "=over" ... "=back" 영역에 아이템이 아예 없을 예정이라면 예외예요.
"=over" ... "=back" 영역 안에 "=head n" 명령을 넣지 마세요.
무엇보다 중요한 건 아이템을 일관성 있게 유지하는 거예요: 전부 "=item *"로 불릿을 만들거나, "=item 1.", "=item 2." 등으로 번호 목록을 만들거나, "=item foo", "=item bar" 같은 불릿도 번호도 아닌 것들을 쓰세요. (불릿·번호처럼 보이지 않는 것 1)과 불릿·번호처럼 보이는 것 2)을 모두 포함한 목록이 있다면, 불릿·번호처럼 보이는 아이템 앞에 Z<>를 붙여야 해요. 예시는 아래 Z<>를 보세요.)

불릿이나 번호로 시작했다면 계속 그걸 쓰세요. 포맷터가 첫 번째 "=item" 유형으로 목록을 어떻게 포맷할지 결정하거든요.

`=cut`

Pod 블록을 끝내려면 빈 줄, "=cut"으로 시작하는 줄, 그 뒤 빈 줄을 쓰세요. 이것은 Perl(과 Pod 포맷터)에게 여기서 Perl 코드가 다시 시작된다는 걸 알려줘요. ("=cut" 앞의 빈 줄은 기술적으로 필수는 아니지만, 많은 옛 Pod 프로세서가 요구해요.)

`=pod`

"=pod" 명령 자체는 별로 하는 게 없어요. 다만 Perl(과 Pod 포맷터)에게 여기서 Pod 블록이 시작한다는 걸 알려줘요. Pod 블록은 아무 명령 문단으로 시작하므로, "=pod" 명령은 보통 보통 문단이나 verbatim 문단으로 Pod 블록을 시작하고 싶을 때만 써요. 예:

=item stuff()

This function does stuff.

=cut

sub stuff {
  ...
}

=pod

Remember to check its return value, as in:

  stuff() || die "Couldn't do stuff!";

=cut

`=begin _formatname_`, `=end _formatname_`, `=for _formatname_ _text..._`

for, begin, end는 보통 Pod 텍스트로 해석되지 않고, 특정 포맷터에 직접 전달되거나 특별한 텍스트/코드/데이터 영역을 만들게 해 줘요. 그 형식을 쓸 수 있는 포맷터는 그 영역을 쓰고, 그렇지 않으면 완전히 무시돼요.

명령 "=begin formatname", 몇 개의 문단, 명령 "=end formatname"은 그 사이의 텍스트/데이터가 _formatname_이라는 특별한 형식을 이해하는 포맷터를 위한 것임을 의미해요. 예:

=begin html

<hr> <img src="thang.png">
<p> This is a raw HTML paragraph </p>

=end html

명령 "=for formatname text..."는 딱 이 문단의 나머지(formatname 바로 뒤부터)가 그 특별한 형식이라고 지정해요.

=for html <hr> <img src="thang.png">
<p> This is a raw HTML paragraph </p>

이것은 위의 "=begin html" ... "=end html" 영역과 같은 뜻이에요.

즉, "=for"로는 한 문단 분량의 텍스트만 가질 수 있지만("=foo targetname text..."의 텍스트), "=begin targetname" ... "=end targetname"으로는 그 사이에 얼마든지 가질 수 있어요. ("=begin" 명령 뒤에 빈 줄이, "=end" 명령 앞에 빈 줄이 반드시 있어야 한다는 점을 기억하세요.)

이 사용법의 몇 가지 예를 볼게요:

=begin html

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

=end html

=begin text

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

^^^^ Figure 1. ^^^^

=end text

포맷터가 현재 받아들인다고 알려진 몇 가지 형식 이름은 "roff", "man", "latex", "tex", "text", "html"이에요. (일부 포맷터는 이 중 일부를 동의어로 취급해요.)

"comment"라는 형식 이름은 Pod 문서의 어떤 포맷 버전에도 나타나지 않을 메모(아마 자기 자신에게)를 남기는 데 흔해요:

=for comment
Make sure that all the available options are documented!

일부 _formatname_은 앞에 콜론을 요구할 수도 있어요(":formatname" 같은). 이것은 텍스트가 raw 데이터가 아니라 Pod 텍스트임(즉 포맷 코드를 포함할 수 있음)을 알리는 신호예요. 다만 정상 포맷용은 아니고(예: 정상 사용 문단이 아니라 각주로 포맷될 수도 있음) 그렇죠.

`=encoding _encodingname_`

이 명령은 문서의 인코딩을 선언할 때 써요. 대부분 사용자는 필요 없지만, 인코딩이 US-ASCII가 아니라면 문서 아주 초반에 =encoding _encodingname_ 명령을 넣어서 pod 포맷터가 문서를 디코딩하는 법을 알게 해야 해요. _encodingname_으로는 Encode::Supported 모듈이 인식하는 이름을 써요. 일부 pod 포맷터는 Latin-1/CP-1252과 UTF-8 사이에서 추측하려 하지만 틀릴 수도 있어요. 엄격한 ASCII 외의 것을 쓰면 명시적으로 지정하는 게 가장 좋아요. 예:

=encoding latin1

=encoding utf8

=encoding koi8-r

=encoding ShiftJIS

=encoding big5

=encoding은 문서 전체에 영향을 주고, 반드시 한 번만 나와야 해요.

한 가지 잊지 마세요. =encoding을 제외한 모든 명령은 자기 줄이 아니라 자기 문단 끝까지 지속돼요. 아래 예시에서 볼 수 있듯 모든 명령은 문단을 끝내기 위해 뒤에 빈 줄이 필요해요. (일부 옛 Pod 번역기는 생략해도 합법적인데도 =encoding 줄 다음에 빈 줄을 요구할 수 있어요.)

목록의 몇 가지 예시를 볼게요:

=over

=item *

First item

=item *

Second item

=back

=over

=item Foo()

Description of Foo function

=item Bar()

Description of Bar function

=back

포맷 코드 (Formatting Codes)

보통 문단과 일부 명령 문단에서는 다양한 포맷 코드("내부 시퀀스(interior sequences)"라고도 함)를 쓸 수 있어요.

`I<text>` — 이탤릭 텍스트

강조("be I<careful!>")와 매개변수("redo I<LABEL>")에 써요.

`B<text>` — 굵은 텍스트

스위치("perl's B<-n> switch"), 프로그램("some systems provide a B<chfn> for that"), 강조("be B<careful!>") 등에 써요. ("and that feature is known as B<autovivification>" 같은)

`U<text>` — 밑줄 텍스트

2024년에 추가된 새 항목이라 모든 프로세서나 출력 형식에서 쓸 수 없을 수 있어요. 또한 일부 출력 형식은 이탤릭과 밑줄을 동시에 만들 수 없으므로, 둘 다 인식되더라도 시각적으로 구분되지 않을 수 있어요.

`C<code>` — 코드 텍스트

타자기 폰트로 코드를 렌더링하거나, 이것이 프로그램 텍스트("C<gmtime($^T)>") 또는 다른 형태의 컴퓨터 용어("C<drwxr-xr-x>")임을 나타내는 다른 표시를 줘요.

`L<name>` — 하이퍼링크

아래에 나열된 여러 문법이 있어요. 주어진 문법에서 text, name, section은 '/'와 '|' 문자를 포함할 수 없고, '<'나 '>'는 매치되어야 해요.

L<name> — Perl 매뉴얼 페이지로의 링크 (예: L<Net::Ping>). name에 공백이 없어야 해요. Unix man 페이지 참조에도 가끔 쓰여요. 예: L<crontab(5)>.
L<name/"sec"> 또는 L<name/sec> — 다른 매뉴얼 페이지의 섹션으로의 링크. 예: L<perlsyn/"For Loops">.
L</"sec"> 또는 L</sec> — 이 매뉴얼 페이지의 섹션으로의 링크. 예: L</"Object Methods">.

섹션은 이름이 붙은 제목이나 아이템으로 시작돼요. 예를 들어 L<perlvar/$.>와 L<perlvar/"$."> 모두 perlvar의 "=item $."로 시작하는 섹션에 링크해요. L<perlsyn/For Loops>와 L<perlsyn/"For Loops"> 모두 perlsyn의 "=head2 For Loops"로 시작하는 섹션에 링크해요.

표시할 텍스트를 제어하려면 "L<text|...>"를 써요:

L<text|name> — 이 텍스트를 그 매뉴얼 페이지에 링크. 예: L<Perl Error Messages|perldiag>.
L<text|name/"sec"> 또는 L<text|name/sec> — 이 텍스트를 그 매뉴얼 페이지의 그 섹션에 링크. 예: L<postfix "if"|perlsyn/"Statement Modifiers">.
L<text|/"sec"> 또는 L<text|/sec> 또는 L<text|"sec"> — 이 텍스트를 이 매뉴얼 페이지의 그 섹션에 링크. 예: L<the various attributes|/"Member Data">.

또는 웹 페이지에 링크할 수 있어요:

L<scheme:...> / L<text|scheme:...> — 절대 URL에 링크. 예: L<http://www.perl.org/> 또는 L<The Perl Home Page|http://www.perl.org/>.

`E<escape>` — 문자 이스케이프

HTML/XML의 &_foo_; "엔티티 참조"와 매우 비슷해요:

E<lt> — 리터럴 < (보다 작음)
E<gt> — 리터럴 > (보다 큼)
E<verbar> — 리터럴 | (수직 막대)
E<sol> — 리터럴 / (슬래시)

위 네 가지는 다른 포맷 코드 안(특히 L<...>)과 대문자 바로 뒤가 아니면 선택 사항이에요.

E<htmlname> — E<eacute>처럼, HTML의 é와 같은 뜻의 비숫자 HTML 엔티티 이름. 즉 acute(/모양) 악센트가 있는 소문자 e.
E<number> — 그 숫자의 ASCII/Latin-1/Unicode 문자. 앞의 "0x"는 _number_가 16진임을 의미해요(E<0x201E>처럼). 앞의 "0"은 8진임을 의미해요(E<075>처럼). 그 외에는 _number_가 10진으로 해석돼요(E<181>처럼).

옛 Pod 포맷터는 8진·16진 숫자 이스케이프를 인식하지 못할 수 있고, 많은 포맷터가 255보다 큰 문자를 신뢰성 있게 렌더링하지 못한다는 점을 기억하세요. (일부 포맷터는 Latin-1/CP-1252 문자를 타협한 렌더링으로 처리해야 할 수도 있어요. E<eacute>를 그냥 "e"로 렌더링하는 것처럼요.)

`F<filename>` — 파일 이름용

보통 이탤릭으로 표시돼요. 예: "F<.cshrc>"

`S<text>` — 비분리 공백을 포함한 텍스트

text 안의 단어가 줄바꿈에서 분리되면 안 된다는 뜻이에요. 예: S<$x ? $y : $z>.

`X<topic name>` — 인덱스 항목

대부분 포맷터가 무시하지만, 일부는 인덱스 구축에 쓸 수도 있어요. 항상 빈 문자열로 렌더링돼요. 예: X<absolutizing relative URLs>.

`Z<>` — 널(효과 없음) 포맷 코드

거의 안 쓰여요. 가끔 E<...> 코드를 쓰는 걸 피하는 한 방법이에요. 예를 들어 "NE<lt>3"(즉 "N<3") 대신 "NZ<><3"이라고 쓸 수 있어요. ("Z<>"가 "N"과 "<"를 분리해서 (가상의) "N<...>" 코드의 일부로 간주되지 않게 해요.)

또 하나의 용도는 =item Z<>_stuff..._의 _stuff_가 불릿이나 번호로 간주되지 않음을 나타내는 거예요. 예를 들어 Z<> 없이는:

=item Z<>500 Server error

이 줄이 번호 목록의 항목으로 파싱될 수 있는데, 그렇게 의도된 게 아닐 때가 있어요.

또 다른 용도는 =item 줄 사이의 시각적 공간을 유지하는 거예요. 다음을 지정하면:

=item foo

=item bar

보통 이렇게 렌더링돼요.

foo
bar

그게 원하는 것일 수도 있지만, 정말 원하는 게 이것이라면:

foo

bar

Z<>로 그걸 이룰 수 있어요.

=item foo

Z<>

=item bar

대부분의 경우 포맷 코드의 시작과 끝을 구분하는 데 한 쌍의 꺾쇠괄호만 있으면 돼요. 하지만 때로는 포맷 코드 안에 진짜 오른쪽 꺾쇠괄호('>')를 넣고 싶을 때가 있어요. 특히 코드 조각에 다른 폰트를 주기 위해 포맷 코드를 쓸 때 흔해요. Perl의 모든 것처럼, 하는 방법은 하나가 아니에요. 한 방법은 E 코드로 닫는 꺾쇠를 이스케이프하는 거예요:

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

이것은 "$a <=> $b"를 만들어요.

더 읽기 쉽고 아마 더 "plain"한 방법은 단일 ">"를 이스케이프할 필요가 없는 대체 구분자 집합을 쓰는 거예요. 이중 꺾쇠("<<"와 ">>")는 여는 구분자 바로 뒤에 공백이 있고 닫는 구분자 바로 앞에 공백이 있을 때에만 쓸 수 있어요! 예를 들어 다음이 트릭을 해내요:

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

사실 여는·닫는 구분자에 같은 수의 꺾쇠만 있고, 여는 구분자의 마지막 '<' 바로 뒤에 공백이, 닫는 구분자의 첫 '>' 바로 앞에 공백이 있다면(공백은 무시돼요) 얼마든지 반복된 꺾쇠를 쓸 수 있어요. 그래서 다음도 동작해요:

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

그리고 전부 이와 정확히 같아요:

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

여러 꺾쇠 형태는 포맷 코드 내용의 해석에 영향을 주지 않고, 어떻게 끝나야 하는지만 달라져요. 즉 위 예시들은 이것과도 정확히 같아요:

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

추가 예시로, 이 코드 조각들을 C(코드) 스타일로 넣고 싶다면:

open(X, ">>thing.dat") || die $!
$foo->bar();

이렇게 할 수 있어요:

C<<< open(X, ">>thing.dat") || die $! >>>
C<< $foo->bar(); >>

이것이 옛 방식보다 읽기 쉬울 거예요:

C<open(X, "E<gt>E<gt>thing.dat") || die $!>
C<$foo-E<gt>bar();>

이것은 현재 pod2text(Pod::Text), pod2man(Pod::Man), 그리고 Pod::Parser 1.093 이상 또는 Pod::Tree 1.02 이상을 쓰는 다른 pod2xxx/Pod::Xxxx 번역기에서 지원돼요.

의도 (The Intent)

의도는 사용의 단순함이지 표현의 힘이 아니에요. 문단은 문단처럼 보여서(블록 형식) 시각적으로 두드러지고, fmt로 쉽게 다시 포맷할 수 있게 했어요. 번역기가 verbatim 모드에서 ' . ` " 인용부호를 항상 그대로 두게 하고 싶었어요. 그래서 동작하는 프로그램을 긁어다가 4칸 들여쓰고 그대로(verbatim) 출력하게 하려는 거죠. 어쨌든 모노스페이스 폰트로요.

Pod 형식이 책을 쓰기에 반드시 충분한 건 아니에요. Pod는 nroff, HTML, TeX, 그 밖의 마크업 언어를 위한, 온라인 문서에 쓰이는 바보도 못 틀리게 하는 공통 원본으로 의도됐어요. pod2text, pod2html, pod2man(nroff(1)·troff(1)용), pod2latex, pod2fm 번역기가 있고, 다양한 다른 것들이 CPAN에 있어요.

Perl 모듈에 Pod 삽입하기 (Embedding Pods in Perl Modules)

Perl 모듈과 스크립트에 Pod 문서를 삽입할 수 있어요. 문서를 빈 줄로 시작하고 맨 앞에 "=head1" 명령을, "=cut" 명령과 빈 줄로 끝내세요. perl 실행 파일은 Pod 텍스트를 무시해요. perl이 새 문장의 시작을 기대하는 곳에는 Pod 문을 놓을 수 있지만, 문장 안에는 놓을 수 없어요(그러면 오류가 나요). 예시는 제공된 라이브러리 모듈 아무거나 보세요.

파일 끝에 Pod를 놓을 거고 __END__ 또는 __DATA__ 컷 마크를 쓴다면, 첫 번째 Pod 명령 앞에 빈 줄을 꼭 두세요.

__END__

=head1 NAME

Time::Local - efficiently compute time from local and GMT time

"=head1" 앞에 그 빈 줄이 없으면 많은 번역기가 "=head1"을 Pod 블록의 시작으로 인식하지 못했을 거예요.

Pod 작성 힌트 (Hints for Writing Pod)

podchecker 명령은 Pod 문법의 오류·경고를 검사할 때 제공돼요. 예를 들어 Pod 블록의 완전히 빈 줄, 알 수 없는 명령·포맷 코드를 검사해요. 그래도 문서를 하나 이상의 번역기에 통과시키고 결과를 교정하거나, 결과를 출력해서 교정해야 해요. 발견되는 문제 중 일부는 번역기의 버그일 수 있는데, 그걸 우회할지 말지는 여러분의 선택이에요.
HTML 작성이 Pod보다 익숙하다면, 간단한 HTML로 문서를 쓰고 실험적인 Pod::HTML2Pod 모듈(CPAN에 있음)로 Pod로 변환해 보고 결과 코드를 살펴볼 수 있어요. CPAN의 실험적 Pod::PXML 모듈도 유용할 수 있어요.
많은 옛 Pod 번역기는 모든 Pod 명령 앞뒤의 줄("=cut"도 포함!)이 빈 줄이어야 해요. 이렇게 돼 있으면:

# - - - - - - - - - - - -
=item $firecracker->boom()

This noisily detonates the firecracker object.
=cut
sub boom {
...

...그런 Pod 번역기는 Pod 블록을 전혀 보지 못할 거예요.

대신 이렇게 하세요:

# - - - - - - - - - - - -

=item $firecracker->boom()

This noisily detonates the firecracker object.

=cut

sub boom {
...

일부 옛 Pod 번역기는 문단("=head2 Functions" 같은 명령 문단 포함)이 완전히 빈 줄로 구분되어야 해요. 공백 몇 개가 있는 겉보기에 빈 줄은 그 번역기들에게 구분자로 세지 않아서 이상한 포맷이 될 수 있어요.
옛 번역기는 L<> 링크 주위에 문구를 추가해서 L<Foo::Bar>가 "the Foo::Bar manpage"가 될 수도 있어요. 그러니 번역된 문서가 말이 되게 하려면 the L<foo> documentation 같은 걸 쓰면 안 돼요. 대신 링크가 어떻게 나오는지 제어하려면 the L<Foo::Bar|Foo::Bar> documentation 또는 L<the Foo::Bar documentation|Foo::Bar>라고 쓰세요.
verbatim 블록에서 70번째 열을 넘어가면 일부 포맷터가 어색하게 래핑할 수 있어요.

더 알아보기 (SEE ALSO)

perlpodspec, "PODs: Embedded Documentation" in perlsyn, perlnewmod, perldoc, pod2html, pod2man, podchecker.

Perl POD 형식

Perl POD 형식 (perlpod)

본문

설명 (DESCRIPTION)

보통 문단 (Ordinary Paragraph)

Verbatim 문단 (Verbatim Paragraph)

명령 문단 (Command Paragraph)

=head1 ~ =head6 Heading Text

=over _indentlevel_, =item _stuff..._, =back

=cut

=pod

=begin _formatname_, =end _formatname_, =for _formatname_ _text..._

=encoding _encodingname_

포맷 코드 (Formatting Codes)

I<text> — 이탤릭 텍스트

B<text> — 굵은 텍스트

U<text> — 밑줄 텍스트

C<code> — 코드 텍스트

L<name> — 하이퍼링크

E<escape> — 문자 이스케이프

F<filename> — 파일 이름용

S<text> — 비분리 공백을 포함한 텍스트

X<topic name> — 인덱스 항목

Z<> — 널(효과 없음) 포맷 코드