Egloos | Log-in
F/OSS study
F/OSS study
[groff] man 페이지 작성하기
groff: 1.20.1
man-db: 2.5.7


groff는 (tex과 비슷한) 문서 조판 프로그램이며
과거 UNIX에서 사용되는 troff/nroff를 GNU 프로젝트로 구현한 것이다.
(다른 분야는 잘 모르겠지만) groff가 가장 널리 사용되는 분야는 바로
GNU/Linux 시스템의 man 페이지를 작성하는 것이다.

여기서는 groff의 기능을 자세히 설명하는 대신
간단한 man 페이지를 작성할 수 있을 정도의 기능을 알아보고자 한다.

groff를 통해 문서를 작성하기 위한 몇 가지 기본적인 규칙은 다음과 같다.
크게 3 종류의 글꼴을 선택할 수 있는데 기본 값은 Roman이다.
  • Roman : 기본 글꼴 (R)
  • Bold: 굵은 글꼴 (B)
  • Italic: 기울인 글꼴 (I) - 터미널 종류에 따라 기울인 글꼴 대신 밑줄로 표시될 수 있다.
그냥 일반적인 문장을 적으면 기본 글꼴을 이용한 하나의 문단으로 묶이게 된다.
문단을 나누려면 해당 위치에 빈 줄을 입력해야 한다.

각 줄의 맨 앞에 '.'(마침표) 기호로 시작하는 명령이 오면 이는 매크로이다.
groff는 여러 가지 (low-level) 매크로를 제공하지만 실제로 사용하는 것은
man(an) 이라는 이름의 매크로 패키지에서 제공하는 것들이며
여기서 설명하는 것들도 man 패키지 내에서 포함된 매크로들이다.
다만 .\" 로 시작하는 줄은 주석이므로 혼동하지 않아야 할 것이다.
또한 문장 중간에서도 '\'(역슬래시) 기호를 통해 특수 문자를 입력하거나 몇몇 명령을 실행할 수 있다.

일단 이 정도로 groff에 대한 설명은 마치고 (사실은 더 이상 아는 것도 없지만.. ;;)
man 페이지에 대한 설명으로 넘어가도록 하자.

man 페이지는 크게 몇 개의 섹션으로 구성되는데
가장 기본적으로 NAME, SYNOPSIS, DESCRIPTION 등의 섹션이 있어야 하며
필요에 따라 OPTIONS, FILES, ENVIRONMENT, EXAMPLES, SEE ALSO 등의 섹션이 존재한다.
그리고 작성자를 표시하기 위해 AUTHOR 섹션도 필요할 것이다.
(사실 섹션 이름이나 구성에 딱히 어떠한 제약이 있는 것은 아니므로 자유롭게 추가해도 된다.)

섹션을 구성하려면 이를 표시하기 위해 섹션의 시작 위치에 다음과 같은 (section heading) 매크로를 이용하면 된다.

.SH 섹션 이름

만약 섹션 아래에 하위 섹션이 존재한다면 (sub-section heading) .SS 매크로를 이용할 수 있다.

각 섹션 내에서 특정한 용어나 파일, 옵션 등을 설명하는 경우가 있는데
이 때 해당하는 단어를 강조하기 위해 왼쪽에 따로 두고
이에 대한 설명을 오른쪽의 (들여쓰기된) 문단 내에 적게된다.
이 경우 다음과 같은 (term-paragraph) 매크로를 이용하게 된다.

.TP
용어
설명 문단

.TP 매크로 바로 아래 줄은 설명할 용어/파일/옵션을 적는 부분이며
그 아래에는 이에 대한 설명이 뒤따르게 된다. 설명 문단은 반드시 하나의 문단일 필요는 없으며
별도의 표시 (매크로)가 없는 한 현재 용어에 대한 설명으로 인식하고 같이 들여쓰기된다.

이와 비슷한/연관된 것으로 .IP 와 .HP 와 .PP 매크로가 있다.

.IP [기호]
문단

.HP
문단

.PP

.IP 매크로는 단순히 * 기호와 같은 것을 통해 여러 문장을 나열할 때 쓰이게 되며
인자로 앞에 들어갈 기호를 지정할 수 있다. (생략 가능)

.HP 매크로는 앞 문단과 내용 상 이어지지는 않지만 동일한 들여쓰기를 유지하고 싶을 때 사용한다.
.PP 매크로는 앞에서 적용한 들여쓰기를 원래 값으로 되돌리기 위해 사용한다.

다음으로는 글꼴을 변경하기 위한 매크로들이 있다.
가장 기본적인 것은 다음과 같은 것이다.

.B 단어

.I 단어

.B 매크로는 해당 단어를 굵은 글꼴로 표시하게 하며 .I 매크로는 기울인 글꼴로 표시하게 한다.
여기서 인자로 주어진 단어는 사실 하나일 필요는 없지만
여러 단어가 주어진 경우 모두 해당 글꼴이 적용되지만 띄어쓰기는 무시되고 하나의 단어로 연결된다.
만약 강제로 띄어쓰기를 하고 싶다면 겹따옴표로 둘러싼 공백 문자를 추가해야 할 것이다.
.B 와 .I 매크로는 기본적으로 하나의 단어 만을 다루는 것이므로
출력 결과에서 해당 매크로 앞의 문장과 뒤의 문장은 자연스럽게 하나로 연결된다.

이와 비슷한 것으로 R, B, I 글꼴을 조합한 다음과 같은 매크로들이 있다.

.RB 단어1 단어2...

.BR 단어1 단어2...

.RI 단어1 단어2...

.IR 단어1 단어2...

.BI 단어1 단어2...

.IB 단어1 단어2...

이들 매크로는 이름에 해당하는 글꼴을 각 단어 별로 번갈아가며 적용한다.
예를 들어 .RB 매크로의 경우 단어1은 일반 글꼴, 단어2는 굵은 글꼴이 적용될 것이며
만약 인자로 단어3, 단어4, 단어5 등이 더 주어졌다면 역시 차례로 일반 글꼴, 굵은 글꼴이 적용될 것이다.

이는 기본적으로 .B 매크로와 .I 매크로 만으로 (여러 줄을 통해) 표현할 수 있을테지만
.TP 매크로와 같이 반드시 한 줄로 표현해야 하는 곳에 여러 글꼴을 동시에 표현하고 싶다면
위의 매크로를 이용해야만 할 것이다.

예를 들어, 옵션을 설명하는 부분에서 짧은 옵션과 긴 옵션을 동시에 설명하고 싶은 경우
옵션 자체는 굵은 글꼴로 표시하지만 이를 구분하는 쉼표는 기본 글꼴로 표시할 때 다음과 같이 할 수 있다.

.TP
.BR -h ", " --help
Display help message and exit.

이제 기본적인 설명이 끝났으니 실제로 man 페이지를 작성해 볼 수 있다.
사실 마지막으로 설명해야 할 매크로가 하나 남아있는데 여기서 함께 설명하기로 한다.

man 페이지는 설명하고자 하는 대상의 용도에 따라 몇 개의 섹션으로 구분된다.
(단, 지금 말하는 섹션은 우리가 위에서 .SH 매크로를 다루면서 설명한 문서 내의 섹션과는 다른 것이다.)
각 섹션에는 번호가 부여되어 있는데 대부분 자신이 작성한 프로그램에 대한 man 페이지를 작성하는 경우일테니
이 경우에는 1번에 해당하게 된다. (자세한 정보는 man 프로그램의 man 페이지를 참조하자!)

작성된 man 페이지는 아무 파일에나 저장할 수 있을테지만
관례적으로 설명하려는 대상의 이름과 같은 이름을 사용하며, 섹션 번호를 확장자로 사용한다.
만약 내가 zlib-cat이라는 프로그램을 만들었다면 zlib-cat.1이라는 이름으로 man 페이지를 저장한다.

man 페이지의 시작 부분에는 문서의 제목을 지정하기 위해 .TH 매크로 (title heading?)를 사용한다.

.TH 제목 섹션번호 [날짜 [버전]]

제목과 섹션번호는 '제목(섹션번호)'와 같은 형태로 man 페이지의 제일 위 모서리 양쪽과
제일 아랫줄의 오른쪽에 표시된다. 만약 날짜를 입력했다면 제일 아랫줄의 가운데에 표시된다.
만약 버전을 입력했다면 제일 아랫줄의 왼쪽에 표시된다. 물론 날짜와 버전은 생략 가능하며
꼭 날짜 혹은 버전을 적어야하는 것도 아니지만 일반적으로 그러한 용도로 사용된다.

이제 다음과 같은 파일을 작성하여 zlib-cat.1이라는 이름으로 저장하자.

.\"
.\" This is a man page for zlib-cat(1)
.\"     written by Namhyung Kim
.\"
.TH zlib-cat 1 2011-06-22 v0.1

.SH NAME
zlib-cat - show contents of a zlib'ed file

.SH SYNOPSIS
.B zlib-cat
[
.BR -h " | " --help " |"
.BR -v " | " --version " |"
.I file
]

.SH DESCRIPTION
.B zlib-cat
decompresses given
.I file
which is compressed by zlib's
.B DEFLATE
algorithm and writes its content to
.IR stdout .

.SH OPTIONS
.TP
.BR -h ", " --help
Display help message and exit.

.TP
.BR -v ", " --version
Display version number and exit.
.PP

.SH AUTHOR
Namhyung Kim
.RI < namhyung@gmail.com >.

.SH SEE ALSO
.BR zcat (1)

man 페이지를 표시하기 위해서는 man 프로그램이 알 수 있는 위치에 해당 파일이 저장되어 있어야 한다.
이는 /usr/share/man 혹은 /usr/local/share/man 디렉터리이며 그 아래에
각 섹션에 맞게 man1, man2, ... 와 같은 하위 디렉터리가 존재한다.

이 경우 /usr/local/share/man/man1 디렉터리에 해당 파일을 복사해두면 될 것이지만
일단 테스트 단계에서는 man 페이지가 잘 작성되었는지 곧바로 확인하기 위해
현재 디렉터리에 존재하는 파일을 열어보기 위해 man 프로그램의 -l 옵션을 이용할 수 있다.
다만 이 경우 확장자를 포함한 정확한 파일 이름을 전부 지정해 주어야 한다.

$ man -l zlib-cat.1

혹은 groff를 직접 호출할 수도 있는데, 실제로 위의 명령은 아래의 명령과 거의 동일하다.

$ groff -Tutf8 -man zlib-cat.1 | less

단 groff는 기본값인 80 column을 이용하여 페이지를 표시하게 되지만
man 프로그램은 ioctl을 통해 현재 터미널 크기에 맞게 페이지 길이를 적절히 조정하는 것이다.
만약 어떤 식으로는 터미널의 크기 정보를 알아냈다면 -rLL=<숫자>n 옵션을 통해 groff에게 넘겨줄 수 있다.

$ groff -Tutf8 -man -rLL=120n zlib-cat.1 | less


=== 참고 문헌 ===

by namhyung | 2011/06/22 22:20 | Application | 트랙백(1) | 덧글(2)
트랙백 주소 : http://studyfoss.egloos.com/tb/5542588
☞ 내 이글루에 이 글과 관련된 글 쓰기 (트랙백 보내기) [도움말]
Tracked from at 2014/03/11 00:42

제목 : http://helenmccrory.org/
line3...more

Commented by kkamagui at 2011/06/25 17:24
안녕하세요, 남형님 ^^
남형님께서 꼼꼼히 리뷰해주신 덕분에 드디어 "64비트 멀티코어 OS 원리와 구조"가 나오게 되었습니다.

감사합니다. ^^
그럼 행복한 주말 되시고, 언제 한번 식사라도 대접하겠습니다.
Commented by namhyung at 2011/06/27 15:23
고생하셨습니다!
좋은 책을 만드는 데 조금이나마 도움이 되셨길 바랍니다.

:         :

:

비공개 덧글

◀ 이전 페이지 다음 페이지 ▶

카테고리
General
Application
System
Kernel
Book
Tips
태그
binutils git scm perf build emacs bash linux compiler CAaQA3 computer-architecture vcs CARM elf blktrace C gcc patch memory sed documentation algorithm block-layer script SMP x86 kernel glibc synchronization awk
전체보기
이글루 파인더

최근 등록된 덧글
http://serbaserbiinfoterkini56..
by cakra at 09/22
informsi yang bagus dan b..
by cakra at 09/16
informsi yang bagus dan be..
by pordanaia at 08/05
최근 등록된 트랙백
Tod's Ferrari Homme
by Tods Pas Cher,Kodak did ..
Mocassin Femme
by Mocassins Homme, I got so..
natural garcinia cambogia
by
rss

skin by jiinny


X