일반 이전 설명서

Plean Old Documentation(팟)은 Perl 프로그래밍 언어와 Perl 모듈 및 프로그램을 문서화하는 데 사용되는 경량 마크업 언어다.

디자인

포드는 간단하고 깨끗한 언어로 설계되었으며, 유용한 구문만 충분하다.여기에는 글꼴, 이미지, 색상 또는 표에 대한 메커니즘이 의도적으로 포함되지 않는다.목표의 일부는 다음과 같다.

• 구문 분석하기 쉬운
• XML, TeX 또는 Markdown과 같은 다른 형식으로 쉽게 변환
• 샘플 코드를 쉽게 통합
• 포드 포맷터 없이 읽기 쉽음(즉, 소스 코드 형태로)
• 쓰기 편함

사이비 POD라고 불리는 테이블과 각주를 지원하는 확장된 버전의 포드(Pod)는 여러 Perl 책을 제작하는데 O'Reilly & Associates에 의해 사용되었는데, 특히 Larry Wall의 Programming Perl, Tom Christianensen, 그리고 Jon Orwant가 그것이다.

팟은 사용자 중심의 문서에 잘 맞는 수동 페이지를 쉽게 작성할 수 있도록 한다.이와는 대조적으로, 사용자 문서에 사용될 수 있지만 파이썬의 Docstring이나 자바 자바독과 같은 다른 문서 시스템은 소프트웨어 프로젝트의 소스 코드에 대한 개발자 중심의 문서화를 쉽게 생성하도록 설계된다.

사용하다

포드(Pod)는 펄(Perl) 세계에서 대부분의 문서에 사용되는 언어다.여기에는 Perl 자체, 거의 모든 공개 모듈, 많은 스크립트, 대부분의 설계 문서, Perl.com 및 기타 Perl 관련 웹 사이트의 많은 기사, 그리고 앵무새 가상 머신이 포함된다.

포드는 포맷 도구의 도움 없이 읽을 수 있도록 설계되었지만 원시에서는 거의 읽히지 않는다.대신 perldoc 도구로 읽거나 유닉스 맨 페이지나 웹 표준 HTML 페이지로 변환된다.

Perl이 아닌 다른 맥락에서 팟을 사용하는 것도 가능하다.예를 들어, 간단한 문서를 bash 스크립트에 추가하기 위해, 이 스크립트는 쉽게 man 페이지로 변환될 수 있다.^[1]이러한 용도는 (bash로) POD 섹션에 회선을 접두사처럼 포드 부분을 숨기기 위해 언어별 해킹에 의존한다.:<<=cut바쉬의 수술 금지 명령을 내려서 :명령어, 포드 블록 전체를 여기에 입력된 문서로 사용.

순수 포드 파일에는 일반적으로 확장자가 있음.pod, 그러나 pod는 주로 Perl 코드에 직접 사용되는데, 이 코드는 일반적으로.pl그리고.pm확장. (Perl 통역사의 파서는 Perl 코드의 pod를 무시하도록 설계되었다.)소스 코드 파일에서 설명서는 일반적으로 다음 항목 뒤에 배치된다.__END__마커(일부 편집기에서 구문을 강조 표시하여 코멘트로 표시함)

포드는 다른 포맷으로 쉽게 변환될 수 있는데, 예를 들어 다음과 같은 다양한 위키 포맷이 있다.WikiWikiWeb, Kwiki, TWiki, UseModWiki, TiddlyWiki, Fectric, MediaWiki, MoinMoin 또는 Pod::단순::위키

예

이 문서는 구문론적으로 정확한 팟으로, 섹션 이름 지정에 대한 주요 규칙을 따르려고 시도한다.^[2]

=head1 NAME  My::Module - 예제 모듈  =head1 SynopsIS  사용 내:모듈; 나의 $object = My:::Module->new(); $object->as_string 인쇄;  =head1 설명  이 모듈은 실제로 존재하지 않는다. 의 유일한 목적으로 만들어졌다. POD 작동 방식 시연.  =head2 방법  =12세 이상  =새 항목 C.  새 My::Module 개체를 반환함  =항목 C.  문자열화된 표현을 반환 목적어이것은 주로 디버깅을 위한 것이다. 목적들  =백  =head1 라이센스  이것은 예술에 의해 공개된다. 면허증L을 참조하십시오.  =head1 작성자  Juerd - L<http://juerd.nl/>  =head1 참고 항목  L.PerlPod, L.Perlpodspec  =컷 

서식 세부 정보

포드 파일은 ASCII 호환 인코딩(예: Latin-1 또는 UTF-8)으로 작성된다. 포드 파서(pod parser)는 항상 파싱 중인 파일이 포드로부터 시작되지 않는다고 가정한다. 포드파서(pod parser)는 포드 지시어를 볼 때까지 모든 라인을 무시한다.팟 지시어는 줄의 시작 부분에 와야 하며, 모든 것은 같은 기호로 시작한다.그런 다음 포드 파서는 "=cut" 지시어로 구성된 라인과 마주칠 때까지 모든 다음 라인이 포드라고 가정한다.파서가 다른 팟 지시어와 마주칠 때까지 내용이 무시된다.따라서 언어의 파서가 팟을 인식하고 무시하는 방법을 알고 있다면 팟은 실행 가능한 소스 코드와 혼합될 수 있다.

포드 내용은 빈 줄에 의해 단락으로 나뉜다.공백 문자(탭 또는 공백)로 시작하는 단락은 "완전히 형식화되지 않은 단락"으로 간주되며, 샘플 코드, ASCII 아트 등에 사용된다.등호로 시작하는 단락은 "명령 단락"이다. 등호 바로 뒤에 나오는 영숫자 순서는 포드 지시어로 처리되며, 나머지 단락은 그 지시에 따라 포맷된다.일부 지침은 다음 단락에도 영향을 미친다.만약 어떤 단락이 동일한 부호나 공백이 아닌 것으로 시작된다면, 그것은 "일반적인 단락"으로 간주된다.

일반 단락과 명령 단락의 내용은 모두 포맷 코드를 구문 분석한다.포드의 형식은 매우 평범하다; 주로 굵은 글씨, 이탤릭체, 밑줄, 모노스페이스, 그리고 몇 가지 다른 형식들로 제한된다.팟 문서 간 또는 같은 문서 내의 다른 섹션과 연결하는 코드도 있다.포맷 코드는 다음 중 하나로 구성된다.

• 대문자 하나 뒤에 작은 기호(<), 포맷할 내용 및 큰 기호(>)가 오는 경우.B<bolded text>, 또는
• 대문자 한 개, 기호(<<>), 기호 두 개 이상, 공백, 포맷할 내용, 다른 공간 및 이전과 동일한 수의 기호.B<< bolded text >>. 이 양식은 종종 큰 부호를 포함하는 코드 조각에 사용되며 그렇지 않으면 포맷 코드가 종료된다.

팟의 명령어에는 네 가지 수준의 제목, 글머리표 및 번호 목록, 섹션을 다른 언어로 표시하는 명령이 포함된다.후자의 특징은 그것을 지지하는 파서들에게 특별한 포맷을 제공할 수 있게 한다.

참고 항목

• 문서 생성기 비교

참조

• 월, 래리; 크리스천, 톰; & 오완트, 존(2000년)프로그래밍 Perl(3차 개정).세바스토폴: 오라일리 & 어소시에이츠 ISBN0-596-00027-8.
• 제15장 "팟과 함께 일하기" (2007) foy, brian d.펄 마스터링.세바스토폴: 오라일리 미디어.ISBN 0-596-52724-1
• 섹션 5.2, 칼 알빙, 보센, JP, 그리고 카메론 뉴햄의 "쉘 스크립트의 내장 문서"(2007).Bash Cookbook: Bash Users를 위한 솔루션과 예; O'Reilly & Associates.ISBN 0-596-52678-4

외부 링크

• perlpod(문서 작성자용 pod에 저장)
• perlpodspec(Perlpodspec for parsperlpodspec
• 원시 포드 형식의 Perl 맨 페이지
• (PseudoPOD)
• 디렉터리에 포드 포맷이 포함된 많은 모듈이 있음
• Getopt:Eucleid 모듈이 포드 태그를 기반으로 자동으로 Perl 스크립트에 입력 구문 분석
• 포드::단순::Wiki는 pod를 다양한 Wiki 형식으로 변환한다.
• 포드::Markdown pod를 Markdown으로 변환