Notes on clarifying man pages

2026-02-18

man 페이지를 더 명확하게 만드는 방법에 대한 노트

안녕하세요! 작년에 Git man 페이지를 작업하는 데 시간을 보낸 뒤, 좋은 man 페이지란 무엇인지에 대해 조금 더 생각해 보게 됐어요.

저는 주요 문서가 man 페이지인 도구들(tcpdump, git, dig 등)의 치트 시트를 만드는 데 많은 시간을 써 왔어요. man 페이지에서 원하는 정보를 찾기가 종종 어렵다고 느꼈기 때문이에요.

최근에는 이런 생각을 해 봤어요. man 페이지 자체 안에 훌륭한 치트 시트가 들어갈 수는 없을까? man 페이지를 더 쓰기 쉽게 만들려면 무엇이 필요할까? 아직 고민을 시작한 지 얼마 안 됐지만 간단히 떠오른 생각들을 정리해 두고 싶었어요.

Mastodon에서 사람들에게 좋아하는 man 페이지를 물어봤고, 그 man 페이지들에서 본 흥미로운 사례들을 소개해 볼게요.

옵션 요약(OPTIONS SUMMARY)

man 페이지를 많이 읽어 보셨다면 SYNOPSIS에서 이런 걸 본 적이 있을 거예요. 거의 알파벳 전체를 나열해 놓으면 읽기가 정말 어렵거든요.

ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,]

grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz]

rsync man 페이지에는 지금까지 본 적 없는 해결책이 있더라고요. SYNOPSIS를 아주 간결하게 유지하는 방식이에요. 이렇게요.

 Local:
     rsync [OPTION...] SRC... [DEST]

그리고 나서 각 옵션을 한 줄로 요약한 “OPTIONS SUMMARY” 섹션이 이어져요. 이런 식이에요.

--verbose, -v            increase verbosity
--info=FLAGS             fine-grained informational verbosity
--debug=FLAGS            fine-grained debug verbosity
--stderr=e|a|c           change stderr output mode (default: errors)
--quiet, -q              suppress non-error messages
--no-motd                suppress daemon-mode MOTD

그 뒤에는 일반적인 OPTIONS 섹션에서 각 옵션에 대한 자세한 설명을 볼 수 있어요.

카테고리별로 정리된 OPTIONS 섹션

strace man 페이지는 옵션을 알파벳순이 아니라 카테고리별(예: “General”, “Startup”, “Tracing”, “Filtering”, “Output Format”)로 정리해 놓았어요.

실험 삼아 grep man 페이지에 카테고리별로 묶은 “OPTIONS SUMMARY” 섹션을 만들어 봤는데, 결과는 여기에서 볼 수 있어요. 결과가 마음에 드는지는 잘 모르겠지만 재미있는 시도였어요. 이 작업을 하면서 -l 같은 grep 옵션이 도무지 기억이 안 난다는 생각을 했거든요. man 페이지에서 그 옵션을 찾는 데 항상 한참이 걸리는 느낌이 들었고, 어떻게 구성하면 더 쉽게 찾을 수 있을지 고민해 봤어요. 카테고리로 나누면 어떨까 싶어서요.

치트 시트

몇 분이 Perl man 페이지 모음(perlfunc, perlre 등)을 알려 주셨는데, 그중에서 man perlcheat에 이런 치트 시트 섹션이 있는 걸 발견했어요.

 SYNTAX
 foreach (LIST) { }     for (a;b;c) { }
 while   (e) { }        until (e)   { }
 if      (e) { } elsif (e) { } else { }
 unless  (e) { } elsif (e) { } else { }
 given   (e) { when (e) {} default {} }

정말 멋지다고 생각했고, 80자 너비의 간결한 ASCII 치트 시트를 man 페이지 안에 넣는 다른 방법은 없을까 궁금해지더라고요.

예제는 언제나 인기예요

가장 흔했던 의견은 “예제가 있는 man 페이지는 다 좋다”는 거였어요. 누군가 OpenBSD man 페이지를 언급했는데, OpenBSD tail man 페이지는 제가 tail을 쓰는 딱 두 가지 방법을 예제로 마지막에 잘 보여 주거든요.

보통 EXAMPLES 섹션은 man 페이지 맨 끝에 있는 경우가 많다고 생각해요. 하지만 앞에서 본 rsync man 페이지처럼 예제로 시작하는 man 페이지도 있어요. 제가 git-add와 git rebase man 페이지를 작업할 때는 맨 앞에 짧은 예제를 넣었어요.

목차와 섹션 간 링크

이건 man 페이지 자체의 속성은 아니지만, 터미널에서 man 페이지를 볼 때 어떤 섹션이 있는지 파악하기 어렵다는 문제가 있어요.

Git man 페이지를 작업할 때, 저와 Marie는 Git 사이트에 올라온 man 페이지 HTML 버전의 사이드바에 목차를 추가했어요.

나중에는 Git man 페이지 HTML 버전에도 하이퍼링크를 더 추가해서, “INCOMPATIBLE OPTIONS” 같은 항목을 클릭하면 해당 섹션으로 바로 이동할 수 있게 하고 싶어요. Git 프로젝트에서는 man 페이지가 AsciiDoc으로 생성되기 때문에 이런 링크를 추가하는 게 아주 쉬워요.

목차를 추가하고 내부 하이퍼링크를 넣는 건, 전혀 다른 형태의 문서를 따로 유지하지 않으면서도 man 페이지 형식(적어도 HTML 버전에서는)을 개선할 수 있는 괜찮은 절충안이라고 생각해요. 물론 이렇게 하려면 Git의 AsciiDoc 시스템 같은 툴체인을 갖춰야 해요.

man 페이지에서 특정 옵션을 쉽게 찾아볼 수 있게 해 주는(“-a는 뭘 하는 옵션이지?” 같은 질문에 답해 주는) 범용 시스템이 있다면 정말 좋을 것 같아요. 제가 아는 가장 좋은 방법은 man 페이저에서 ^ *-a 같은 패턴으로 검색하는 거지만, 저는 항상 그걸 깜빡하고 결국 man 페이지 안에서 -a가 나오는 부분을 하나하나 넘겨가며 찾게 되더라고요.

모든 옵션에 예제가 있는 경우

curl man 페이지에는 모든 옵션에 예제가 있고, HTML 버전에는 목차도 있어서 원하는 옵션으로 훨씬 쉽게 이동할 수 있어요.

예를 들어 --cert 예제를 보면 --key 옵션도 함께 넘겨야 한다는 걸 바로 알 수 있어요. 이렇게요.

  curl --cert certfile --key keyfile https://example.com

구현 방식은 각 옵션마다 파일이 하나씩 있고(https://github.com/curl/curl/blob/dc08922a61efe546b318daf964514ffbf41583 25/docs/cmdline-opts/append.md) 그 파일 안에 “Example” 필드가 있는 형태예요.

표로 데이터 정리하기

꽤 많은 분이 man ascii를 가장 좋아하는 man 페이지로 꼽아 주셨는데, 이렇게 생겼어요.

 Oct   Dec   Hex   Char                     
 ───────────────────────────────────────────
 000   0     00    NUL '\0' (null character)
 001   1     01    SOH (start of heading)   
 002   2     02    STX (start of text)      
 003   3     03    ETX (end of text)        
 004   4     04    EOT (end of transmission)
 005   5     05    ENQ (enquiry)            
 006   6     06    ACK (acknowledge)        
 007   7     07    BEL '\a' (bell)          
 010   8     08    BS  '\b' (backspace)     
 011   9     09    HT  '\t' (horizontal tab)
 012   10    0A    LF  '\n' (new line)

물론 man ascii는 특이한 man 페이지지만, 이 페이지가 멋진 점은(ASCII 레퍼런스로 항상 유용하다는 점 말고도) 표 형식 덕분에 필요한 정보를 훑어보며 아주 쉽게 찾을 수 있다는 거예요. man 페이지 안에서 정보를 “표”로 보여 주면 더 읽기 쉬워지는 경우가 더 있지 않을까 궁금해지더라고요.

GNU 방식

man 페이지 이야기를 하다 보면 GNU coreutils man 페이지(예를 들면 man tail)에는 예제가 없다는 얘기가 자주 나와요. 반면 OpenBSD man 페이지는 예제가 있거든요.

이 주제는 꽤 정치적인 이야기라 깊게 들어가진 않겠지만, 제가 사실이라고 믿는 몇 가지는 이렇예요.

GNU 프로젝트는 man 페이지 대신 “info” 매뉴얼에 문서를 유지하는 걸 선호해요. 이 페이지에는 “man 페이지는 더 이상 유지보수되지 않는다”고 나와 있어요.
“info” 매뉴얼을 읽는 방법은 세 가지예요. HTML 버전, Emacs 안, 또는 독립 실행형 info 도구로 읽는 방법이죠. Emacs info 브라우저를 좋아한다는 Emacs 사용자 얘기는 들어 본 적이 있어요. 독립 실행형 info 도구를 쓰는 사람은 본 적이 없는 것 같아요.
tail에 대한 info 매뉴얼 항목은 man 페이지 맨 아래에 링크가 있고, 거기에는 예제가 있어요.
FSF는 GNU 소프트웨어 매뉴얼을 인쇄 책으로 판매하곤 했고(지금도 가끔 판매할지도 몰라요)

어느 정도 복잡도를 넘어서면 man 페이지는 탐색하기가 정말 어려워져요. 저는 coreutils info 매뉴얼을 써 본 적도 없고 앞으로도 쓸 것 같지 않지만, GNU Bash 레퍼런스 매뉴얼이나 The GNU C Library Reference Manual은 man 페이지보다는 HTML 문서로 보는 걸 훨씬 선호할 것 같아요.

man 페이지와 관련된 몇 가지 도구들

흥미롭다고 생각한 도구들을 몇 가지 소개할게요.

fish 셸에는 man 페이지에서 자동으로 탭 완성을 생성하는 Python 스크립트가 함께 들어 있어요.
tldr.sh는 커뮤니티에서 유지하는 예제 모음이에요. 예를 들어 tldr grep처럼 실행할 수 있죠. 많은 분이 유용하다고 하더라고요.
Dash라는 Mac용 문서 브라우저에는 멋진 man 페이지 뷰어가 들어 있어요. 저는 여전히 터미널 man 페이지 뷰어를 쓰지만, 목차가 포함되어 있다는 점이 마음에 들어요. 이렇게 생겼어요.

제약이 많은 형식을 고민하는 재미

man 페이지는 형식이 정말 제약이 많은데, 그런 제한적인 형식으로 무엇을 할 수 있을지 고민하는 게 재미있어요.

저는 글쓰기를 정말 좋아하면서도 문서를 잘 읽지 않는 고질적인 습관이 있어서, man 페이지에서 무엇이 정말 유용한지 스스로 판단하기가 조금 어렵더라고요. 이 글에 쓴 것들 대부분이 제 사용 경험을 개선해 줄지 잘 모르겠어요. (예제는 예외예요. 저는 예제를 정말 좋아해요)

그래서 여러분이 잘 만들었다고 생각하는 다른 man 페이지와, 그 페이지의 어떤 점이 좋은지 듣고 싶어요. 댓글은 여기에서 남겨 주세요.