'''Linux Man Page HOWTO'''
* Jens Schweikhardt <howto@schweikhardt.net>
* Pradeep Padala - Conversion from HTML to !DocBook v4.1. 2002-09-07.
* [윤현호] <hhyoon@kldp.org> 한글 버전으로 번역. 2004-03-24.
이 HOWTO는 Manpage:man.1 명령어를 통해 볼 수 있는 온라인 문서(이른바 메뉴얼 페이지, manpage)를 작성하고자 할 때, 주의해야 할 사항에 대해 설명한다.
이 HOWTO의 최신 영문 버전은 http://www.tldp.org/HOWTO/Man-Page/index.html 에서 구할 수 있으며,
한글 버전은 http://man.kldp.org/wiki/LinuxManPageHOWTO 에서 볼 수 있다.
----
[[TableOfContents]]
== 문서화에 대한 몇가지 고찰 ==
왜 문서를 작성하는가? 이것은 바보스러운 질문일지도 모른다.
여기에 대한 답은 우리가 만든 프로그램이나 라이브러리, 함수, 그리고 그외의 우리가 작성하고 만든 것들을 다른 사람들이 쓸 수 있기를 원하기 때문이다. 그러나, 문서를 쓴다는 것은 이것이 전부는 아니다.
* 문서는 누구나 쉽게 볼 수 있어야 한다. 문서화에 관련된 도구가 찾을 수 없는 장소에 있다면, 그 목적을 이룰 수 없다.
* 문서는 신뢰할 수 있고 정확해야 한다. 프로그램 동작과 문서가 일치하지 않는 것만큼 짜증나는 것은 없다. 사용자들은 당신에게 악담을 하고, 원한이 가득 담긴 메일을 보내고, 프로그램을 삭제한 후, 이 얼간이가 만든 그 어떤 것이라도 다시는 인스톨하지 않을 것이라고 다짐할 것이다.
유닉스에서 역사적으로 잘 알려진 문서화 방법은 Manpage:man.1 명령어를 이용하는 것이다. 이 HOWTO는 문서화에 관련된 도구가 올바르게 처리할 수 있는 메뉴얼 페이지를 작성하기 위해 해야할 일을 설명한다. 이러한 도구들 중 중요한 것에는 Manpage:man.1, Manpage:xman.1x, Manpage:apropos.1, Manpage:makewhatis.8, Manpage:catman.8 등이 있다. 물론 정보의 신뢰성과 정확성은 전적으로 문서를 작성하는 사람에게 달려있다.
[#s-9 9절]을 보면 흔히 할 수 있는 실수를 피하는데 도움이 될 것이다.
== 메뉴얼 페이지에는 어떻게 접근하는가? ==
메뉴얼 페이지에 적당한 이름을 주고 올바른 장소에 설치하기 위해서는, 메뉴얼 페이지가 어떻게 접근되는지 정확한 구조를 알아야 한다. 모든 메뉴얼 페이지는 한 특정 섹션에 포함되어야 하고, 섹션은 한 글자로 표현된다. 리눅스에서 가장 일반적으로 사용되는 섹션과 그 의미는 다음과 같다.
{{{
섹션 이름
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>}}}는 [#s-2 위 표]에서 설명한 섹션을 나타내는 하나의 문자이다. 이 디렉토리에 모든 섹션에 대응하는 하위 디렉토리가 설치될 필요는 없다. 이것은 비어있는 하위 디렉토리를 둘 필요가 없기 때문이다. 그런데, 혹시 화면에 출력하거나 인쇄할 목적의 문서를 가지고 있는 "{{{cat<s>}}}", "{{{dvi<s>}}}" "{{{ps<s>}}}" 등과 같은 디렉토리가 있을 수도 있다. 이에 대해서는 나중에 자세히 설명하도록 하겠다.
기본 디렉토리에 있는 다른 파일은 {{{whatis}}}에 관련된 파일 뿐이다. 이 파일의 목적과 작성에 대해서는 [#s-12 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}}}와 같이 메뉴얼 페이지를 읽을 수 있는 모든 도구들이 새로운 환경을 지원할 때까지 새로운 디렉토리 구성으로 전환하지 않을 것이다.
== 형식화된 메뉴얼 페이지는 어떻게 보이는가? ==
우선 예제를 하나 보고 난 다음, 자세한 설명을 하겠다.
아래 보이는 메뉴얼 페이지는 가상의 프로그램인 {{{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
}}}
자, 이제 상세한 설명을 보도록 하자.
=== 이름 섹션 (NAME section) ===
이름 섹션은 반드시 있어야 하는 섹션이다. 이름 섹션이 없으면 메뉴얼 페이지는 북극점에서 냉장고 수준의 가치 밖에 없다. 이름 섹션은 쉼표로 단락지어진 프로그램이나 함수의 리스트와 데쉬(-)로 이어지는 설명(보통 한 줄), 즉 프로그램이나 함수, 파일이 수행하는 기능의 짧은 설명으로 이루어진 표준화된 형식을 가진다. Manpage:makewhatis.8''''''는 이름 섹션을 이용해 {{{whatis}}} 데이타베이스 파일을 작성한다. {{{makewhatis}}}에서 사용하므로 이름 섹션이 필수이며, 형식이 표준화되고 있는 것이다. {{{groff}}} 형식의 소스에서는 반드시 다음과 같이 되어야 한다.
{{{
.SH 이름
foo \- bar 라이브러리를 조정한다.
}}}
여기서 "{{{\-}}}"는 중요하다. 백슬레쉬(backslash)는 데쉬를 명령 이름이나 간단한 설명에 나오는 하이포네이션의 데쉬와 구별하기 위해서 필요하다.
=== 사용법 섹션 (SYNOPSIS section) ===
사용법 섹션은 설정할 수 있는 옵션에 대한 간단한 설명이 포함된다. 함수에 대해서는 프로그래머가 매개 변수의 형태와 갯수, 반환값의 데이터형을 알 수 있도록 이 섹션에 해당 헤더 파일과 함수 원형이 나타난다.
=== 설명 섹션 (DESCRIPTION section) ===
설명 섹션에서는 이 프로그램이 도대체 어떤 가치가 있는가에 대해 자세한 설명이 나타난다. 이 섹션을 쓸 때는 알고 있는 모든 것을 써야 한다. 말하자면 "명성의 전당"이다. 다른 프로그래머나 사용자의 칭찬을 얻기 위해서는, 자세하고 신뢰할 수 있는 정보로 이 섹션을 작성해야 한다. 어느 인수가 무엇을 위해서 있으며, 어떤 파일 형태가 이용되고, 어떤 알고리즘이 프로그램 처리에 이용되고 있는지 설명해야 한다.
=== 옵션 섹션 (OPTIONS section) ===
옵션 섹션에서는 각 옵션이 프로그램의 동작에게 주는 영향에 대해 설명된다. 자신의 프로그램이니 사용되는 옵션에 대해서는 잘 알고 있을 것이다. 여기에 그 설명들을 적으면 된다.
=== 파일 섹션 (FILES section) ===
파일 섹션에서는 프로그램 또는 함수가 사용하는 파일을 나열한다. 예를 들어, 설정 파일, 초기 파일, 프로그램이 직접 조작하는 파일 등이 여기에 포함된다. 이러한 파일의 전체 경로명을 기재해 사용자의 취향에 맞게, 설치하는 디렉토리를 변경할 수 있도록 설치 과정을 만드는 것이 좋은 생각이다. 예를 들면, {{{groff}}}의 메뉴얼에서는 기본 디렉토리가 {{{/usr/local}}}이고, 보통 {{{/usr/local/lib/groff/*}}} 파일을 참조한다. 그러나 '{{{make prefix=/opt/gnu}}}'라고 실행해 설치하면, 메뉴얼 페이지에서 {{{/opt/gnu/lib/groff/*}}} 파일을 참조하도록 변경된다.
=== 환경 변수 섹션 (ENVIRONMENT section) ===
환경 변수 섹션에서는 프로그램이나 함수에 관한 환경 변수들이 나열되고, 어떤 영향을 주는지에 대한 설명이 나타난다. 보통 환경 변수에 의해 경로명이나 파일명, 기본 옵션이 지정된다.
=== 진단 섹션 (DIAGNOSTICS section) ===
진단 섹션에는 프로그램에서 출력되는 에러 메세지의 간단한 설명과 해당 에러 메세지를 어떻게 처리해야 하는가에 대해 설명한다. 프로그램을 실행했을 때에 나타날지도 모르는 시스템 오류 메시지(Manpage:perror.3 로부터)라든지, 치명적인 신호(Manpage:psignal.3 로부터)에 대해서 설명할 필요는 없다.
=== 버그 섹션 (BUGS section) ===
버그 섹션은 이상적으로는 없는 것이 좋다. 용기가 있다면, 프로그램의 제한이라든지, 알고 있는 프로그램의 불편한 점, 다른 사람이 이상한 것으로 간주하는 기능에 대해 쓰면 좋다. 용기가 없으면, "추후 계획"(TO DO)이라고 이름을 바꾸자. ;-)
=== 저자 섹션 (AUTHOR section) ===
프로그램의 동작이라든지 문서에 오류가 있어, 버그 보고를 받기를 원한다면, 저자 섹션을 적는 것은 괜찮은 방법이다.
=== 관련 항목 섹션 (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)
}}}
== 여러 프로그램/함수의 메뉴얼 페이지를 하나의 메뉴얼 페이지로 묶기 ==
많은 프로그램(예를 들면 {{{grep}}}, {{{egrep}}})이나 함수(예를 들면 {{{printf}}}, {{{fprintf}}}, ...)는 하나의 메뉴얼 페이지 안에 설명되어 있다. 그러나 이러한 메뉴얼 페이지가 하나의 명칭만으로 참조 가능다면, 정말 불편할 것이다. 사용자가 {{{egrep}}} 메뉴얼 페이지가 실제는 {{{grep}}}의 메뉴얼 페이지라고 기억하고 있어 주는 것은 기대할 수 없는 것이다. 따라서, 이런 메뉴얼 페이지는 여러 이름으로 이용할 수 있도록 하는 것이 필요하게 된다. 이를 가능하게 하는 방법에는 여러 가지가 있다.
1. 각각의 이름에 대해 파일의 복사본을 준비한다.
1. 하드 링크(hard link)로 모든 메뉴얼 페이지를 링크한다.
1. 실제의 메뉴얼 페이지를 기호 연결(symbolic link)로 지정한다.
1. {{{groff}}}의 {{{.so}}} 매크로에 의한 소스 기능을 이용한다.
첫번째 방법은 디스크를 쓸데없이 낭비하게 된다. 두번째 방법은 {{{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}}}의 인수를 해석하게 된다.
== 어떤 매크로 패키지를 사용할 것인가? ==
메뉴얼 페이지를 쓸 때 사용할 수 있도록 특별히 만들어진 매크로 패키지가 몇가지 있다. 보통 이런 매크로는 {{{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://www.freebsd.org/cgi/man.cgi?query=mdoc.samples mdoc.samples]을 참고하기 바란다. 여기에 가면 Manpage:mdoc.7, Manpage:mdoc.samples.7, Manpage:groff_man.7 등도 볼 수 있다.
위에서 언급한 모든 매크로를 포함하는 {{{troff}}}의 완전한 정보는 {{{troff}}} 사용자 설명서에서 볼 수 있다.
이 설명서는 1992년 11월 Jospeh F. Ossanna과 Brian W. Kernighan가 작성하였으며, [http://cm.bell-labs.com/sys/doc/troff.html HTML], [http://cm.bell-labs.com/sys/doc/troff.ps PS (760K)], [http://cm.bell-labs.com/sys/doc/troff.pdf PDF (240K)] 버전으로 볼 수 있다. AT&T Bell 연구소는 이것을 공개하였다. 그리고, "Unix Network Programming"과 "TCP/IP Illustrated"로 유명한 [http://www.kohala.com/start/ W. Richard Steven]의 홈페이지에 들려보기 바란다. 여기에는 tbl, eqn, pic, 그리고 다른 필터들에 대한 정보를 포함한 [http://www.kohala.com/start/troff/troff.html Troff 자원]에 대한 목록이 나와있다.
== 어떤 선행처리기를 사용할 수 있는가? ==
{{{groff}}}는 적어도 {{{tbl}}}, {{{eqn}}}, {{{pic}}} 세 개의 선행처리기(preprocessor)를 사용한다. (가끔 어떤 시스템에서는 {{{gtbl}}}, {{{geqn}}}, {{{gpic}}} 이라는 이름으로 사용된다.) 이런 선행처리기는 선행처리기 매크로를 해석해서 데이터를 일반적인 {{{troff}}} 입력에 적합하도록 변환하는 일을 한다. {{{tbl}}}은 표에 관련된 선행처리기이며, {{{eqn}}}은 방정식/수학용 선행처리기, {{{pic}}}은 그림에 관련된 선행처리기이다. 각각의 자세한 설명은 메뉴얼 페이지를 참고해주기 바란다. 가능하다면, 메뉴얼 페이지는 어떠한 선행처리기도 사용하지 않도록 작성해야 한다.
{{{eqn}}} 선행처리기는 메뉴얼 페이지를 보여줄 수 있는 장치 중 99% 정도가 사용되는 타자기와 비슷한 장치(typewriter-like device, 모니터가 대표적인 장치이다.)에 대해서 정말 끔찍한 출력을 보여준다. 예를 들어, Manpage:XAllocColor.3x''''''는 지수 표기를 갖는 수식을 표현하는 사용된다. 타자기와 비슷한 장치이기 때문에 지수는 기수와 같은 줄에 표현된다. 즉, N의 제곱은 "N2"와 같이 표시된다.
{{{tbl}}}의 사용은 자제해야 한다. 모든 {{{xman}}} 프로그램들은 이를 제대로 처리하지 못한다. 예를 들어, Manpage: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}}}를 사용하도록 추천한다. 만약 표를 사용하고 싶다면 다음과 같이 쓰는 것이 좋다.
1. 표를 직접 형식화시키고, 이것이 형식화되지 않도록 {{{.nf}}} 와 {{{.fi}}} 사이에 두도록 하자. 이 방법을 사용하면 굵은 글꼴과 기울린 글꼴을 사용할 수 없지만, 이것이 표를 제대로 출력하기 위한 좋은 방법이다.
1. {{{tbl}}} 매크로를 사용하되 {{{tbl}}} 입력 대신 출력을 배포하라. {{{.TS}}} 매크로로 시작하는 줄이 있는 파일은 {{{grog}}}가 {{{tbl}}} 매크로가 필요하다라고 판단한다. 그러니, {{{.TS}}}와 {{{.TE}}}를 빼버리도록 하라. 이것들을 빼버리더라도 표는 그럭저럭 괜찮게 보인다. 하지만, 반드시 제대로 보이는지 확인해야 한다.
아직까지 {{{pic}}} 선행처리를 하는 메뉴얼 페이지를 본 적은 없다. 하지만, 메뉴얼 페이지에서 {{{pic}}} 선행처리기를 쓴다는 것은 바람직하지 않다고 생각한다. 위에서 봤듯이, {{{xman}}}은 {{{pic}}} 선행처리기를 사용하지 않고 {{{groff}}}도 입력을 제대로 처리하지 못한다.
== 배포해야 할 것은 메뉴얼 페이지 소스인가? 아니면 형식화된 문서인가? ==
몇몇 가능성에 대해 장점과 단점을 정리해보도록 하자.
1. 소스만 배포하는 경우:
* 장점: 배포하는 패키지의 크기가 작다.
* 단점: {{{groff}}}가 없는 시스템에서는 사용할 수 없다.
1. 압축되지 않은 형식화된 문서만 배포하는 경우
* 장점: {{{groff}}}가 없어도 이용할 수 있다.
* 단점: {{{dvi}}} 파일이나 {{{postscript}}} 파일을 만들 수 없다.
* 단점: 압축된 페이지를 취급하는 시스템에서는 디스크 공간이 낭비된다.
1. 압축된 형식화된 문서만 배포하는 경우
* 장점: {{{groff}}}가 없어도 이용할 수 있다.
* 단점: {{{dvi}}} 파일이나 {{{postscript}}} 파일을 만들 수 없다.
* 단점: 어떤 압축 형식을 사용할 것인가? {{{.Z}}}? {{{.z}}}? {{{.gz}}}? 아니면 모두 다?
1. 소스와 압축되지 않은 형식화된 문서를 배포하는 경우
* 장점: {{{groff}}}가 없어도 이용할 수 있다.
* 단점: 배포 패키지의 크기가 커진다.
* 단점: 몇몇 시스템에서는 형식화된 메뉴얼 페이지가 압축되어 있는 것을 전제로 한다.
* 단점: {{{groff}}}를 위해 준비되는 여분의 정보가 필요하다.
내 생각에는 소스만을 배포하는 것이 제일 좋은 방법이다. {{{groff}}}가 없는 시스템에서 이용할 수 없다는 것은 중요하지 않다. 리눅스 문서 프로젝트에 있는 500 페이지 이상의 메뉴얼 페이지는 소스만 있을 뿐이다. !XFree86의 메뉴얼 페이지도 소스만 배포한다. FSF의 메뉴얼 페이지 역시 소스만 배포하고 있다. 실제로 형식화된 메뉴얼 페이지를 배포하는 소프트웨어를 본 적이 없다. 시스템 관리자가 메뉴얼 페이지를 이용할 수 있도록 해놨다면, {{{groff}}}도 이미 설치되어 있을 것이다.
== 글꼴 규정이 무엇인가? ==
우선 {{{\fB}}}, {{{\fP}}}와 같은 직접적인 글꼴 연산자를 사용하지 않도록 하라. 인자를 지정하는 매크로는 사용하는 것이 좋다. 이 방법을 사용하면 글꼴 변경 범위의 끝에서 글꼴 변경을 잊어, 다음 글꼴 변경이 나올 때까지 굵은 글꼴이나 기울린 글꼴이 연장되는 사소한 실수를 피할 수 있다. 믿지 않겠지만, 이런 실수는 자주 일어난다.
{{{tmac.an}}} 매크로에서는 다음과 같은 글꼴을 사용할 수 있다.
* '''{{{.B}}}''' -- 굵은 글꼴
* '''{{{.BI}}}''' -- 굵은 글꼴과 기울린 글꼴의 교차
* '''{{{.BR}}}''' -- 굵은 글꼴과 로만 글꼴의 교차
* '''{{{.I}}}''' -- 기울린 글꼴
* '''{{{.IB}}}''' -- 기울린 글꼴과 굵은 글꼴 교차
* '''{{{.IR}}}''' -- 기울린 글꼴과 로만 글꼴의 교차
* '''{{{.RB}}}''' -- 로만 글꼴과 굵은 글꼴의 교차
* '''{{{.RI}}}''' -- 로만 글꼴과 기울린 글꼴의 교차
* '''{{{.SM}}}''' -- 작은 글꼴 (일반 글꼴의 9/10 크기)
* '''{{{.SB}}}''' -- 작은 글꼴의 굵은체 (작은 글꼴과 굵은 글꼴이 교차되는 것과는 다르다.)
"{{{X}}}와 {{{Y}}}의 교차"라는 것은 홀수번째 인자의 글꼴이 {{{X}}}가 되고, 짝수번째 인자의 글꼴이 {{{Y}}}가 되는 것이다.
예를 들어,
{{{
.BI "인자 1은 굵은 글꼴, " "인자 2는 기울린 글꼴, " "다음은 굵은 글꼴, " "그리고 기울린 글꼴"
}}}
여기에서 인자가 공백을 포함하는 경우에는 쌍따옴표로 묶어줘야 한다. 쌍따옴표를 적지 않으면, 각 단어는 하나의 인자로 인식된다.
이러한 글꼴 교차는 글꼴이 다르게 적용되는 단어 사이에 공백 문자가 들어가지 않게 만들기 위해 사용된다.
(특히 한글 메뉴얼 페이지의 경우는 조사를 명사와 붙여서 보이게 하기 위해 아주 적절히 사용할 수 있다.)
아래는 다른 글꼴들을 어떻게 사용할 것인지를 보여준다. (이것은 Manpage: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)
}}}
== 메뉴얼 페이지 다듬기 ==
아래는 문서의 신뢰성, 가독성, 볼품을 개선하기 위한 지침이다.
* 명령이 제대로 동작하는지 테스트해본다. 메뉴얼 페이지에 있는데로 정확히 명령어를 복사해서 쉘에 붙여넣기 하여 실행한 다음 그 실행 결과를 메뉴얼 페이지에 복사하도록 한다. 프로그램이 이런 식으로 출력할 것이라고 예상해서 적지 않도록 주의해야 한다.
* 교정하고, {{{ispell}}}을 통해 철자 검사를 하고, 다른 누군가에게 한번 읽어달라고 부탁하라. 특히 영어를 모국어로 하지 않는다면 반드시 필요한 과정이다. 지금 당신이 읽고 있는 이 HOWTO도 이런 과정을 거친 것이다. (특히 많은 도움을 준 Michael Miller에게 감사한다. 이 HOWTO에 남아있는 다른 애매한 점은 모두 내 잘못이다.) 다른 지원자도 언제나 환영한다.
* 메뉴얼 페이지를 직접 테스트하라. 메뉴얼 페이지를 형식화할 때 {{{groff}}}에서 오류가 발생하지는 않았는지 확인하는 것이 좋다. 주석으로 {{{groff}}}의 명령을 적어넣는 것도 좋은 방법이다. 메뉴얼 페이지를 {{{man}}}을 통해 불렀을 때 Manpage:man''''''이 오류를 내지는 않았는지, {{{man}}}을 통해 봤을 때 출력된 결과가 예상한 것과 일치하는지, {{{xman(1x)}}}과 {{{tkman(1tk)}}}이 메뉴얼 페이지를 제대로 처리하는지 등을 확인하라. !XFree86 3.1에서는 xman 3.1.6 - !X11R6을 사용하고, 이것은 다음 명령을 통해 압축 해제를 시도한다.
{{{
gzip -c -d < %s > %s zcat < %s > %s
}}}
* Manpage:makewhatis.8''''''이 "이름" 섹션으로부터 한 줄짜리 설명을 제대로 뽑아내는지 확인하라.
* 메뉴얼 페이지를 http://polyglotman.sourceforge.net 을 통해 HTML 형식으로 변환해보고, 그 결과를 웹 브라우저에서 확인해보기 바란다. 만들어진 HTML 페이지에 상호 참조한 내용들이 링크로 제대로 연결되어 있는지 확인하라. 만약 당신의 소프트웨어 패키지가 웹 사이트를 가지고 있다면, 메뉴얼 페이지를 거기에 올리고 꾸준히 갱신하도록 노력해야 한다.
* 메뉴얼 페이지를 책이나 다른 큰 문서에 넣을 것이라면, {{{rman}}} 프로그램을 사용해서 메뉴얼 페이지를 !LaTeX, RTF, SGML, 그리고 다른 형태로 바꿔보고, 제대로 변환됐는지 확인해보기 바란다.
* {{{man2html}}}을 이용해서 메뉴얼 페이지를 HTML로 변환시켜고 확인해보기 바란다. {{{man2html}}}은 {{{rman}}}보다는 덜 의욕적인 변환기이기는 하지만 {{{man-1.4}}} 이후부터 Linux {{{man}}} 패키지에 포함되어 있으니, 거의 대부분의 리눅스 사용자는 이미 가지고 있을 것이다. 그러니 {{{man2html}}}이 메뉴얼 페이지를 제대로 처리하는지 확인해보는 것은 가치 있는 일이다.
== 메뉴얼 페이지에서 ^H, ^_ 등이 없는 일반 텍스트 파일를 어떻게 만드는가? ==
우선 Manpage:col.1''''''을 보도록 하자. {{{col}}}은 백스페이스 시퀀스를 없앨 수 있다. 도저히 다음 글을 읽을 때까지 기다릴 수 없다면, 일단 아래와 같은 명령을 실행해보기 바란다.
{{{
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
}}}
== 고품질의 !PostScript 메뉴얼 페이지 만들기 ==
아래 명령을 사용해서 {{{ps}}} 파일을 만든 다음, !PostScript 프린터나 뷰어를 통해 출력하거나 볼 수 있다.
사용된 옵션에 대한 자세한 설명은 [#s-10 10절]을 참고하기 바란다.
{{{
funnyprompt$ groff -t -e -mandoc -Tps manpage.1 > manpage.ps
}}}
== "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}}} 데이터베이스 파일은 Manpage:makewhatos.8''''''에 의해 작성된다. 여러 버전이 있기 때문에 어떤 옵션이 사용 가능한지 메뉴얼 페이지에 언급해두는 것이 좋다. {{{makewhatis}}} 프로그램이 "이름" 섹션을 제대로 뽑아내기 위해서는 메뉴얼의 저자가 [#s-3 3절]에서 설명한데로 정확한 형식을 지키는 것이 중요하다.
{{{apropos}}}와 {{{whatis}}}의 차이는 검색하는 부분이 다르다는 것뿐이다.
{{{aprospos}}}는 "{{{man -k}}}"와 같은 의미이며 데이터베이스의 줄 전체에 대한 검색을 하는 것이고,
{{{whatis}}}는 "{{{man -f}}}"와 같은 의미로 데이터베이스에서 각 줄의 데쉬 이전, 즉 명령 이름에 대해서만 일치하는 것을 찾는다. 따라서, "{{{whatis cc}}}"을 실행하면 {{{cc}}}에 대한 정보는 출력하지만, {{{gcc}}}에 대한 정보는 출력하지 않는다.
'''잘못된 점의 수정이나 제안은 언제나 환영한다!'''
== 저작권 ==
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.
}}}
== 감사의 글 ==
* Michael Miller for proofreading the whole HOWTO (in February 2001); Gordon Torrie for many helpful grammar remarks (in August 2001). Any remaining grammar or style bogons are entirely my fault.
* S.u.S.E. (.de) (or .com) who are the only distributor to keep sending me a free copy of their latest product, acknowledging my work as a howto author.
* George B. Moody for additional suggestions on how to polish a man page.
If your name is missing here, drop me a note.
== 수정 내역 ==
* March 6 2001: HTML source now passes weblint -pedantic. Paragraph 6: Added workarounds for tbl screw-ups. Added Acknowledgements and Changelog. Added RCS Id.
* August 9 2001: Howto put under a two clause BSD license.
* August 20 2001: Improved grammar. Use a numbered list for the TOC.
* October 28 2001: Added refs to mdoc(7), mdoc.samples(7) and groff_man(7).
* April 28 2002: Fix a grammar bogon by s/particular/particularly/.
* April 30 2002: Update the link to the groff_mdoc BSD tutorial.
* November 29 2002: More suggestions for polishing your man page.
* December 15 2002: Publish SGML derived HTML. Removed dead link to LSM.