나만의 manpage 만들기
manpage가 뭔데?
Your reference guide is called Google / man / the Internet / ....
manual page의 약자로, 유닉스 계열 운영체제에서 사용되는 유틸리티이다. man 명령어와 같이 사용하면 해당 명령어에 대한 메뉴얼을 볼 수 있다.
manpage는 메뉴얼의 종류별로 여러 개의 섹션으로 나누어져 있다.
섹션 번호 | 섹션 설명 |
1 | 실행 가능한 프로그램 또는 쉘 명령 |
2 | 시스템 콜 |
3 | 라이브러리 호출 (주로 Standard C Library) |
4 | 특별한 파일 (주로 /dev 에 포함된 디바이스 파일들) |
5 | 파일 포맷 및 규칙 (/etc/passed 같은 파일) |
6 | 게임 |
7 | 기타 (매크로 패키지나 규약 같은 내용을 담고 있음. 예: man(7), groff(7)) |
8 | 시스템 관리자를 위한 명령 |
man 명령의 기본 설정은 1 8 3 0 2 5 4 9 6 7 순서대로 섹션을 참조한다(운영체제별로 다름: man(1)의 DEFAULTS섹션 참고). 따라서 printf와 같이 동명의 메뉴얼이 다른 섹션에 있을 때에는 섹션 번호를 직접 입력하여 메뉴얼을 보아야 한다.
•
쉘 환경에서 출력하는 유틸리티에 대해 알고 싶으면 man printf만 실행해도 섹션 1이 가장 우선순위가 높기 때문에 man 1 printf와 같은 문서를 볼 수 있다.
•
C 표준 라이브러리의 표준 입출력 함수에 대해 알고 싶으면 man 3 printf라 입력해 섹션 3의 문서를 지정해서 보아야 한다.
각 메뉴얼들은 여러 개의 단락으로 나누어진다. 다음은 일반적인 단락들이다: NAME, SYNOPSIS, CONFIGURATION, DESCRIPTION, OPTIONS, EXIT STATUS, RETURN VALUE, ERRORS, ENVIRONMENT, FILES, VERSIONS, CONFORMING TO, NOTES, BUGS, EXAMPLE, AUTHORS, SEE ALSO.
단락별 사용 예시를 들면,
•
첫 과제인 libft를 수행하기 위해서는 libc 함수의 원형과 동작, 그리고 리턴값을 잘 이해하고 있어야 한다. 이때 manpage의 SYNOPSIS에서 프로토타입을, DESCRIPTION에서 동작을, RETURN VALUE에서 리턴값을, EXAMPLE에서 다양한 예시를 확인할 수 있다.
•
1서클 통곡의 벽 born2beroot 과제를 수행하기 위해서는 다양한 쉘 명령어들을 이해하고 있어야 한다. 이때 manpage의 OPTIONS에서 다양한 인자들과 설명을, EXAMPLE에서 사용 예시를, SEE ALSO에서 관련 있는 다른 명령들을 볼 수 있다.
manpage 만들기
.TH kyungjle 7 "2023.11.07" "10.2" "42Seoul Cadet Info"
Plain Text
복사
메뉴얼의 제목을 지정하는 메크로이다. 문서 제목은 인트라 아이디인 kyungjle, 섹션은 MISC 카테고리인 7로 지정했다.
여기까지가 필수 정보이고, 나머지는 부가적인 정보들이다. 가이드 문서에 따르면 footer-middle 자리에는 최종 수정일이, footer-inside 자리에는 버전 정보가 들어가는 것이 컨벤션이라고 하니 따라주었다. 추가적으로, 메크로는 공백을 기준으로 인자를 구분하기 때문에 문자열들을 큰따옴표로 묶어서 잘못 해석되는 것을 방지했다.
.SH "NAME"
Plain Text
복사
단락을 지정하는 메크로이다. 앞에서 언급했듯, man page에는 일반적으로 NAME, SYNOPSIS, SEE ALSO같은 단락이 존재한다. 단락 이름은 중복되어도 상관없지만, 컨벤션에 따라 겹치지 않도록 하는 것이 좋을 듯 하다.
kyungjle nicknamemohaji mohaji - \\fB Lee Kyung Jun \\fR (learner)
Plain Text
복사
.이나 '으로 시작하지 않는 문장은 일반 문장으로 취급된다. 주의할 점은 개행이 따로 없다는 것이다. 줄을 바꾸고 싶으면 새로운 단락 (.P 등의 메크로 사용 가능)을 만들어 주어야 한다.
\\fB와 같은 구문은 roff에서 사용하는 escape sequence들이다. C언어의 \\n을 생각하면 쉽다. \\fB를 이용해 일반 텍스트에서 굵은 글자로 바꾸고, \\fR 이후부터는 다시 일반 텍스트 취급한다.
kyungjle nicknamemohaji mohaji -
.B Lee Kyung Jun
learner
Plain Text
복사
위와 같이 .B 메크로를 이용하여 서식을 지정할 수도 있다. 취향 차이인 듯 하다. 개인적으로는 escape sequence를 사용하는 쪽이 읽기 편하다.
줄 전체를 굵은 글자로 쓰고 싶다면 메크로 뒤에 아무 인자를 넣지 않는 방법을 이용할 수 있다. 메뉴얼에서는 이를 input trap이라고 소개한다.
I love to
.B
eat, sleep
, and watch a football match
Plain Text
복사
.SY IG
@nicknamemohaji00
.YS
Plain Text
복사
사용 예시를 나타낼 때 주로 사용하는 구문이다. .SY 뒤에 명령어가, SY와 YS 사이의 내용에 설명이 들어간다.
.UR <https://nicknamemohaji.tistory.com>
.UE
Plain Text
복사
URL을 추가할 때 넣는 구문이다. 하이퍼링크가 걸려서, 마우스 사용이 가능한 환경에서는 넘어갈 수 있는 링크가 삽입된다.
.UE 뒤에는 trailing 문자열을 넣을 수 있다. 근데 대치가 아니고 trailing이라 예쁘게 나오지 않아서 패스.
최종적으로, 다음과 같은 자기소개 페이지를 만들었다.
.TH kyungjle 7 "2023.11.07" "10.2" "42Seoul Cadet Info"
.SH "NAME"
kyungjle nicknamemohaji mohaji - \\fB Lee Kyung Jun \\fR
.SH "DESCRIPTION"
kyungjle is 42Seoul cadet joined on Oct, 2023.
.SH "Contact"
.SY IG
@nicknamemohaji00
.YS
.SY BLOG
.UR <https://nicknamemohaji.tistory.com>
.UE
.YS
.SH "Hobbies"
.TP
I love to
.B
eat, sleep
, and watch a football match
.TP
I am interested in
.I
Cybersecurity
Plain Text
복사
이렇게 만든 manpage는 man -l kyungjle로 읽을 수 있다.
man-db 를 업데이트해서 시스템 어디에서나 이 manpage를 볼 수 있게 하는 방법은 80006년쯤 후에 업데이트...
마치며
manpage 작성법에 대해 알아보았습니다. 개발자스럽게 자기소개.. 가 아니라 프로그램 개발 후 manpage를 작성해 사용자들에게 상세한 가이드를 제공하는 것은 어떨까요?
