perldoc 명령

perldoc 명령 (perldoc)

perldoc은 Perl 문서를 Pod 형식으로 조회하는 명령이에요. 이 문서는 perldoc이 어떤 옵션을 제공하는지, 각 옵션을 언제 왜 쓰는지 강사가 옆에서 설명하듯 안내해 드려요.

perldoc은 Perl 설치 트리나 Perl 스크립트에 포함된 .pod 형식 문서를 찾아서 다양한 포맷터로 표시해요. 주로 Perl 라이브러리 모듈의 문서를 볼 때 씁니다. 시스템에 그 모듈들의 man 페이지가 설치돼 있다면 그냥 man(1) 명령을 써도 돼요. Perl 라이브러리 모듈 문서의 목차를 찾고 있다면 perltoc 페이지를 보세요.

출처: perldoc - Look up Perl documentation in Pod format.

본문

SYNOPSIS

perldoc [-h] [-D] [-t] [-u] [-m] [-l] [-U] [-F]
    [-i] [-V] [-T] [-r]
    [-d destination_file]
    [-o formatname]
    [-M FormatterClassName]
    [-w formatteroption:value]
    [-n nroff-replacement]
    [-X]
    [-L language_code]
    PageName|ModuleName|ProgramName|URL

예시:

perldoc -f BuiltinFunction

perldoc -L it -f BuiltinFunction

perldoc -q FAQ Keyword

perldoc -L fr -q FAQ Keyword

perldoc -v PerlVariable

perldoc -a PerlAPI

각 스위치에 대한 자세한 설명은 아래를 보세요.

OPTIONS

**-h

간단한 help 메시지를 출력해요.

**-D

항목을 찾는 과정을 detail(상세)하게 설명해요.

**-t

nroff 대신 일반 text 변환기로 문서를 표시해요. 더 빠를 수 있지만 아마 그만큼 예쁘진 않을 거예요.

**-u

실제 Pod 포맷을 건너뛰고 원시 Pod 소스만 보여줘요(Unformatted).

**-m module

모듈 전체(코드와 포맷되지 않은 pod 문서)를 표시해요. 문서가 함수를 필요한 만큼 자세히 설명하지 않아서 코드를 직접 들여다보고 싶을 때 유용해요. perldoc이 해당 파일을 찾아서 그냥 표시해 줍니다.

**-l

찾은 모듈의 파일 이름만 표시해요.

**-U

수퍼유저로 실행할 때 보안을 위해 권한을 낮추지 않아요. 이 옵션은 -F와 함께 쓰면 암묵적으로 적용돼요.

NOTE: 자세한 내용은 아래 SECURITY 항목을 참고하세요.

**-F

인자를 파일 이름으로 간주하고 디렉터리 검색은 수행하지 않아요. 수퍼유저로 실행하면 -U를 암묵적으로 의미해요.

**-f perlfunc

-f 옵션 뒤에 Perl 내장 함수 이름을 주면 perlfunc에서 이 함수의 문서를 뽑아줘요.

예시:

perldoc -f sprintf

**-q perlfaq-search-regexp

-q 옵션은 정규 표현식을 인자로 받아요. perlfaq[1-9]의 question(질문) 제목을 검색해서 정규 표현식에 맞는 항목을 출력해요.

예시:

perldoc -q shuffle

**-a perlapifunc

-a 옵션 뒤에 perl api 함수 이름을 주면 perlapi에서 이 함수의 문서를 뽑아줘요.

예시:

perldoc -a newHV

**-v perlvar

-v 옵션 뒤에 Perl 사전 정의 변수 이름을 주면 perlvar에서 이 변수의 문서를 뽑아줘요.

예시:

perldoc -v '$\"'
perldoc -v @+
perldoc -v DATA

**-T

출력을 페이저로 보내지 않고 STDOUT으로 직접 보내라고 지정해요.

**-d destination-filename

출력을 페이저나 STDOUT 어디로도 보내지 않고 지정한 파일 이름으로 저장하라고 지정해요. 예시: perldoc -oLaTeX -dtextwrapdocs.tex Text::Wrap

**-o output-formatname

Perldoc이 지정한 출력 형식에 대해 Pod 포맷팅 클래스를 사용하도록 해요. 예: -oman. 사실 이건 -M 스위치를 감싼 것일 뿐이에요. -o*formatname*은 그 형식 이름(대문자 변형 포함)을 여러 클래스 이름 접두어 뒤에 붙여 로드 가능한 클래스를 찾아봐요.

예를 들어 -oLaTeX는 현재 다음 클래스들을 모두 시도해요: Pod::Perldoc::ToLaTeX, Pod::Perldoc::Tolatex, Pod::Perldoc::ToLatex, Pod::Perldoc::ToLATEX, Pod::Simple::LaTeX, Pod::Simple::latex, Pod::Simple::Latex, Pod::Simple::LATEX, Pod::LaTeX, Pod::latex, Pod::Latex, Pod::LATEX.

**-M module-name

pod 포맷팅에 사용할 모듈을 지정해요. 클래스는 최소한 parse_from_file 메서드를 제공해야 해요. 예: perldoc -MPod::Perldoc::ToChecker.

시도할 클래스를 여러 개 지정하려면 쉼표나 세미콜론으로 연결하면 돼요. 예: -MTk::SuperPod;Tk::Pod.

**-w option:value 또는 -w option

포맷터에 넘길 옵션을 with(가지고) 지정해요. 예를 들어 -w textsize:15는 포맷터 객체로 객체를 포맷하기 전에 $formatter->textsize(15)를 호출해요. 그러려면 포맷터 클래스가 그런 메서드를 제공해야 하고, 넘기는 값도 유효해야 해요.(textsize가 정수를 기대하는데 -w textsize:big을 하면 문제가 생길 거예요.)

-w optionname(값 없이)을 -w optionname:*TRUE*의 줄임말로 쓸 수 있어요. -w page_numbering 같은 켜고/끄는 기능에 유용할 거예요.

콜론 대신 "="를 써도 돼요. 예: -w textsize=15. 쓰는 셸에 따라 편할 수도 있고 불편할 수도 있어요.

**-X

인덱스가 있으면 사용해요. -X 옵션은 파일 $Config{archlib}/pod.idx에서 명령줄에 준 이름과 기본 이름이 일치하는 항목을 찾아요. pod.idx 파일은 한 줄에 하나씩 전체 경로가 담겨 있어야 해요.

**-L language_code

원하는 언어 번역의 language code를 지정해요. 시스템에 POD2::<language_code> 패키지가 설치돼 있지 않으면 이 스위치는 무시돼요. 사용 가능한 모든 번역 패키지는 POD2:: 네임스페이스 아래에서 찾을 수 있어요. 새 지역화 POD2::* 문서 패키지를 만들고 Pod::Perldoc에 통합하는 방법은 POD2::IT(또는 POD2::FR)을 보세요.

**PageName|ModuleName|ProgramName|URL

조회할 항목이에요. 중첩 모듈(예: File::Basename)은 File::Basename이나 File/Basename으로 지정해요. perlfunc 같은 페이지의 설명 이름을 줘도 돼요. URL은 현재 HTTP와 HTTPS만 지원해요.

'foo' 같은 단순한 이름의 경우, 일반 검색이 일치하는 페이지를 못 찾으면 "perl" 접두어를 붙인 검색도 시도해요. 그래서 "perldoc intro"만 해도 "perlintro.pod"을 찾아 렌더링할 수 있어요.

**-n some-formatter

groff의 대체 포맷터를 지정해요.

**-r

재귀 검색이에요.

**-i

대소문자를 무시해요.

**-V

현재 실행 중인 perldoc의 버전을 표시해요.

SECURITY

perldoc은 tainted 모드에서 제대로 동작하지 않고 보안 이슈가 있는 것으로 알려져 있어서, 수퍼유저로 실행하면 권한을 낮추려고 시도해요. effective/real ID를 nobody나 nouser 계정으로 설정하고, 불가능하면 -2로 설정해요. 권한을 포기할 수 없으면 실행하지 않을 거예요.

이 동작을 원하지 않으면 -U 옵션을 보세요. 다만 -U를 쓰면 상당한 보안 위험이 있다는 점을 주의하세요.

3.26부터 수퍼유저로 -F를 쓰는 것도 -U를 암묵적으로 의미해요. 대부분의 파일을 열고 디렉터리를 탐색하는 데는 nobody/nogroup 수준 이상의 권한이 필요하니까요.

ENVIRONMENT

PERLDOC 환경 변수에 담긴 스위치들은 명령줄 인자보다 먼저 적용돼요.

PERLDOC에 유용한 값은 보유한 모듈에 따라 -oterm, -otext, -ortf, -oxml 등이고, 포맷터 클래스를 정확히 지정하려면 -MPod::Perldoc::ToTerm 같은 걸 쓰면 돼요.

perldoc은 또한 PERL5LIB(PERL5LIB가 정의돼 있지 않으면 PERLLIB)와 PATH 환경 변수가 지정한 디렉터리도 검색해요.(후자는 perldoc 자신 같은 실행 파일에 포함된 pod도 사용 가능하게 하려는 것 때문이에요.)

Makefile.PL이나 Build.PL이 있는 디렉터리에서는 perldoc이 검색 경로 맨 앞에 .와 lib을 추가하고, 수퍼유저가 아니면 blib도 추가해요. 빌드 디렉터리 안에서 작업하면서 이전에 설치된 모듈 버전이 있어도 문서를 읽고 싶을 때 정말 유용해요.

perldoc은 스스로 페이저를 찾기 전에 PERLDOC_PAGER, MANPAGER, PAGER 순서로 우선해 페이저를 사용해요.(perldoc이 일반 텍스트나 포맷되지 않은 pod를 표시하도록 지시받았다면 MANPAGER는 쓰이지 않아요.)

-m 모드(모듈 소스 코드 표시)에서 perldoc을 쓸 때는 PERLDOC_SRC_PAGER에 설정된 페이저를 사용하려 해요. 이 명령에 유용한 설정은 좋아하는 편집기, 예를 들어 /usr/bin/nano 같은 거예요.(판단하지 마세요.)

PERLDOC_PAGER의 유용한 값 중 하나는 less -+C -E예요.

PERLDOCDEBUG에 양의 정수를 설정하면 perldoc이 -D 스위치보다도 더 상세한 출력을 내요. 숫자가 클수록 더 많이 내요.

CHANGES

3.14_05까지는 -v 스위치가 perldoc 동작의 상세 메시지를 출력하는 데 쓰였는데, 지금은 -D가 그 역할을 해요.

SEE ALSO

perlpod, Pod::Perldoc

AUTHOR

현재 유지보수자: Mark Allen <[email protected]>

과거 기여자: brian d foy <[email protected]>, Adriano R. Ferreira <[email protected]>, Sean M. Burke <[email protected]>, Kenneth Albanowski <[email protected]>, Andy Dougherty <[email protected]>, 그리고 그 외 다수.

더 알아보기 (Learn more)