Notes on clarifying man pages

2026-02-18

man 페이지를 더 명확하게 만드는 노트

원문은 Julia Evans님이 2026-02-18에 게재했습니다. 이 블로그 구독하기

안녕하세요! 작년에 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 {} }

정말 멋지다고 생각했고, man 페이지에 쓸 수 있는 80자 너비의 간결한 ASCII 치트 시트를 작성하는 다른 방법은 없을지 궁금해졌습니다.

예제는 언제나 인기 있다

가장 흔한 의견은 “예제가 있는 man 페이지는 다 좋다”는 취지의 말이었다. 누군가 OpenBSD man 페이지를 언급했는데, OpenBSD tail man 페이지는 마지막 부분에 제가 tail을 사용하는 정확히 두 가지 방법에 대한 예제가 있습니다.

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

목차와 섹션 간 링크

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

Git man 페이지를 작업할 때 Marie와 제가 한 일 중 하나는 Git 사이트에 호스팅된 man 페이지의 HTML 버전에 사이드바 목차를 추가한 것이었습니다.

언젠가는 Git man 페이지의 HTML 버전에 하이퍼링크도 더 추가해서, “INCOMPATIBLE OPTIONS” 같은 문구를 클릭하면 해당 섹션으로 이동할 수 있게 하고 싶습니다. Git man 페이지는 AsciiDoc으로 생성되기 때문에 Git 프로젝트에서는 이런 링크를 추가하는 것이 매우 쉽습니다.

목차를 추가하고 내부 하이퍼링크를 넣는 것은 완전히 다른 형태의 문서를 유지하지 않으면서도 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 페이지와 달리 예제가 없다는 이야기가 자주 나옵니다. OpenBSD man 페이지는 예제가 있습니다.

이건 꽤 정치적인 주제처럼 보이고 여기서 제가 제대로 다루기도 어려울 것 같아 깊게 들어가지는 않겠지만, 제가 사실이라고 믿는 몇 가지는 이렇습니다.

GNU 프로젝트는 man 페이지 대신 “info” 매뉴얼로 문서를 유지하는 것을 선호합니다. 이 페이지에는 “the man pages are no longer being maintained”이라고 적혀 있습니다.
“info” 매뉴얼을 읽는 방법은 세 가지가 있습니다. HTML 버전, Emacs 안, 또는 독립 실행형 info 도구입니다. Emacs 사용자 중에는 Emacs info 브라우저를 좋아한다는 사람들을 본 적이 있습니다. 독립 실행형 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 페이지와 그 이유가 무엇인지 듣고 싶습니다. 댓글은 여기에서 남길 수 있습니다.