안녕하세요! 지난달 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 쪽에서는 무슨 일이 일어나고 있는지 궁금해지더라고요.

댓글은 여기에서 보실 수 있어요.