Perl/POD

Perl POD

1. perlpod 정리

1.1. Ordinary Paragraph

1.2. Verbatim Paragraph

1.3. Command Paragraph

1.4. Formatting Codes

1.5. The Intent

1.6. Embedding Pods in Perl Modules

1.7. Hints for Writing Pod

1.8. 참고

2. 한글

3. 기타 & Comments

1. perlpod 정리

1.1. Ordinary Paragraph

• 일반적인 단락.
• 단락 전후에 빈 줄이 있어야 함
• 자동 줄바꿈, 글꼴 여백 조정, 정렬 등의 최소한의 효과만 적용됨

• 포매팅 코드를 사용하여 여러 가지 효과를 줄 수 있음.

1.2. Verbatim Paragraph

• 단락의 첫 글자가 공백이나 탭으로 시작 (보통은 단락의 모든 행을 공백이나 탭으로 시작하게 작성)

• 코드블록를 나타낼 때
• 특별한 처리나 포매팅 적용이 되지 않고 텍스트 원문을 그대로 보이고 싶을 때
• 아무런 포매팅이 적용되지 않음

1.3. Command Paragraph

• 표제, 목록 등 특별한 처리를 하도록 지시

• =식별자 추가텍스트 형태
• 현재 지원되는 명령들:

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

 =head1 Heading Text
 =head2 Heading Text
 =head3 Heading Text
 =head4 Heading Text

• 표제를 생성:

=head2 Object Attributes

• head3과 head4는 오래된 Pod 번역기에서 지원하지 않을 수 있음
• 표제의 텍스트에도 포매팅 코드를 사용 가능:

=head2 Possible Values for C<$/>

 =over indentlevel
 =item stuff...
 =back

• "=item"을 사용하여 생성한 목록이 들어있을 영역을 지정할 때 사용
• 일반 단락들을 그룹지어 들여쓸 영역을 지정할 때도 사용
• "=over"로 시작해서 "=back"으로 끝냄
• indentlevel은 얼마나 들여쓸지를 나타냄. (어떤 포매터에서는 무시됨)
• stuff에는 포매팅 코드 사용 가능:

=item Using C<$|> to Control Buffering

• "=over" ... "=back" 영역을 사용할 때 적용되는 규칙
  • "=item"을 영역 밖에서 사용하지 말 것
  • 영역 내에 "=item"이 하나라도 있을 경우는, "=over" 명령 바로 다음에 "=item"이 나와야 한다.
  • 영역 안에는 "=headn" 명령을 두지 말 것
  • (중요) 아이템을 일관성 있게 표시할 것. 한 영역 안에서 다음 세 가지 중 하나를 택해서 그것만 사용하라.
    • "=item *" - 번호 없는 리스트
    • "=item 숫자." - 번호 있는 리스트
    • "=item foo", "=item bar" 등 - 불릿이나 번호가 없는 리스트

 =cut

• Pod 블록을 종료하고 Perl 코드가 다시 진행됨을 알림
• 빈 줄, "=cut", 빈 줄 형태로 쓸 것

 =pod

• Pod 블록이 시작됨을 알림.
• 아무 명령 단락으로도 Pod 블록을 시작할 수 있으므로, "=pod"는 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...

• 특정한 포매터에만 전달되는 내용을 담는 영역을 지정
  • 해당 포맷을 사용할 수 있는 포매터만 이 영역의 내용을 인식하고, 다른 포매터는 무시함

• "=begin formatname" ... "=end formatname" - begin과 end사이의 영역에 대하여 적용:

=begin html

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

=end html

• "=for formatname text..." - 이 단락의 text... 부분에 대해서 적용:

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

• 예:

=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") 텍스트가 raw data가 아니라, 일반적이지 않은 포매팅을 적용해야 할 Pod 텍스트(포매팅 코드를 포함하고 있을 수 있는)임을 알려줄 수 있다. (예를 들어 보통의 단락이 아니라 각주로 포매팅되어야 하는 경우)

 =encoding encodingname

• 문서의 인코딩을 선언:

=encoding utf8
=encoding koi8-r
=encoding ShiftJIS
=encoding big5

=over

=item *

First item

=item *

Second item

=back

=over

=item Foo()

Description of Foo function

=item Bar()

Description of Bar function

=back

1.4. Formatting Codes

• 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>)

• C<text> - 코드 텍스트
  • 프로그램 텍스트 (C<gmtime($^T)>)
  • 컴퓨터 전문 용어나 서식 (C<drwxr-xr-x>)

• L<name> - 하이퍼링크
  • 아래의 문법들에서, text, name, section 자리에는 "/", "|" 캐릭터는 넣을 수 없으며, "<"와 ">"는 서로 대응되어야 한다.
  • "섹션"은 표제나 아이템의 이름이 있는 곳부터 시작함.
  • L<name>
    • 펄 매뉴얼 페이지 (L<Net::Ping>)
    • 간혹 UNIX 맨페이지를 링크할 때도 쓰임 (L<crontab(5)>)
    • name에는 공백을 넣을 수 없음
  • L<name/"sec"> , L<name/sec>
    • 다른 매뉴얼 페이지의 섹션 (L<perlsyn/"For Loops">)
  • L</"sec"> , L</sec> , L<"sec">
    • 현재 매뉴얼 페이지의 섹션 (L</"Object Methods">)

• L<text|...> - 출력되는 텍스트 변경
• L<text|name>
• L<text|name/"sec"> , L<text|name/sec>
• L<text|/"sec"> , L<text|/sec> , L<text|"sec">

• L<scheme:...> - 웹페이지 링크
  • 예: L<http://www.perl.org/>

• E<escape>
  • 캐릭터 이스케이프
  • E<lt> - "<"
  • E<gt> - ">"
  • E<verbar> - "|"
  • E<sol> - "/"
  • E<htmlname> - HTML 개체 이름. (E<eacute>)
  • E<number> - ASCIILatin-1/Unicode 캐릭터 번호 (E<0x201E> , E<075> , E<181>)

• F<filename>
  • 파일명. 주로 이탤릭체로 나옴 (F<.cshrc>)

• S<text>
  • 공백이 있더라도 그 자리에서 줄을 바꾸면 안 되는 텍스트 (S<$x ? $y : $z>)

• X<topic name>
  • 색인 항목 (X<absolutizing relative URLs>)
  • 포매터에서는 주로 무시됨

• Z<>
  • 널 포매팅 코드.
  • 포매팅코드로 해석되지 않게 중간에 끊어주는 용도 등으로 사용. ( "N<3"을 표기할 때: "NE<lt>3" 또는 "NZ<><3")

• "$a <=> $b"를 표시하는 경우
  • E코드 사용 - C<$a E<lt>=E<gt> $b>
  • Perl 5.660 이후 버전에서는 포매팅 코드의 좌우 경계를 나타내기 위해서 두 겹 이상의 부등호 쌍을 사용할 수 있다.
    • 단 시작과 끝의 부등호의 갯수가 동일해야 하고
    • 시작하는 부등호 바로 다음과, 끝나는 부등호 바로 전에 공백문자가 있어야 함

    C<< $a <=> $b >>
    C<<< $a <=> $b >>>
    C<<<<  $a <=> $b     >>>>
이것은 모두
    C<$a E<lt>=E<gt> $b>
와 같다

    C<<< open(X, ">>thing.dat") || die $! >>>
    C<< $foo->bar(); >>
위의 형태가 아래 형태보다 읽기 좋다
    C<open(X, "E<gt>E<gt>thing.dat") || die $!>
    C<$foo-E<gt>bar();>

1.5. The Intent

• Pod 포맷은 표현력보다는 사용하기 쉬운 쪽에 초첨이 맞춰져 있다
• pod2text, pod2html, pod2man, pod2latex, pod2fm, 그리고 CPAN 에 있는 그외의 번역기 등을 사용하여 HTML, TeX 등의 다른 형태로 쉽게 바꿀 수 있다.
• 책을 작성하는 데 쓰기에는 부적절하다. :-)

1.6. Embedding Pods in Perl Modules

• 펄 모듈이나 스크립트에 Pod 문서를 내장할 때,
  • 빈 줄, "=head1" 명령 으로 문서를 시작하고 "=cut" 명령, 빈 줄 순서로 문서를 끝냄

• Pod 문서를 파일의 마지막 부분에 작성하고, 이 파일에 __END__나 __DATA__ 마크가 있을 경우 첫번째 Pod 명령 앞에 빈 줄이 반드시 있어야 한다.

__END__

=head1 NAME

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

1.7. Hints for Writing Pod

• podchecker 프로그램으로 Pod 문서의 문법 에러나 경고를 점검할 수 있다.
• 여러 종류의 번역기에 문서를 통과시켜서 제대로 번역이 되는지 확인하라.
• Pod보다 HTML 문서를 작성하는 게 더 편하다면, CPAN:Pod::HTML2Pod 모듈로 역변환을 할 수도 있다.
• 구식의 번역기들은 모든 Pod 명령의 앞뒤로 빈줄이 있어야 제대로 해석한다. ("=cut"도!)
• 어떤 구식 번역기들은 단락의 앞뒤로 완전히 빈 줄로 구분되어 있어야 제대로 해석한다. (즉 공백 문자조차도 없어야 함)
• 구식 번역기 중에는 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컬럼을 넘어가게 작성할 경우 어떤 포매터에서는 이상하게 줄바꿈이 되어 버릴 수 있다.

1.8. 참고

• perldocspec
• ["PODs: Embedded Documentation" in perlsyn]
• perlnewmod
• perldoc
• pod2html
• pod2man
• [podchecker]

2. 한글

• 아래의 내용은 Strawberry perl 5.10.0 에서 테스트
• /Pod-Usage를 사용하여 스크립트 내에서 pod2usage()를 사용하여 출력할 때는 다음과 같이 하면 잘 나온다.
  • 스크립트를 UTF-8로 인코딩할 경우에는 =encoding utf8로, EUC-KR로 인코딩할 경우에는 =encoding euc-kr 로 명시해주고
  • binmode(STDOUT, ":encoding(euc-kr)") 로 지정해 주어야 함
• perldoc 스크립트이름을 사용해 출력할 경우 - 깨져서 나온다
  • UTF-8 로 인코딩한 경우에 깨져서 나옴
  • EUC-KR 로 인코딩한 경우에는, =encoding euc-kr이 적혀 있으면 깨져 나오고, 이 줄을 삭제할 경우 한글이 나오긴 하는데 이때도 일부는 깨져 나옴

3. 기타 & Comments