안녕하세요! 지난달 man 페이지에 대한 단상에서 얻은 가장 큰 교훈은 man 페이지의 예제가 정말 훌륭하다는 것이었기에, 제가 가장 좋아하는 두 도구의 man 페이지에 예제를 추가(하거나 개선)하는 작업을 했습니다.

결과물은 다음과 같습니다:

• dig man 페이지 (이제 예제 포함)
• tcpdump man 페이지 예제 (기존 예제를 업데이트한 것입니다)

목표: 가장 기본적인 예제 담기

여기서의 목표는 정말 가장 기초적인 도구 사용 예제를 제공하는 것이었습니다. tcpdump나 dig를 자주 쓰지 않거나(혹은 한 번도 써본 적 없는!) 그래서 사용법을 잘 기억하지 못하는 사람들을 위한 예제죠.

지금까지 “초보자와 이 도구를 가끔 쓰는 사람들을 위한 예제 섹션을 쓰고 싶다”고 말하는 방식이 아주 잘 통했습니다. 설명하기도 쉽고, 사용자들에게 man 페이지에 바라는 점으로 들은 이야기들을 생각하면 타당하다고 느껴지며, 메인테이너들도 설득력 있게 받아들이는 것 같습니다.

Denis Ovsienko, Guy Harris, Ondřej Surý를 비롯해 문서 변경 사항을 검토해 주신 모든 분께 감사드립니다. 좋은 경험이었고, 덕분에 man 페이지 작업을 조금 더 해보고 싶다는 동기가 생겼습니다.

왜 man 페이지를 개선할까?

지금 도구의 공식 문서를 작업하는 데 관심이 생긴 이유는 다음과 같습니다:

• Man 페이지는 실제로 거의 100% 정확한 정보를 담을 수 있습니다! 정보가 실제로 맞는지 확인하는 검토 과정을 거치는 것 자체가 큰 가치가 있습니다.
• “가장 자주 쓰이는 tcpdump 플래그는 무엇인가” 같은 기본적인 질문조차도, 메인테이너는 종종 제가 모르는 유용한 기능을 알고 있습니다! 예를 들어 이번 tcpdump 예제 작업을 하면서, tcpdump -w out.pcap으로 패킷을 파일에 저장할 때 -v를 함께 넘기면 지금까지 캡처된 패킷 수에 대한 실시간 요약을 출력할 수 있다는 것을 알게 되었습니다. 정말 유용하고, 저는 전혀 몰랐던 내용이며, 혼자서는 아마 절대 알아차리지 못했을 것 같습니다.

솔직히 저는 늘 문서가 읽기 어려울 거라고 지레 짐작하고, 보통은 문서를 건너뛰고 블로그 글이나 Stack Overflow 댓글을 읽거나 친구에게 물어보는 편이라 지금 제 상황이 좀 낯설게 느껴집니다. 하지만 지금은 낙관적인 기분이 듭니다. 문서가 꼭 형편없을 필요는 없지 않을까? 정말 훌륭한 블로그 글을 읽는 것만큼 좋으면서, 거기에 더해 실제로 정확하다는 장점까지 가질 수도 있지 않을까 하는 생각이 듭니다. 최근에 Django 문서를 쓰고 있는데, 정말 좋습니다! 앞으로 어떻게 될지 지켜봐야겠죠.

man 페이지 언어 직접 작성을 피하는 법

tcpdump 프로젝트 도구의 man 페이지는 roff 언어로 작성되어 있는데, 사용하기가 좀 어렵고 솔직히 배우고 싶지 않았습니다.

그래서 저는 Markdown을 roff로 변환하는 아주 간단한 markdown-to-roff 스크립트를 작성해 해결했고, 기존 man 페이지가 이미 사용하고 있던 것과 비슷한 관례를 따랐습니다. pandoc을 그냥 썼을 수도 있지만, pandoc이 만들어내는 결과물이 꽤 달라 보여서 차라리 제 스크립트를 직접 작성하는 게 낫겠다고 생각했습니다. 뭐, 알 수 없죠.

기존 Markdown 라이브러리가 Markdown AST를 파싱하는 기능을 활용해, 이 맥락에서 말이 되는 방식으로 포맷팅하기 위해 코드 생성 메서드를 직접 구현할 수 있다는 점은 꽤 멋지다고 생각했습니다.

man 페이지는 복잡하다

BSD 시스템(그리고 일부 Linux 시스템, 그리고 아마 Mac OS)이 man 페이지 포맷팅에 사용하는 mandoc 프로젝트에 대해 알게 된 것을 계기로, roff의 역사와 70년대 이후 어떻게 발전해 왔는지, 그리고 오늘날 누가 이를 작업하고 있는지에 대해 깊이 파고들었습니다. 오늘은 이에 대해 더는 이야기하지 않겠지만, 다음 기회에 다뤄보겠습니다.

전반적으로 BSD와 Linux에서 문서화가 작동하는 방식에는 제가 아직 제대로 이해하지 못한 기술적·문화적 간극이 있는 것 같습니다. 하지만 BSD 쪽에서는 어떤 일이 일어나고 있는지 계속 궁금해하고 있습니다.

댓글은 여기에서 볼 수 있습니다.