프로페셔널한 리눅스 프로그램을 만들고 싶으신가요? 그렇다면 매뉴얼 페이지를 제공하는 것이 좋습니다. 여기, 가장 빠르고 쉬운 방법을 소개합니다.
매뉴얼 페이지 (man page)
오래된 유닉스 농담 중에 이런 말이 있습니다. “정말 필요한 명령어만 아는 사람이 진정한 고수다.” 매뉴얼 페이지는 엄청난 양의 정보를 담고 있으며, 어떤 명령어에 대해 배우고 싶을 때 가장 먼저 찾아봐야 할 곳입니다.
여러분이 만든 유틸리티나 명령어에 대한 매뉴얼 페이지를 제공하면, 그저 유용한 코드를 넘어 완벽한 리눅스 패키지로 격상될 수 있습니다. 사람들은 리눅스용으로 개발된 프로그램에 매뉴얼 페이지가 있기를 기대합니다. 리눅스를 지원한다면, 프로그램의 신뢰성을 높이기 위해 매뉴얼 페이지는 필수입니다.
과거에는 매뉴얼 페이지를 작성할 때 복잡한 서식 매크로를 사용해야 했습니다. 사용자가 `man` 명령어로 페이지를 열면, groff라는 프로그램이 파일을 읽고 매크로에 따라 형식을 갖춘 출력을 생성합니다. 그런 다음, less를 통해 사용자에게 보여집니다.
매뉴얼 페이지를 자주 작성하지 않는다면, 매크로를 직접 삽입하여 매뉴얼 페이지를 만드는 작업은 매우 번거롭습니다. 올바르게 구문 분석되고 보기 좋게 만들어야 한다는 부담 때문에, 명령어에 대한 간결하고 철저한 설명을 제공하려는 원래 목표를 잊을 수도 있습니다.
복잡한 매크로와 씨름하는 대신, 콘텐츠에 집중해야 합니다.
Pandoc의 도움
Pandoc 프로그램은 마크다운 파일을 읽고, 매뉴얼 페이지를 포함한 40여 가지의 다양한 마크업 언어 및 문서 형식으로 변환해줍니다. 덕분에 매뉴얼 페이지 작성 과정을 완전히 바꿀 수 있으며, 복잡한 문법에 고생할 필요가 없습니다.
시작하려면 다음 명령을 사용하여 Ubuntu에 Pandoc을 설치할 수 있습니다:
sudo apt-get install pandoc
Fedora에서는 다음 명령어를 사용하세요:
sudo dnf install pandoc
Manjaro에서는 다음과 같이 입력합니다:
sudo pacman -Syu pandoc
매뉴얼 페이지의 구성
매뉴얼 페이지는 표준 명명 규칙을 따르는 여러 섹션으로 구성됩니다. 매뉴얼 페이지에 필요한 섹션은 설명하는 명령어의 복잡성에 따라 달라집니다.
대부분의 매뉴얼 페이지에는 최소한 다음 섹션이 포함됩니다:
이름: 명령어 이름과 그 기능을 간략하게 설명하는 한 줄 설명.
개요: 프로그램을 실행하는 데 필요한 호출 방법에 대한 간략한 설명. 허용되는 명령줄 매개변수의 유형을 보여줍니다.
설명: 명령어 또는 기능에 대한 자세한 설명.
옵션: 명령줄 옵션 목록과 각 옵션의 기능.
예제: 일반적인 사용법에 대한 몇 가지 예시.
종료 값: 가능한 반환 코드와 그 의미.
버그: 알려진 버그 및 단점 목록. 종종 프로젝트의 이슈 트래커에 대한 링크로 대체되기도 합니다.
작성자: 명령어를 작성한 사람 또는 사람들.
저작권: 저작권 정보. 여기에는 프로그램이 배포되는 라이선스 유형도 포함됩니다.
좀 더 복잡한 매뉴얼 페이지를 살펴보면 다른 섹션도 많이 있다는 것을 알 수 있습니다. 예를 들어, `man man` 명령어를 실행해 보세요. 하지만 모든 섹션을 포함할 필요는 없습니다. 정말 필요한 것만 포함하면 됩니다. 매뉴얼 페이지는 너무 장황하게 설명하는 곳이 아닙니다.
자주 볼 수 있는 다른 섹션은 다음과 같습니다:
참고: 유용하거나 관련성이 있다고 생각되는 주제와 관련된 다른 명령어.
파일: 패키지에 포함된 파일 목록.
주의: 알아두거나 주의해야 할 기타 사항.
기록: 명령어에 대한 변경 이력.
매뉴얼의 섹션
리눅스 매뉴얼은 매뉴얼 페이지로 구성되며, 다음과 같이 번호가 매겨진 섹션으로 나뉩니다:
1: 실행 프로그램 또는 쉘 명령어.
2: 시스템 호출: 커널에서 제공하는 기능.
3: 라이브러리 호출: 프로그램 라이브러리 내의 함수.
4: 특수 파일.
5: 파일 형식 및 규칙: 예: “/etc/passwd”.
6: 게임.
7: 기타: groff와 같은 매크로 패키지 및 규칙.
8: 시스템 관리 명령어: 일반적으로 루트 사용자에게 예약되어 있습니다.
9: 커널 루틴: 일반적으로 기본적으로 설치되지 않습니다.
모든 매뉴얼 페이지는 자신이 속한 섹션을 나타내야 하며, 나중에 보겠지만 해당 섹션의 적절한 위치에도 저장해야 합니다. 명령어 및 유틸리티에 대한 매뉴얼 페이지는 섹션 1에 속합니다.
매뉴얼 페이지의 형식
groff 매크로 형식은 시각적으로 구문 분석하기가 쉽지 않습니다. 반면, 마크다운은 훨씬 쉽습니다.
아래는 groff 형식으로 작성된 매뉴얼 페이지입니다:
동일한 페이지가 아래의 마크다운 형식으로 표시됩니다:
머리말 (Preamble)
처음 세 줄은 머리말이라고 합니다. 이 세 줄은 모두 백분율 기호(%)로 시작해야 하고, 공백 없이 바로 뒤에 내용이 와야 합니다.
첫 번째 줄: 명령어 이름과 괄호 안에 매뉴얼 섹션을 공백 없이 표시합니다. 이 이름은 매뉴얼 페이지 헤더의 왼쪽과 오른쪽 섹션이 됩니다. 일반적으로 명령어 이름은 대문자로 작성하지만, 반드시 그런 것은 아닙니다. 명령어 이름과 매뉴얼 섹션 번호 뒤에 오는 내용은 바닥글의 왼쪽 섹션이 됩니다. 소프트웨어 버전 번호로 사용하면 편리합니다.
두 번째 줄: 작성자의 이름. 이 이름은 매뉴얼 페이지의 자동 생성된 “작성자” 섹션에 표시됩니다. “작성자” 섹션을 따로 추가할 필요는 없습니다. 여기에는 하나 이상의 이름을 넣을 수 있습니다.
세 번째 줄: 바닥글의 중앙 부분이 되는 날짜.
이름
섹션은 숫자 기호(#)로 시작하는 줄로 표시되며, 이는 마크다운에서 헤더를 나타냅니다. 숫자 기호(#)는 줄의 첫 번째 문자여야 하며, 뒤에 공백이 와야 합니다.
“이름” 섹션에는 명령어 이름, 공백, 하이픈(-), 공백 및 명령어가 하는 일에 대한 매우 짧은 설명이 포함된 간결한 한 줄 항목이 있습니다.
개요
개요는 명령줄이 사용할 수 있는 다양한 형식을 보여줍니다. 명령어는 검색 패턴이나 명령줄 옵션을 받을 수 있습니다. 명령어 이름 양쪽에 있는 두 개의 별표(**)는 해당 이름이 매뉴얼 페이지에서 굵게 표시됨을 의미합니다. 하나의 별표(*)
일부 텍스트 양쪽에 있으면 매뉴얼 페이지에 밑줄이 그어진 텍스트로 표시됩니다.
기본적으로 각 줄바꿈 뒤에는 빈 줄이 옵니다. 빈 줄 없이 강제로 줄바꿈하려면 줄 끝에 백슬래시()를 사용할 수 있습니다.
설명
“설명” 섹션은 명령어 또는 프로그램이 수행하는 작업을 자세히 설명합니다. 중요한 세부 사항을 간결하게 다루어야 합니다. 사용 설명서를 작성하는 것이 아님을 기억하십시오.
줄 시작 부분에 두 개의 숫자 기호(##)를 사용하면 수준 2 제목이 생성됩니다. 이를 사용해 설명을 더 작은 덩어리로 나눌 수 있습니다.
옵션
“옵션” 섹션에는 명령어와 함께 사용할 수 있는 모든 명령줄 옵션에 대한 설명이 포함됩니다. 관례에 따라 굵게 표시되므로, 앞뒤에 두 개의 별표(**)를 포함합니다. 다음 줄에는 옵션에 대한 텍스트 설명을 콜론(:)으로 시작하고 그 뒤에 공백을 붙여서 포함합니다.
설명이 충분히 짧으면 man은 명령줄 옵션과 같은 줄에 설명을 표시합니다. 너무 길면 명령줄 옵션 아래 줄에서 시작하는 들여쓰기 단락으로 표시됩니다.
예제
“예제” 섹션에는 다양한 명령줄 형식이 포함됩니다. “옵션” 섹션과 마찬가지로 설명 줄을 콜론(:)으로 시작한다는 점에 유의하십시오.
종료 값
이 섹션에서는 명령어가 호출 프로세스에 다시 보내는 반환 값을 나열합니다. 명령줄에서 호출한 경우 쉘일 수 있고, 쉘 스크립트에서 시작한 경우 스크립트일 수 있습니다. 이 섹션에서도 콜론(:)으로 설명 줄을 시작합니다.
버그
“버그” 섹션에는 사람들이 알아야 할 알려진 버그, 문제점 또는 단점이 나열되어 있습니다. 오픈 소스 프로젝트의 경우, 여기에 프로젝트의 이슈 트래커에 대한 링크를 포함하여 버그의 상태를 확인하거나 새로운 버그를 보고하는 것이 일반적입니다.
저작권
“저작권” 섹션에는 저작권 정보와 소프트웨어가 배포되는 라이선스 유형에 대한 설명이 포함됩니다.
효율적인 작업 흐름
매뉴얼 페이지는 여러분이 선호하는 편집기로 편집할 수 있습니다. 구문 강조 기능을 제공하는 대부분의 편집기는 마크다운 형식을 인식하고 텍스트에 색상을 적용하여 제목을 강조하고, 굵게 표시하거나 밑줄을 그을 수 있습니다. 이 기능은 매우 유용하지만, 실제로 렌더링된 매뉴얼 페이지를 보는 것이 더 중요합니다.
pandoc ms.1.md -s -t man | /usr/bin/man -l -
마크다운 파일이 있는 디렉토리에서 터미널 창을 엽니다. 편집기에서 파일을 열어 편집하는 동안 주기적으로 파일을 저장하세요. 저장할 때마다 터미널 창에서 다음 명령어를 실행할 수 있습니다.
이 명령어를 실행한 후, 위쪽 화살표 키를 눌러 다시 실행하고 Enter 키를 누르면 됩니다.
이 명령어는 마크다운 파일(“ms.1.md”라고 가정)에서 pandoc을 호출합니다.
`-s` (독립 실행형) 옵션은 man 형식의 일부 텍스트가 아닌 위에서 아래로 완전한 매뉴얼 페이지를 생성합니다.
`-t` (출력 유형) 옵션은 pandoc에게 man 형식으로 출력을 생성하라고 지시합니다. pandoc에게 출력을 파일로 보내라고 지시하지 않았으므로, stdout으로 보낼 것입니다.
또한, `-l` (로컬 파일) 옵션을 사용하여 해당 출력을 man으로 전달하고 있습니다. 이 옵션은 man에게 man 페이지를 찾는 데이터베이스를 검색하지 말고, 지정된 파일을 열어야 함을 알려줍니다. 파일 이름이 `-` 이면 man은 stdin에서 입력을 받습니다.
요약하자면, 편집기에서 저장하고 터미널 창에서 위 명령어를 실행하면, `Q` 키를 눌러 man을 닫을 수 있으며, 위쪽 화살표 키를 누른 다음 Enter 키를 눌러 man 페이지의 렌더링된 버전을 man에서 바로 볼 수 있다는 것입니다.
매뉴얼 페이지 만들기
pandoc ms.1.md -s -t man -o ms.1
매뉴얼 페이지 작성이 완료되면, 최종 버전을 만들고 시스템에 설치해야 합니다. 다음 명령어는 pandoc에게 “ms.1″이라는 매뉴얼 페이지를 생성하라고 지시합니다.
이 명령어는 설명하는 명령어 이름 뒤에 매뉴얼 페이지의 이름을 지정하고, 파일 확장자처럼 매뉴얼 섹션 번호를 추가하는 규칙을 따릅니다.
manpath
이 명령어는 새로운 매뉴얼 페이지 파일인 “ms.1″을 생성합니다. 그렇다면, 이 파일을 어디에 넣어야 할까요? `manpath` 명령어를 실행하면 man이 매뉴얼 페이지를 검색하는 위치를 알 수 있습니다.
결과는 다음 정보를 제공합니다:
/usr/share/man: 매뉴얼 페이지의 표준 라이브러리 위치. 이 라이브러리에 직접 페이지를 추가하지는 않습니다.
/usr/local/share/man: 이 심볼릭 링크는 “/usr/local/man”을 가리킵니다.
/usr/local/man: 여기에 새로운 매뉴얼 페이지를 배치해야 합니다.
`man1`, `man2`, `man3` 등 다른 매뉴얼 섹션은 자체 디렉토리에 포함되어 있습니다. 섹션에 대한 디렉토리가 없으면 만들어야 합니다.
sudo mkdir /usr/local/man/man1
다음과 같이 입력하여 파일을 복사합니다:
sudo cp ms.1 /usr/local/man/man1
그런 다음 “ms.1” 파일을 올바른 디렉토리에 복사합니다. 일반적으로 man 페이지는 압축되어야 하므로 gzip을 사용해 압축합니다.
sudo gzip /usr/local/man/man1/ms.1
다음 명령어를 실행합니다:
sudo mandb
man이 새 파일을 데이터베이스에 추가하도록 하려면 다음을 입력하십시오.
man ms
이제 끝났습니다! 이제 `man ms` 명령어를 입력하면 다른 매뉴얼 페이지처럼 새로운 매뉴얼 페이지를 볼 수 있습니다.
새로운 매뉴얼 페이지가 표시됩니다.
다른 매뉴얼 페이지와 마찬가지로 굵게, 밑줄, 들여쓰기된 텍스트가 적절한 위치에 표시됩니다.
설명하는 옵션 옆에 짧은 설명 줄이 있으면 같은 줄에 표시됩니다. 너무 길어서 맞지 않는 줄은 설명하는 옵션 아래에 표시됩니다.
또한 자동으로 “작성자” 섹션이 생성되었습니다. 바닥글에는 머리말에 정의된 대로 소프트웨어 버전 번호, 날짜 및 명령어 이름이 포함되어 있습니다.
원한다면, . . .
pandoc이 매뉴얼 페이지를 생성한 후, 매뉴얼 페이지 디렉토리로 이동하기 전에 직접 groff 매크로 형식으로 파일을 편집하고 gzip으로 압축할 수도 있습니다.