Linux Man PageHOWTO
|
Linux Man Page HOWTO
 man.1명령어를 통해 볼 수 있는 온라인 문서(이른바 메뉴얼 페이지, manpage)를 작성하고자 할 때, 주의해야 할 사항에 대해 설명한다.
이 HOWTO의 최신 영문 버전은 http://www.tldp.org/HOWTO/Man-Page/index.html 에서 구할 수 있으며,
한글 버전은 http://man.kldp.org/wiki/LinuxManPageHOWTO 에서 볼 수 있다.
Contents
1. 문서화에 대한 몇가지 고찰 ¶왜 문서를 작성하는가? 이것은 바보스러운 질문일지도 모른다.
여기에 대한 답은 우리가 만든 프로그램이나 라이브러리, 함수, 그리고 그외의 우리가 작성하고 만든 것들을 다른 사람들이 쓸 수 있기를 원하기 때문이다. 그러나, 문서를 쓴다는 것은 이것이 전부는 아니다.
man.1명령어를 이용하는 것이다. 이 HOWTO는 문서화에 관련된 도구가 올바르게 처리할 수 있는 메뉴얼 페이지를 작성하기 위해 해야할 일을 설명한다. 이러한 도구들 중 중요한 것에는 man.1, xman.1x, apropos.1, makewhatis.8, catman.8등이 있다. 물론 정보의 신뢰성과 정확성은 전적으로 문서를 작성하는 사람에게 달려있다.
9절을 보면 흔히 할 수 있는 실수를 피하는데 도움이 될 것이다.
2. 메뉴얼 페이지에는 어떻게 접근하는가? ¶메뉴얼 페이지에 적당한 이름을 주고 올바른 장소에 설치하기 위해서는, 메뉴얼 페이지가 어떻게 접근되는지 정확한 구조를 알아야 한다. 모든 메뉴얼 페이지는 한 특정 섹션에 포함되어야 하고, 섹션은 한 글자로 표현된다. 리눅스에서 가장 일반적으로 사용되는 섹션과 그 의미는 다음과 같다.
섹션 이름 1 누구나 실행할 수 있는 사용자 명령 (User Commands) 2 시스템 호출 (System Calls), 즉 커널에서 제공하는 함수 3 C 라이브러리 함수 (C Library functions) 4 디바이스와 네트워크 인터페이스 (Devices and Network Interfaces), 즉 /dev 디렉토리에 있는 특별한 파일들 5 파일 포맷 (File Formats), 예를 들어 /etc/passwd 6 게임과 데모 (Games and Demos) 7 환경, 테이블, 매크로 (Environments, Tables, and Macros) 등의 잡다한 여러 가지들 8 시스템 관리자만 실행할 수 있는 시스템 관리용 명령들 (Maintenance Commands) 9 커널 루틴에 관련된 문서들의 리눅스만의 독자적인 저장소 n 새로운 문서들의 저장소. 보다 적당한 장소로 이동된다. o 오래된 문서들의 저장소. 유예 기간으로 보관되고 있는 것들이다. l 특정 시스템에 대한 로컬 문서들 형식화 시스템의 입력이 되는 메뉴얼 페이지의 원시 파일 이름은 해당하는 명령, 함수 혹은 파일 이름으로 시작하고, 점을 찍은 후, 섹션 문자를 붙인다. 예를 들어, "
passwd" 파일의 메뉴얼 페이지를 작성할 때, 원시 파일의 이름은 반드시 "passwd.5"로 해야 한다. 여기에서 원시 파일의 이름은 파일의 이름을 따르고, 점을 찍은 다음에, 파일 형식을 설명하는 섹션의 문자인 "5"를 붙인 것이다. 비슷한 예로, passwd 명령에 대한 메뉴얼 페이지의 원시 파일 이름은 "passwd.1"이 되는 것이고, 해당 C 라이브러리 함수를 설명하는 메뉴얼 페이지의 원시 파일 이름은 "passwd.3"이 될 것이다. 이처럼 같은 이름을 가지는 메뉴얼 페이지가 여러 섹션에 존재할 수 있기 때문에 섹션 문자는 중요한 구분자가 된다.
가끔 "
xterm.1x" 혹은 "wish.1tk"와 같이 몇 개의 문자가 추가되기도 한다. 이것은 X 윈도우 프로그램이나 Tk 응용 프로그램이라는 것을 의미하는 것이다. 몇몇 메뉴얼 탐색기에서는 이 추가적인 정보를 이용할 수 있다. 예를 들어, xman은 이용 가능한 문서 목록에서 "xterm(x)"와 "wish(tk)"을 사용한다.
가급적
n, o, l 섹션은 사용하지 않는 것이 좋다. 파일 시스템 표준(File System Standard)에서는 이러한 섹션을 사용하는 것을 반대한다. 숫자로 된 섹션을 사용하기 바란다. 또한, 이미 존재하는 프로그램, 함수, 파일 이름과의 충돌에 주의해야 한다. 독자적인 에디터를 만들어 이것을 ed 라든지 sed (smart ed라는 의미), 혹은 red (Rocky's ed라는 의미)와 같이 이름 짓는 것은 좋은 생각이 아니다. 만든 프로그램 이름을 고유한 것으로 정해서, 다른 사람이 당신이 만든 프로그램을 사용하면서 다른 프로그램의 메뉴얼 페이지를 보는 일이 일어나지 않도록 해야할 것이다.
자, 이제 메뉴얼 파일의 이름이 정해졌다. 다음으로 해야할 일은 어느 디렉토리에 이 파일을 설치할 것인지를 결정하는 것이다. 말하자면, 사용자가 "
make install"을 실행했을 때 설치되는 디렉토리를 어디로 할 것인지를 결정해야 한다는 것이다.
리눅스에서 모든 메뉴얼 페이지는 환경 변수
MANPATH로 지정된 디렉토리에 있다. 쉘이 환경 변수 PATH를 이용하는 것처럼 문서화 관련 도구들은 환경 변수 MANPATH를 이용한다.
실제로 MANPATH는 PATH와 같은 형식이다. 이것들은 콜론으로 나누어진 디렉토리의 리스트를 포함하고 있다. 단지 MANPATH에서는 빈 필드나 상대 경로를 허용하지 않고, 절대 경로만을 허용하는 차이가 있을 뿐이다.
환경 변수
MANPATH가 설정되어 있지 않으면 최소한 /usr/man 디렉토리가 포함된 기본값이 사용된다. 검색 속도를 올리고, 사용되는 디렉토리의 수를 적게 하기 위해, 기본 디렉토리로 불리는 MANPATH에 설정되는 디렉토리는 "man<s>"와 같은 이름을 갖는 하위 디렉토리들을 포함한다. 여기에서 <s>는 위 표에서 설명한 섹션을 나타내는 하나의 문자이다. 이 디렉토리에 모든 섹션에 대응하는 하위 디렉토리가 설치될 필요는 없다. 이것은 비어있는 하위 디렉토리를 둘 필요가 없기 때문이다. 그런데, 혹시 화면에 출력하거나 인쇄할 목적의 문서를 가지고 있는 "cat<s>", "dvi<s>" "ps<s>" 등과 같은 디렉토리가 있을 수도 있다. 이에 대해서는 나중에 자세히 설명하도록 하겠다.
기본 디렉토리에 있는 다른 파일은
whatis에 관련된 파일 뿐이다. 이 파일의 목적과 작성에 대해서는 12절에 설명되어 있다. 섹션 <s>에 속한 메뉴얼 페이지를 올바른 곳에 설치하는 제일 안전한 방법은 /usr/man/man<s> 디렉토리에 두는 것이다. 그런데, 잘 작성된 Makefile은 make 변수 MANDIR을 이용해 사용자에게 기본 디렉토리를 선택할 수 있도록 하고 있다. 많은 GNU 패키지에서는 디렉토리를 지정할 수 있는 --prefix=/what/ever 접두사 옵션을 이용해 설정할 수 있다. 이때, 메뉴얼 페이지는 기본 디렉토리를 /what/ever/man으로 하여 설치된다. 이런 식의 방법을 제공하기를 추천한다.
리눅스 파일 시스템 표준 (FS-Stnd)으로 인해, 사태는 한층 더 복잡하게 되었다. (FS-Stnd는 FHS(Filesystem Hierarchy Standard, http://www.pathname.com/fhs/ )로 변경되었다.) FS-Stnd 1.2에서는
"다른 혹은 다수의 언어로 쓰여진 메뉴얼 페이지를 지원하기 위해
/usr/man 의 구조에 대한 약속을 매듭지어야 한다."
라고 말하고 있다. 이것은 다른 언어 사이에 구별되는 다른 디렉토리 레벨을 사용함으로 구현된다. 다시 FS-Stnd를 인용하면,
"
/usr/man에서 언어에 대한 하위 디렉토리의 명명은 로케일 식별 문자열에 대한 설명이 있는 POSIX 1003.1 표준의 부록 E에 근거한다. 이것이 문화가 다른 환경을 기술하는 가장 적절한 방법이다. 로케일 문자열은 <language>[_<territory>][.<character-set>][,<version>]으로 나타낸다."
라고 나와 있다. (몇몇 공통 로케일 문자열에 대해서는 FS-Stnd를 참고하라.)
이러한 규칙을 따르면, 메뉴얼 페이지의 디렉토리는
/usr/man/<locale>/man[1-9lno]가 된다. 그럼 형식화된 버전은 당연히 /usr/man/<locale>/cat[1-9lno]이 될 것이다. 이렇게 하지 않으면 형식화된 버전은 하나의 로케일만 제공할 수 있게 될 것이다. 하지만, 현시점에서는 이러한 디렉토리 구성으로의 전환을 추천하지 않는다. 또한 FS-Stnd 1.2에서는 다음과 같이 말하고 있다.
"모든 메뉴얼 페이지에 언어와 코드셋이 일치된다면,
<locale>을 생략한 <mandir>에 모든 메뉴얼 페이지를 보관해도 괜찮다. 예를 들어, ASCII로 된 영어 메뉴얼 페이지만 가진 시스템에서는 메뉴얼 페이지들을 /usr/man 디렉토리 안의 man[1-9] 디렉토리에 보관할 수 있다. (이것은 전통적인 환경이고 배치이다.)"
나는
xman, tkman, info와 같이 메뉴얼 페이지를 읽을 수 있는 모든 도구들이 새로운 환경을 지원할 때까지 새로운 디렉토리 구성으로 전환하지 않을 것이다.
3. 형식화된 메뉴얼 페이지는 어떻게 보이는가? ¶우선 예제를 하나 보고 난 다음, 자세한 설명을 하겠다.
아래 보이는 메뉴얼 페이지는 가상의 프로그램인
foo에 대한 메뉴얼 페이지이다.
FOO(1) User Manuals FOO(1)
이름
foo - bar 라이브러리를 조정한다.
사용법
foo [-bar] [-c config-file ] file ...
설명
foo는 내부 심볼 테이블을 조정해서 bar 라이브러리를 조정한다. 기본적
으로 모든 baz 세그먼트를 분석해서, xyzzy(1) 링커가 참조할 수 있도록
시간의 역순으로 정렬한다. symdef의 엔트리는 WBG (Whiz-Bang-Gizmo)
알고리즘을 이용해 압축된다. 모든 파일은 주어진 순서대로 처리된다.
옵션
-b 처리 도중 표준 출력에 `busy' 를 출력하지 않는다.
-c config-file
설정 파일 /etc/foo.conf 대신 지정된 config-file을 사용한다.
이 옵션은 환경 변수 FOOCONF에 우선한다.
-a baz 세그먼트와 함께 blurfl 헤더도 분석한다.
-r 재귀 처리 모드. 대용량의 가상 메모리를 사용해 빠른 속도로 처리
한다.
파일
/etc/foo.conf
시스템 전반에 관련되는 설정 파일. 자세한 것은 foo(5)를 참조하라.
~/.foorc
사용자 개인의 설정 파일. 자세한 것은 foo(5)를 참조하라.
환경 변수
FOOCONF
설정되어 있는 경우에 이것은 시스템 전반에 작용하는 다른 설정 파일
foo.conf의 전체 경로 이름을 나타낸다. -c 옵션이 우선한다.
진단
표준 에러 출력에 아래와 같은 진단 메세지가 표시된다.
Bad magic number.
주어진 입력 파일은 기록 파일이 아니다.
Old style baz segments.
foo는 새로운 형식의 baz 세그먼트만을 처리할 수 있다. 이 버젼에서
는 COBOL의 목적 라이브러리를 처리할 수 없다.
버그
명령의 이름은 분명하게 명령의 목적을 알 수 있는 것으로 해야한다.
저자
Jens Schweikhardt <howto at schweikhardt dot net>
관련 항목
bar(1), foo(5), xyzzy(1)
Linux Last change: MARCH 1995 2
자, 이제 상세한 설명을 보도록 하자.
3.1. 이름 섹션 (NAME section) ¶이름 섹션은 반드시 있어야 하는 섹션이다. 이름 섹션이 없으면 메뉴얼 페이지는 북극점에서 냉장고 수준의 가치 밖에 없다. 이름 섹션은 쉼표로 단락지어진 프로그램이나 함수의 리스트와 데쉬(-)로 이어지는 설명(보통 한 줄), 즉 프로그램이나 함수, 파일이 수행하는 기능의 짧은 설명으로 이루어진 표준화된 형식을 가진다.
makewhatis.8는 이름 섹션을 이용해 whatis 데이타베이스 파일을 작성한다. makewhatis에서 사용하므로 이름 섹션이 필수이며, 형식이 표준화되고 있는 것이다. groff 형식의 소스에서는 반드시 다음과 같이 되어야 한다.
.SH 이름 foo \- bar 라이브러리를 조정한다. 여기서 "
\-"는 중요하다. 백슬레쉬(backslash)는 데쉬를 명령 이름이나 간단한 설명에 나오는 하이포네이션의 데쉬와 구별하기 위해서 필요하다.
3.2. 사용법 섹션 (SYNOPSIS section) ¶사용법 섹션은 설정할 수 있는 옵션에 대한 간단한 설명이 포함된다. 함수에 대해서는 프로그래머가 매개 변수의 형태와 갯수, 반환값의 데이터형을 알 수 있도록 이 섹션에 해당 헤더 파일과 함수 원형이 나타난다.
3.3. 설명 섹션 (DESCRIPTION section) ¶설명 섹션에서는 이 프로그램이 도대체 어떤 가치가 있는가에 대해 자세한 설명이 나타난다. 이 섹션을 쓸 때는 알고 있는 모든 것을 써야 한다. 말하자면 "명성의 전당"이다. 다른 프로그래머나 사용자의 칭찬을 얻기 위해서는, 자세하고 신뢰할 수 있는 정보로 이 섹션을 작성해야 한다. 어느 인수가 무엇을 위해서 있으며, 어떤 파일 형태가 이용되고, 어떤 알고리즘이 프로그램 처리에 이용되고 있는지 설명해야 한다.
3.4. 옵션 섹션 (OPTIONS section) ¶옵션 섹션에서는 각 옵션이 프로그램의 동작에게 주는 영향에 대해 설명된다. 자신의 프로그램이니 사용되는 옵션에 대해서는 잘 알고 있을 것이다. 여기에 그 설명들을 적으면 된다.
3.5. 파일 섹션 (FILES section) ¶파일 섹션에서는 프로그램 또는 함수가 사용하는 파일을 나열한다. 예를 들어, 설정 파일, 초기 파일, 프로그램이 직접 조작하는 파일 등이 여기에 포함된다. 이러한 파일의 전체 경로명을 기재해 사용자의 취향에 맞게, 설치하는 디렉토리를 변경할 수 있도록 설치 과정을 만드는 것이 좋은 생각이다. 예를 들면,
groff의 메뉴얼에서는 기본 디렉토리가 /usr/local이고, 보통 /usr/local/lib/groff/* 파일을 참조한다. 그러나 'make prefix=/opt/gnu'라고 실행해 설치하면, 메뉴얼 페이지에서 /opt/gnu/lib/groff/* 파일을 참조하도록 변경된다.
3.6. 환경 변수 섹션 (ENVIRONMENT section) ¶환경 변수 섹션에서는 프로그램이나 함수에 관한 환경 변수들이 나열되고, 어떤 영향을 주는지에 대한 설명이 나타난다. 보통 환경 변수에 의해 경로명이나 파일명, 기본 옵션이 지정된다.
3.8. 버그 섹션 (BUGS section) ¶버그 섹션은 이상적으로는 없는 것이 좋다. 용기가 있다면, 프로그램의 제한이라든지, 알고 있는 프로그램의 불편한 점, 다른 사람이 이상한 것으로 간주하는 기능에 대해 쓰면 좋다. 용기가 없으면, "추후 계획"(TO DO)이라고 이름을 바꾸자.
.png ";-)")
3.10. 관련 항목 섹션 (SEE ALSO section) ¶관련 항목 섹션은 관련된 메뉴얼 페이지의 알파벳 순서로 나열된다. 관습적으로 마지막에 기술한다.
위에 설명한 섹션에 맞지 않는 내용에 대해서는 다른 섹션을 만들어 사용해도 상관없다.
자, 그럼 정확히 메뉴얼 페이지를 만들었는가? 위에 나온
foo 메뉴얼 페이지의 소스를 보도록 하자.
.\" 이 파일을 다음 명령으로 처리하면 된다. .\" groff -man -Tascii foo.1 .\" .TH FOO 1 "MARCH 1995" Linux "User Manuals" .SH 이름 foo \- bar 라이브러리를 조정한다. .SH 사용법 .B foo [-bar] [-c .I config-file .B ] .I file .B ... .SH 설명 .B foo 는 내부 심볼 테이블을 조정해서 bar 라이브러리를 조정한다. 기본적으로 모든 baz 세그먼트를 분석해서, .BR xyzzy (1) 링커가 참조할 수 있도록 시간의 역순으로 정렬한다. symdef의 엔트리는 WBG (Whiz-Bang-Gizmo) 알고리즘을 이용해 압축된다. 모든 파일은 주어진 순서대로 처리된다. .SH 옵션 .IP -b 처리 도중 표준 출력에 `busy' 를 출력하지 않는다. .IP "-c config-file" 설정 파일 .IR /etc/foo.conf 대신 지정된 .I config-file 을 사용한다. 이 옵션은 환경 변수 .B FOOCONF 에 우선한다. .IP -a baz 세그먼트와 함께 blurfl 헤더도 분석한다. .IP -r 재귀 처리 모드. 대용량의 가상 메모리를 사용해 빠른 속도로 처리한다. .SH 파일 .I /etc/foo.conf .RS 시스템 전반에 관련되는 설정 파일. 자세한 것은 .BR foo (5) 를 참조하라. .RE .I ~/.foorc .RS 사용자 개인의 설정 파일. 자세한 것은 .BR foo (5) 를 참조하라. .SH "환경 변수" .IP FOOCONF 설정되어 있는 경우에 이것은 시스템 전반에 작용하는 다른 설정 파일 .IR foo.conf 의 전체 경로 이름을 나타낸다. .B -c 옵션이 우선한다. .SH 진단 표준 에러 출력에 아래와 같은 진단 메세지가 표시된다. Bad magic number. .RS 주어진 입력 파일은 기록 파일이 아니다. .RE Old style baz segments. .RS .B foo 는 새로운 형식의 baz 세그먼트만을 처리할 수 있다. 이 버젼에서는 COBOL의 목적 라이브러리를 처리할 수 없다. .SH 버그 명령의 이름은 분명하게 명령의 목적을 알 수 있는 것으로 해야한다. .SH AUTHOR Jens Schweikhardt <howto at schweikhardt dot net> .SH "관련 항목" .BR bar (1), .BR foo (5), .BR xyzzy (1) 4. 여러 프로그램/함수의 메뉴얼 페이지를 하나의 메뉴얼 페이지로 묶기 ¶많은 프로그램(예를 들면
grep, egrep)이나 함수(예를 들면 printf, fprintf, ...)는 하나의 메뉴얼 페이지 안에 설명되어 있다. 그러나 이러한 메뉴얼 페이지가 하나의 명칭만으로 참조 가능다면, 정말 불편할 것이다. 사용자가 egrep 메뉴얼 페이지가 실제는 grep의 메뉴얼 페이지라고 기억하고 있어 주는 것은 기대할 수 없는 것이다. 따라서, 이런 메뉴얼 페이지는 여러 이름으로 이용할 수 있도록 하는 것이 필요하게 된다. 이를 가능하게 하는 방법에는 여러 가지가 있다.
catman 프로그램의 개선 버전에서는 파일 형식이나 내용을 찾는데 많은 처리를 생략하게 하므로 추천할 만한 방법이 아니다. catman 프로그램은 하드 링크를 적절히 처리하지 못한다. (catman의 목적은 모든 메뉴얼 페이지를 형식화해 보다 빨리 표시할 수 있도록 하는 것이다.) 세번째 방법은 단점이 있다. 유연성이 중요한 경우, 기호 연결(symbolic link)을 지원하지 않는 파일 시스템이 있다는 것을 염두에 두지 않으면 안된다. 결국 제일 적절한 방법은 groff의 소스 메카니즘을 이용하는 것이다.
즉, 다음과 같이 한다. 메뉴얼 페이지를
foo와 bar라는 이름으로 1 섹션에 만들고자 할 때, 실제 메뉴얼 페이지를 foo.1으로 작성하고, bar.1에는 다음과 같이 적으면 된다.
.so man1/foo.1 중요한 것은 디렉토리명
man1/을 파일명 foo.1과 함께 지정하는 것이다. 이것은 groff가 탐색기로부터 실행되었을 때 메뉴얼 페이지의 표준 디렉토리를 현재 작업 디렉토리(cwd)로 하기 때문으로, groff는 이 cwd를 기준으로 .so의 인수를 해석하게 된다.
5. 어떤 매크로 패키지를 사용할 것인가? ¶메뉴얼 페이지를 쓸 때 사용할 수 있도록 특별히 만들어진 매크로 패키지가 몇가지 있다. 보통 이런 매크로는
groff 매크로 디렉토리인 /usr/lib/groff/tmac 안에 있다. 파일명은 tmac.<something>과 같이 되어 있고, <something>은 groff의 -m 옵션의 인수가 된다. groff는 -m <something> 옵션이 지정됐을 때 매크로 파일 "tmac.<something>"을 사용한다. 보통 "-m"과 "<something>" 사이의 빈칸은 생략되고, 메뉴얼 페이지를 형식화하기 위해 "groff -man"을 사용하게 되면 tmac.an 매크로 패키지가 사용된다. 이런 이유 때문에 메뉴얼 페이지를 형식화하는 매크로 패키지의 이름이 조금은 이상한 "tmac.an"으로 되었다.
자주 사용되는 패키지로
tmac.an 외에도 tmac.doc라는 매크로 패키지가 있다. 이것은 캘리포니아 대학 버클리 분교(UC at Berkeley)에서 개발된 것이다. 많은 BSD 메뉴얼 페이지가 이 패키지를 이용하고 UCB는 이 패키지를 문서화의 표준으로 만들고자 하는 것 같다. tmac.doc은 매우 유연하지만, 불행히도 많은 메뉴얼 탐색기가 이 패키지를 사용하지 않고 항상 "groff -man"을 호출한다. 예를 들어, 모든 xman 프로그램은 tmac.doc을 이용하는 메뉴얼 페이지를 엉망으로 출력한다. 따라서, 가급적 tmac.an을 사용하는 것이 좋다. 다른 매크로 패키지를 사용하는 것은 별로 좋은 생각이 아니다. tmac.andoc 매크로 패키지는 유사 매크로 패키지이며, 메뉴얼 페이지의 소스를 보고 tmac.an을 사용할지 tmac.doc을 사용할지 결정하게 된다.
당연히 모든 메뉴얼 페이지 탐색기가 이
tmac.andoc 패키지를 사용하는 것이 옳은 일이지만, 애석하게도 그렇지 있기 때문에 최선의 방법은 오래된 tmac.an 매크로를 쓸 수 밖에 없다. 그래서, 이제부터 메뉴얼 페이지 매크로에 대해서는 tmac.an에 대해서만 설명한다. 만약 tmac.doc 매크로를 사용하고 싶다면, ![[http]](/imgs/http.png) mdoc.samples을 참고하기 바란다. 여기에 가면 mdoc.7, mdoc.samples.7, groff_man.7등도 볼 수 있다.
위에서 언급한 모든 매크로를 포함하는
troff의 완전한 정보는 troff 사용자 설명서에서 볼 수 있다.
이 설명서는 1992년 11월 Jospeh F. Ossanna과 Brian W. Kernighan가 작성하였으며, HTML, PS (760K), PDF (240K) 버전으로 볼 수 있다. AT&T Bell 연구소는 이것을 공개하였다. 그리고, "Unix Network Programming"과 "TCP/IP Illustrated"로 유명한 W. Richard Steven의 홈페이지에 들려보기 바란다. 여기에는 tbl, eqn, pic, 그리고 다른 필터들에 대한 정보를 포함한 Troff 자원에 대한 목록이 나와있다.
6. 어떤 선행처리기를 사용할 수 있는가? ¶groff는 적어도 tbl, eqn, pic 세 개의 선행처리기(preprocessor)를 사용한다. (가끔 어떤 시스템에서는 gtbl, geqn, gpic 이라는 이름으로 사용된다.) 이런 선행처리기는 선행처리기 매크로를 해석해서 데이터를 일반적인 troff 입력에 적합하도록 변환하는 일을 한다. tbl은 표에 관련된 선행처리기이며, eqn은 방정식/수학용 선행처리기, pic은 그림에 관련된 선행처리기이다. 각각의 자세한 설명은 메뉴얼 페이지를 참고해주기 바란다. 가능하다면, 메뉴얼 페이지는 어떠한 선행처리기도 사용하지 않도록 작성해야 한다.
eqn 선행처리기는 메뉴얼 페이지를 보여줄 수 있는 장치 중 99% 정도가 사용되는 타자기와 비슷한 장치(typewriter-like device, 모니터가 대표적인 장치이다.)에 대해서 정말 끔찍한 출력을 보여준다. 예를 들어, XAllocColor.3x는 지수 표기를 갖는 수식을 표현하는 사용된다. 타자기와 비슷한 장치이기 때문에 지수는 기수와 같은 줄에 표현된다. 즉, N의 제곱은 "N2"와 같이 표시된다.
tbl의 사용은 자제해야 한다. 모든 xman 프로그램들은 이를 제대로 처리하지 못한다. 예를 들어, signal.7페이지를 형식화하는데 xman 3.1.6은 다음과 같은 명령을 사용한다.
gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff -Tascii -man /tmp/xmana01760 2> /dev/null 이 명령은
gtbl 선행처리기를 사용하는 것으로, gtbl로 처리된 결과가 다시 한번 gtbl로 처리되기 때문에 결과를 엉망으로 만들어버린다. 처리 결과는 의도한 표가 없어진 메뉴얼 페이지가 된다. 이것이 버그인지, gtbl 선행처리기가 자신의 출력을 매워버리는 기능인지, 아니면 gtbl이 두 번 사용되서는 안되는 것인지는 알 수 없다. 어떤 시스템에서는 groff를 사용하는데 어떤 옵션을 사용할 것인지 확인하기 위해 grog를 사용하기도 한다. 하지만 불행히도 종종 tbl이 사용되지 말아야 하는데도 grog는 잘못 판단하여 groff -t를 사용하도록 추천한다. 만약 표를 사용하고 싶다면 다음과 같이 쓰는 것이 좋다.
pic 선행처리를 하는 메뉴얼 페이지를 본 적은 없다. 하지만, 메뉴얼 페이지에서 pic 선행처리기를 쓴다는 것은 바람직하지 않다고 생각한다. 위에서 봤듯이, xman은 pic 선행처리기를 사용하지 않고 groff도 입력을 제대로 처리하지 못한다.
7. 배포해야 할 것은 메뉴얼 페이지 소스인가? 아니면 형식화된 문서인가? ¶몇몇 가능성에 대해 장점과 단점을 정리해보도록 하자.
groff가 없는 시스템에서 이용할 수 없다는 것은 중요하지 않다. 리눅스 문서 프로젝트에 있는 500 페이지 이상의 메뉴얼 페이지는 소스만 있을 뿐이다. !XFree86의 메뉴얼 페이지도 소스만 배포한다. FSF의 메뉴얼 페이지 역시 소스만 배포하고 있다. 실제로 형식화된 메뉴얼 페이지를 배포하는 소프트웨어를 본 적이 없다. 시스템 관리자가 메뉴얼 페이지를 이용할 수 있도록 해놨다면, groff도 이미 설치되어 있을 것이다.
8. 글꼴 규정이 무엇인가? ¶우선
\fB, \fP와 같은 직접적인 글꼴 연산자를 사용하지 않도록 하라. 인자를 지정하는 매크로는 사용하는 것이 좋다. 이 방법을 사용하면 글꼴 변경 범위의 끝에서 글꼴 변경을 잊어, 다음 글꼴 변경이 나올 때까지 굵은 글꼴이나 기울린 글꼴이 연장되는 사소한 실수를 피할 수 있다. 믿지 않겠지만, 이런 실수는 자주 일어난다.
tmac.an 매크로에서는 다음과 같은 글꼴을 사용할 수 있다.
X와 Y의 교차"라는 것은 홀수번째 인자의 글꼴이 X가 되고, 짝수번째 인자의 글꼴이 Y가 되는 것이다.
예를 들어,
.BI "인자 1은 굵은 글꼴, " "인자 2는 기울린 글꼴, " "다음은 굵은 글꼴, " "그리고 기울린 글꼴" 여기에서 인자가 공백을 포함하는 경우에는 쌍따옴표로 묶어줘야 한다. 쌍따옴표를 적지 않으면, 각 단어는 하나의 인자로 인식된다.
이러한 글꼴 교차는 글꼴이 다르게 적용되는 단어 사이에 공백 문자가 들어가지 않게 만들기 위해 사용된다.
(특히 한글 메뉴얼 페이지의 경우는 조사를 명사와 붙여서 보이게 하기 위해 아주 적절히 사용할 수 있다.)
아래는 다른 글꼴들을 어떻게 사용할 것인지를 보여준다. (이것은
man.7내용의 일부를 그대로 가져온 것이다.)
UNIX 세계에서는 메뉴얼 페이지에 대해 많은 까다로운 규정이 있지만, 우리에게는 수백개의 Linux 전용 메뉴얼 페이지들이 표준이다.
함수에서 매개 변수는 항상 기울린 글꼴을 사용한다. 심지어 "사용법" 절에서도 함수의 다른 부분은 굵은 글꼴로 표현하더라도 매개 변수만은 기울린 글꼴을 사용한다.
.BI "myfunction(int " argc ", char **" argv ); 파일 이름은 "사용법" 절을 제외하고는 항상 기울린 글꼴을 사용한다. 그리고, "include" 문법을 사용할 때는 굵은 글꼴을 사용한다.
.I /usr/include/stdio.h .B #include <stdio.h> 보통 대문자로 표현되는 특별한 매크로들은 굵은 글꼴을 사용한다.
.B MAXINT 에러 코드를 나열할 때, 코드는 굵은 글꼴로 한다. 이 목록은 보통
.TP 매크로를 사용한다.
.TP .B EBADF .I fd 는 적절한 파일 식별자가 아니다. .TP .B EINVAL .I fd 는 읽기에 적절치 않다. 다른 메뉴얼 페이지에 대한 참조나 현재 메뉴얼 페이지의 제목에 대한 참조는 굵은 글꼴로 나타낸다. 메뉴얼의 섹션 번호는 공백 없이 로만체로 나타낸다.
.BR man (7) 줄임말은 작은 글꼴로 나타내는 것이 보기 좋으므로 이를 추천한다.
.SM UNIX .SM ASCII .SM TAB .SM NFS .SM LALR(1) 9. 메뉴얼 페이지 다듬기 ¶아래는 문서의 신뢰성, 가독성, 볼품을 개선하기 위한 지침이다.
10. 메뉴얼 페이지에서 ^H, ^_ 등이 없는 일반 텍스트 파일를 어떻게 만드는가? ¶funnyprompt$ groff -t -e -mandoc -Tascii manpage.1 | col -bx > manpage.txt -t와 -e 옵션은 groff가 tbl과 eqn 선처리기를 사용하도록 지정한다. 선처리가 필요하지 않은 메뉴얼 페이지에 대해서는 필요없는 옵션이지만, 이 옵션은 수 CPU 사이클만을 사용하기 때문에 별 문제는 없을 것이다. 하지만, -t 옵션이 필요할 때 지정하지 않는다면 메뉴얼 페이지의 표가 심하게 훼손되어 버리기 때문에 가급적이면 -t 옵션을 지정해주는 것이 좋다.
단순히 메뉴얼 페이지 뿐만 아니라 어떤
groff 문서를 형식화하는데 어떤 옵션이 필요한지 짐작하기 위해 다음과 같은 명령을 사용하면 된다.
funnyprompt$ grog /usr/man/man7/signal.7 groff -t -man /usr/man/man7/signal.7 "
grog"는 "GROff Guess"를 의미하고, 이 프로그램이 뭘하는지는 이름에서 짐작할 수 있을 것이다. grog가 완전하다면 groff를 사용하는데 더이상 옵션을 지정할 필요가 없어질텐데, 애석하게도 grog가 매크로 패키지와 선행처리기에 대해 잘못 판단하는 일이 종종 있다.
아래 스크립트는 페이지 머릿말과 꼬리말을 삭제하기 위해 작성한 간단한 perl 스크립트이다. 이것을 사용하면 길고 상세한 메뉴얼 페이지를 인쇄할 때는 몇 페이지는 줄일 수 있다. 이 스크립트를 "
strip-headers"라는 이름으로 저장하고 "chmod 755"로 파일 허가권을 바꾸기 바란다.
#!/usr/bin/perl -wn
# make it slurp the whole file at once:
undef $/;
# delete first header:
s/^\n*.*\n+//;
# delete last footer:
s/\n+.*\n+$/\n/g;
# delete page breaks:
s/\n\n+[^ \t].*\n\n+(\S+).*\1\n\n+/\n/g;
# collapse two or more blank lines into a single one:
s/\n{3,}/\n\n/g;
# see what's left...
print;
이 스크립트는
groff에서 출력되는 개행의 수에 처리를 의존하기 때문에, 이 스크립트를 사용할 때는 반드시 다음과 같이 "man" 명령 다음에 첫번째 필터로 사용해야 한다.
funnyprompt$ man bash | strip-headers | col -bx > bash.txt 11. 고품질의 PostScript 메뉴얼 페이지 만들기 ¶아래 명령을 사용해서
ps 파일을 만든 다음, PostScript 프린터나 뷰어를 통해 출력하거나 볼 수 있다.
사용된 옵션에 대한 자세한 설명은 10절을 참고하기 바란다.
funnyprompt$ groff -t -e -mandoc -Tps manpage.1 > manpage.ps 12. "apropos"와 "whatis" 사용하기 ¶예를 들어, 사용하는 시스템에 어떤 컴파일러가 설치되어 있고 어떻게 실행할 수 있는지 알아보고 싶다고 가정해보자.
이런 경우 다음과 같이 하면 답을 얻을 수 있다.
funnyprompt$ apropos compiler f77 (1) - Fortran 77 compiler gcc (1) - GNU C and C++ compiler pc (1) - Pascal compiler apropos와 whatis는 어떤 주제에 대한 정보가 어떤 메뉴얼 페이지에 있는지 빠른 결과를 보여준다.
이 두 프로그램은 각각의 메뉴얼 기본 디렉토리에 있는 "whatis" 파일들을 검색한다. 전에 말한 것처럼 whatis 데이터베이스 파일은 각각의 디렉토리에 있는 메뉴얼 페이지에 대한 한 줄짜리 정보를 담고 있다. 이 정보는 "이름" 섹션에 나와있는 것이다. (정확히 말하면, 한 줄로 합치고 하이픈을 없앤 형태이다. 이 정보에서 메뉴얼 섹션 번호는 괄호로 묶여 있다.)
whatis 데이터베이스 파일은 makewhatos.8에 의해 작성된다. 여러 버전이 있기 때문에 어떤 옵션이 사용 가능한지 메뉴얼 페이지에 언급해두는 것이 좋다. makewhatis 프로그램이 "이름" 섹션을 제대로 뽑아내기 위해서는 메뉴얼의 저자가 3절에서 설명한데로 정확한 형식을 지키는 것이 중요하다.
apropos와 whatis의 차이는 검색하는 부분이 다르다는 것뿐이다.
aprospos는 "man -k"와 같은 의미이며 데이터베이스의 줄 전체에 대한 검색을 하는 것이고,
whatis는 "man -f"와 같은 의미로 데이터베이스에서 각 줄의 데쉬 이전, 즉 명령 이름에 대해서만 일치하는 것을 찾는다. 따라서, "whatis cc"을 실행하면 cc에 대한 정보는 출력하지만, gcc에 대한 정보는 출력하지 않는다.
잘못된 점의 수정이나 제안은 언제나 환영한다!
13. 저작권 ¶Copyright 1995-2001 by Jens Schweikhardt. All rights reserved.
"Two clause" BSD License:
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
14. 감사의 글 ¶
15. 수정 내역 ¶
|
"Heck, I'm having a hard time imagining the DOM as civilized!" -- Fred L. Drake, Jr.    
|
