Perl/POD 페이지의 소스 보기
마지막으로 [b]
-- Loading page list... --
내용출력
로그인[l]
Diary
[f]
최근변경내역
[r]
페이지목록[i]
횡설수설[2]
게시판[3]
링크
수정할 수 없습니다: Perl/POD 는 읽기 전용 페이지입니다.
= [[Perl]] POD = Plain Old Documentation format <toc> == # perlpod 정리 == Perldoc:perlpod 요약 Pod 마크업을 이루는 세 가지 기본적인 단락 : ordinary, verbatim, command === # Ordinary Paragraph === * 일반적인 단락. * 단락 전후에 빈 줄이 있어야 함 * 자동 줄바꿈, 글꼴 여백 조정, 정렬 등의 최소한의 효과만 적용됨 * 포매팅 코드를 사용하여 여러 가지 효과를 줄 수 있음. === # Verbatim Paragraph === * 단락의 첫 글자가 공백이나 탭으로 시작 (보통은 단락의 모든 행을 공백이나 탭으로 시작하게 작성) * 코드블록를 나타낼 때 * 특별한 처리나 포매팅 적용이 되지 않고 텍스트 원문을 그대로 보이고 싶을 때 * 아무런 포매팅이 적용되지 않음 === # 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'' * 표제를 생성: {{{#!vim pod =head2 Object Attributes }}} * head3과 head4는 오래된 Pod 번역기에서 지원하지 않을 수 있음 * 표제의 텍스트에도 포매팅 코드를 사용 가능: {{{#!vim pod =head2 Possible Values for C<$/> }}} =over ''indentlevel'' =item ''stuff...'' =back * "=item"을 사용하여 생성한 목록이 들어있을 영역을 지정할 때 사용 * 일반 단락들을 그룹지어 들여쓸 영역을 지정할 때도 사용 * "=over"로 시작해서 "=back"으로 끝냄 * ''indentlevel''은 얼마나 들여쓸지를 나타냄. (어떤 포매터에서는 무시됨) * ''stuff''에는 포매팅 코드 사용 가능: {{{#!vim pod =item Using C<$|> to Control Buffering }}} * "=over" ... "=back" 영역을 사용할 때 적용되는 규칙 ** "=item"을 영역 밖에서 사용하지 말 것 ** 영역 내에 "=item"이 하나라도 있을 경우는, "=over" 명령 바로 다음에 "=item"이 나와야 한다. ** 영역 안에는 "=head''n''" 명령을 두지 말 것 ** (중요) 아이템을 일관성 있게 표시할 것. 한 영역 안에서 다음 세 가지 중 하나를 택해서 그것만 사용하라. *** "=item *" - 번호 없는 리스트 *** "=item ''숫자''." - 번호 있는 리스트 *** "=item foo", "=item bar" 등 - 불릿이나 번호가 없는 리스트 =cut * Pod 블록을 종료하고 Perl 코드가 다시 진행됨을 알림 * 빈 줄, "=cut", 빈 줄 형태로 쓸 것 =pod * Pod 블록이 시작됨을 알림. * 아무 명령 단락으로도 Pod 블록을 시작할 수 있으므로, "=pod"는 Pod블록을 보통의 단락이나 원문 단락으로 시작하고 싶을 때 사용: {{{#!vim perl =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사이의 영역에 대하여 적용: {{{#!vim pod =begin html <hr> <img src="thang.png"> <p> This is a raw HTML paragraph </p> =end html }}} * "=for ''formatname text...''" - 이 단락의 ''text...'' 부분에 대해서 적용: {{{#!vim pod =for html <hr> <img src="thang.png"> <p> This is a raw HTML paragraph </p> }}} * 예: {{{#!vim pod =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 문서에 나타나지 않음. 작성자 자신의 기록 용도 등으로 사용: {{{#!vim pod =for comment Make sure that all the available options are documented! }}} * 어떤 포맷명은 앞에 콜론이 붙어서 (":formatname") 텍스트가 raw data가 아니라, 일반적이지 않은 포매팅을 적용해야 할 Pod 텍스트(포매팅 코드를 포함하고 있을 수 있는)임을 알려줄 수 있다. (예를 들어 보통의 단락이 아니라 각주로 포매팅되어야 하는 경우) =encoding ''encodingname'' * 문서의 인코딩을 선언: {{{#!vim pod =encoding utf8 =encoding koi8-r =encoding ShiftJIS =encoding big5 }}} '''유의:''' 명령어가 있는 라인이 아니라 명령어가 포함된 단락의 끝날 때 그 명령어가 끝난다. 따라서 각 명령어는 단락을 끝내기 위해 바로 뒤에 빈 라인이 있어야 한다: {{{#!vim pod =over =item * First item =item * Second item =back =over =item Foo() Description of Foo function =item Bar() Description of Bar function =back }}} === # 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">) ** <code>L<text|...></code> - 출력되는 텍스트 변경 ** L<text|name> ** L<text|name/"sec"> , L<text|name/sec> ** L<text|/"sec"> , L<text|/sec> , L<text|"sec"> ** <code>L<scheme:...></code> - 웹페이지 링크 *** 예: <code>L<http://www.perl.org/></code> * <code>E<escape></code> ** 캐릭터 이스케이프 ** E<lt> - "<" ** E<gt> - ">" ** E<verbar> - "|" ** E<sol> - "/" ** E<htmlname> - HTML 개체 이름. (E<eacute>) ** E<number> - ASCIILatin-1/Unicode 캐릭터 번호 (E<0x201E> , E<075> , E<181>) * <code>F<filename></code> ** 파일명. 주로 이탤릭체로 나옴 (F<.cshrc>) * <code>S<text></code> ** 공백이 있더라도 그 자리에서 줄을 바꾸면 안 되는 텍스트 (S<$x ? $y : $z>) * <code>X<topic name></code> ** 색인 항목 (X<absolutizing relative URLs>) ** 포매터에서는 주로 무시됨 * <code>Z<></code> ** 널 포매팅 코드. ** 포매팅코드로 해석되지 않게 중간에 끊어주는 용도 등으로 사용. ( "N<3"을 표기할 때: "NE<lt>3" 또는 "NZ<><3") 포매팅 코드 안에 ">"가 들어가야 되는 경우, 여러 가지 방법이 있음 * "<code>$a <=> $b</code>"를 표시하는 경우 ** E코드 사용 - <code>C<$a E<lt>=E<gt> $b></code> ** Perl 5.660 이후 버전에서는 포매팅 코드의 좌우 경계를 나타내기 위해서 두 겹 이상의 부등호 쌍을 사용할 수 있다. *** 단 시작과 끝의 부등호의 갯수가 동일해야 하고 *** 시작하는 부등호 바로 다음과, 끝나는 부등호 바로 전에 공백문자가 있어야 함 {{{#!vim pod C<< $a <=> $b >> C<<< $a <=> $b >>> C<<<< $a <=> $b >>>> 이것은 모두 C<$a E<lt>=E<gt> $b> 와 같다 }}} {{{#!vim pod C<<< open(X, ">>thing.dat") || die $! >>> C<< $foo->bar(); >> 위의 형태가 아래 형태보다 읽기 좋다 C<open(X, "E<gt>E<gt>thing.dat") || die $!> C<$foo-E<gt>bar();> }}} === # The Intent === * Pod 포맷은 표현력보다는 사용하기 쉬운 쪽에 초첨이 맞춰져 있다 * pod2text, pod2html, pod2man, pod2latex, pod2fm, 그리고 CPAN 에 있는 그외의 번역기 등을 사용하여 HTML, TeX 등의 다른 형태로 쉽게 바꿀 수 있다. * 책을 작성하는 데 쓰기에는 부적절하다. :-) === # Embedding Pods in Perl Modules === * 펄 모듈이나 스크립트에 Pod 문서를 내장할 때, ** 빈 줄, "=head1" 명령 으로 문서를 시작하고 "=cut" 명령, 빈 줄 순서로 문서를 끝냄 * Pod 문서를 파일의 마지막 부분에 작성하고, 이 파일에 __END__나 __DATA__ 마크가 있을 경우 첫번째 Pod 명령 앞에 빈 줄이 반드시 있어야 한다. {{{#!vim perl __END__ =head1 NAME Time::Local - efficiently compute time from local and GMT time }}} === # Hints for Writing Pod === * podchecker 프로그램으로 Pod 문서의 문법 에러나 경고를 점검할 수 있다. * 여러 종류의 번역기에 문서를 통과시켜서 제대로 번역이 되는지 확인하라. * Pod보다 HTML 문서를 작성하는 게 더 편하다면, CPAN:Pod::HTML2Pod 모듈로 역변환을 할 수도 있다. * 구식의 번역기들은 모든 Pod 명령의 앞뒤로 빈줄이 있어야 제대로 해석한다. ("=cut"도!) * 어떤 구식 번역기들은 단락의 앞뒤로 ''완전히 빈'' 줄로 구분되어 있어야 제대로 해석한다. (즉 공백 문자조차도 없어야 함) * 구식 번역기 중에는 L<> 링크 주위에 단어를 추가하는 경우가 있다. 예를 들어 <code>L<Foo::Bar></code>는 "the Foo::Bar manpage"로 표시될 수 있다. 따라서 "<code>the L<foo> documentation</code>"와 같이 작성할 경우 말이 안 되게 번역될 수 있다. 따라서 이런 경우 "<code>the L<Foo::Bar|Foo::Bar> documentation</code>" 또는 "<code>L<the Foo::Bar documentation|Foo::Bar></code>"와 같이 링크가 어떻게 표시될지도 지정하라. * verbatim 블록 내에서 70컬럼을 넘어가게 작성할 경우 어떤 포매터에서는 이상하게 줄바꿈이 되어 버릴 수 있다. === # 참고 === * Perldoc:perldocspec * [http://perldoc.perl.org/perlsyn.html#PODs%3a-Embedded-Documentation "PODs: Embedded Documentation" in perlsyn] * Perldoc:perlnewmod * Perldoc:perldoc * Perldoc:pod2html * Perldoc:pod2man * [http://perldoc.perl.org/podchecker.html podchecker] == # perlpodstyle 정리 == Perldoc:perlpodstyle 문서 정리 일반적인 얘기: * 문서에 해당하는 프로그램 이름은 볼드<code>B<></code>로. * 프로그램 옵션들도 볼드로. * 인자는 이탤릭으로. <code>I<></code> * 함수 이름은 이탤릭으로. 또는 function()과 같은 형태로 쓰면 Pod::Man이 처리해 줌 * 다른 맨페이지 참조는 <code>L<manpage(section)</code> * 모듈 문서는 <code>L<Module::name></code> * 맨페이지가 없는 프로그램 참조는 <code>B<></code>로. * 최상위 헤더는 <code>=head1</code>. 헤더명은 전부 대문자. * 하위 헤더는 <code>=head2</code>, 대소문자 섞어서. 표준 섹션들: * NAME ** 필수. 프로그램 이름들은 컴마로 구분. 이름과 설명 사이에는 대쉬 하나. 마크업 쓰지 말 것. 함수 이름에 ()쓰지 말 것. man 프로그램이 대쉬를 탭으로 바꿔 출력하더라도 전체가 한 줄에 출력될 수 있게 길이 조절. {{{#!vim foo, bar - programs to do something }}} * SYNOPSIS ** 사용법 요약. Perl 모듈 문서의 경우 verbatim 블럭으로, 모듈을 사용하는 전형적인 예문 몇 개를 보여 줌 * DESCRIPTION ** 자세한 설명, 토의 ** 분량이 길면 서브섹션으로 나눔 {{{#!vim perl =head2 Normal Usage =head2 Advanced Features =head2 Writing Configuration Files }}} ** 모듈의 경우, 모듈이 제공하는 인터페이스의 설명을 <code>=item</code>을 써서 리스트로. ** 인터페이스의 수가 많다면 METHODS, FUNCTIONS, CLASS METHODS, or INSTANCE METHODS 등으로 나누고 DESCRIPTION에서는 개요만 보일 수도. * OPTIONS ** 커맨드 라인 옵션에 대한 자세한 설명 ** 보통은 각 옵션을 <code>=item</code>로 구분하여 설명 ** 옵션 스트링은 <code>B<></code>로. 옵션에 들어가는 값은 <code>I<></code>로. ** 동의어 옵션은 동일한 item에 컴마 다음 한 칸 띄어 적음. 짧은 걸 앞에 적는 걸 권장 {{{#!vim perl =item B<--section>=I<manext> =item B<-s> I<manext>, B<--section>=I<manext> }}} * RETURN VALUE ** 프로그램의 경우 생략할 수도, 함수의 경우는 항상 적어주고, 모듈의 경우는 모듈 인터페이스들의 리턴값을 여기서 요약하거나, 각 함수나 메쏘드의 설명을 하는 곳에서 자세히 설명하거나. * ERRORS ** 보통은 함수나 모듈의 경우 쓰이고, 프로그램은 DIAGNOSTICS 섹션을 대신 사용. ** 경험적으로는, 표준출력이나 표준에러를 통해 사용자에게 나가는 에러는 DIAGNOSTICS 섹션에 설명하고, 호출한 프로그램에 내부적으로 전달되거나 프로그래머를 위한 설명은 ERRORS 섹션에 둔다. ** errono값을 세팅하는 경우는 가능한 값의 목록을 여기에 적음 * DIAGNOSTICS ** 프로그램이 출력할 가능성이 있는 메시지들과 그 의미. ** 가능하면 사용자가 그 에러를 해결할 수 있는 방법을 같이 적도록 함. * EXAMPLES ** 프로그램이나 함수 사용 예제 코드<footnote(그런데 perldoc 문서, 특히 모듈 문서는 SYNOPSIS 자리에 example 코드를 넣는 듯?)>. verbatim 문단으로. ** 각 예문이 무엇을 하는 코드인지도 간단한 설명을 추가해주면 훨씬 좋다. * ENVIRONMENT ** 관련되는 환경변수들을 <code>=over</code>, <code>=item</code>, <code>=back</code>을 사용해 목록으로 출력. {{{#!vim perl =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 ** 프로그램이나 함수에서 사용하는 파일들의 목록. 사용하는 용도. ** 파일명은 <code>F<></code>로 포매팅. ** 파일이 수정될 수 있는 경우 명시해 줄 것 * CAVEATS ** WARNINGS 로도 불림. 주의사항 * BUGS * RESTRICTIONS ** 고칠 계획이 없는 버그들 * NOTES * AUTHOR ** 작성자. (복수이면 AUTHORS) ** 버그 리포트를 받을 수 있는 메일주소나 기타 연락처를 남겨두면 좋음. * HISTORY ** 다른 프로그램에서 파생된 경우. ** 프로그램 수정 내역을 적기도 하지만, 너무 길어지니 별도 파일에 적는 게 낫다. * COPYRIGHT AND LICENSE {{{#!vim Copyright YEAR(s) YOUR NAME(s) }}} ** Perl과 동일한 라이센스를 사용하고 싶다면: {{{#!vim 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변환기가 처리해 준다. * 현존하는 변화기들 다수가 메일 주소를 <code>L<></code>로 둘러쌌을 때 잘못된 수행을 하니 그러지 말라. == # 한글 == 윈도우 명령프롬프트에서 출력할 경우: * 아래의 내용은 Strawberry perl 5.10.0 에서 테스트 * [[/Pod-Usage]]를 사용하여 스크립트 내에서 <code>pod2usage()</code>를 사용하여 출력할 때는 다음과 같이 하면 잘 나온다. ** 스크립트를 UTF-8로 인코딩할 경우에는 <code>=encoding utf8</code>로, EUC-KR로 인코딩할 경우에는 <code>=encoding euc-kr</code> 로 명시해주고 ** <code>binmode(STDOUT, ":encoding(euc-kr)")</code> 로 지정해 주어야 함 * <code>perldoc 스크립트이름</code>을 사용해 출력할 경우 - 깨져서 나온다 ** UTF-8 로 인코딩한 경우에 깨져서 나옴 ** EUC-KR 로 인코딩한 경우에는, <code>=encoding euc-kr</code>이 적혀 있으면 깨져 나오고, 이 줄을 삭제할 경우 한글이 나오긴 하는데 이때도 일부는 깨져 나옴 == # 기타 == * [http://ko.perlmaven.com/pod-plain-old-documentation-of-perl POD - Plain Old Documentation -- Perl Maven] == # Comments == <div class="comments"> <longcomments(100)> ---- </div> ---- [[컴퓨터분류]]
Perl/POD
페이지로 돌아가기 |
다른 수정본 보기
![[첫화면으로]](/raymundo_logo.jpg){kind=logo}
Perl/POD 페이지의 소스 보기Perl/POD 페이지의 소스 보기