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. perlpodstyle 정리

3. 한글

4. 기타

5. 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. perlpodstyle 정리

• 문서에 해당하는 프로그램 이름은 볼드B<>로.
• 프로그램 옵션들도 볼드로.
• 인자는 이탤릭으로. I<>
• 함수 이름은 이탤릭으로. 또는 function()과 같은 형태로 쓰면 Pod::Man이 처리해 줌
• 다른 맨페이지 참조는 L<manpage(section)
• 모듈 문서는 L<Module::name>
• 맨페이지가 없는 프로그램 참조는 B<>로.

• 최상위 헤더는 =head1. 헤더명은 전부 대문자.
• 하위 헤더는 =head2, 대소문자 섞어서.

• NAME
  • 필수. 프로그램 이름들은 컴마로 구분. 이름과 설명 사이에는 대쉬 하나. 마크업 쓰지 말 것. 함수 이름에 ()쓰지 말 것. man 프로그램이 대쉬를 탭으로 바꿔 출력하더라도 전체가 한 줄에 출력될 수 있게 길이 조절.

    foo, bar - programs to do something

• SYNOPSIS
  • 사용법 요약. Perl 모듈 문서의 경우 verbatim 블럭으로, 모듈을 사용하는 전형적인 예문 몇 개를 보여 줌

• DESCRIPTION
  • 자세한 설명, 토의
  • 분량이 길면 서브섹션으로 나눔

=head2 Normal Usage
=head2 Advanced Features
=head2 Writing Configuration Files

• 모듈의 경우, 모듈이 제공하는 인터페이스의 설명을 =item을 써서 리스트로.
• 인터페이스의 수가 많다면 METHODS, FUNCTIONS, CLASS METHODS, or INSTANCE METHODS 등으로 나누고 DESCRIPTION에서는 개요만 보일 수도.

• OPTIONS
  • 커맨드 라인 옵션에 대한 자세한 설명
  • 보통은 각 옵션을 =item로 구분하여 설명
  • 옵션 스트링은 B<>로. 옵션에 들어가는 값은 I<>로.
  • 동의어 옵션은 동일한 item에 컴마 다음 한 칸 띄어 적음. 짧은 걸 앞에 적는 걸 권장

=item B<--section>=I<manext>
=item B<-s> I<manext>, B<--section>=I<manext>

• RETURN VALUE
  • 프로그램의 경우 생략할 수도, 함수의 경우는 항상 적어주고, 모듈의 경우는 모듈 인터페이스들의 리턴값을 여기서 요약하거나, 각 함수나 메쏘드의 설명을 하는 곳에서 자세히 설명하거나.

• ERRORS
  • 보통은 함수나 모듈의 경우 쓰이고, 프로그램은 DIAGNOSTICS 섹션을 대신 사용.
  • 경험적으로는, 표준출력이나 표준에러를 통해 사용자에게 나가는 에러는 DIAGNOSTICS 섹션에 설명하고, 호출한 프로그램에 내부적으로 전달되거나 프로그래머를 위한 설명은 ERRORS 섹션에 둔다.
  • errono값을 세팅하는 경우는 가능한 값의 목록을 여기에 적음

• DIAGNOSTICS
  • 프로그램이 출력할 가능성이 있는 메시지들과 그 의미.
  • 가능하면 사용자가 그 에러를 해결할 수 있는 방법을 같이 적도록 함.

• EXAMPLES
  • 프로그램이나 함수 사용 예제 코드1. 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)

• Perl과 동일한 라이센스를 사용하고 싶다면:

    This library is free software; you may redistribute it and/or modify
    it under the same terms as Perl itself.

• SEE ALSO
  • 보통은 다른 맨페이지들을 컴마 뒤 한칸 띄고 나열.
  • 메일링 리스트나 웹사이트가 있다면 URL

• 객채지향 모듈의 경우 CONSTRUCTORS, METHODS, CLASS METHODS, INSTANCE METHODS 등. 함수 인터페이스의 경우 FUNCTIONS 섹션을 추가하고 DESCRIPTION 섹션에서는 개요만 보여주기도 함.
• 섹션들의 순서는 변할 수 있지만 NAME이 첫번째여야 함. 일반적으로 NAME, SYNOPSIS, DESCRIPTION, OPTIONS가 먼저 오고 이 순서로 나타남
• SEE ALSO, AUTHOR 등은 뒷쪽에

• 펄 변수, 함수명, 맨페이지 레퍼런스 등은 따로 꾸미지 않아도 POD변환기가 처리해 준다.
• 현존하는 변화기들 다수가 메일 주소를 L<>로 둘러쌌을 때 잘못된 수행을 하니 그러지 말라.

3. 한글

• 아래의 내용은 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이 적혀 있으면 깨져 나오고, 이 줄을 삭제할 경우 한글이 나오긴 하는데 이때도 일부는 깨져 나옴

4. 기타

• [POD - Plain Old Documentation -- Perl Maven]

5. Comments