man 페이지는 훌륭해요, 문제는 man 리더입니다
(whynothugo.nl)- man 페이지가 "서로 연결된 링크가 없다"거나 "터미널 창을 줄이면 텍스트가 재정렬되지 않는다"는 비판은 흔하지만, 실제로는 man 포맷 자체가 링크 기능과 재정렬 기능을 지원함
- 문제는 man 페이지를 읽는 도구(man 명령어와 less 등) 가 이 기능을 제대로 구현하지 않았다는 데 있음
man 페이지 포맷 구조
- man 문서는 주로 두 가지 포맷으로 작성됨:
- mdoc(7): 현대적, 의미 기반의 마크업 포맷
- man(7): 1979~1989년에 사용된 구식 포맷
- 예시 (mdoc 문법 일부):
.Sh NAME .Nm openrc .Nd stops and starts services for the specified runlevel .Sh SYNOPSIS -
.Sh,.Nm,.Nd는 각각 섹션 헤더, 명령 이름, 설명을 의미함 - 직접 편집하려면 mdoc 매크로 목록 참고 필요
참조(링크) 기능도 내장되어 있음
- mdoc 포맷에는 다음과 같은 링크 매크로가 포함되어 있음:
-
.Xr: 다른 man 페이지를 참조하는 교차 참조 -
.Sx: 같은 페이지 내 다른 섹션 참조 - HTML로 변환 시 실제 링크로 렌더링되며, 브라우저에서 클릭 가능
-
.Sh섹션 헤더는 앵커로 처리되어.Sx링크의 목적지가 될 수 있음 - 하지만
man명령어로 터미널에서 볼 때는 이 링크 기능이 작동하지 않음
결론: 문제는 man 포맷이 아니라 뷰어임
- 현재
man명령어는 페이지를less로 파이프하여 보여주는데, 이 방식은 링크 처리 불가 - 해결책은:
- man 포맷을 이해하고 링크를 지원하는 새로운 페이지 뷰어 필요
- 터미널 너비 변경 시 텍스트 자동 재정렬(reflow) 기능도 함께 구현하면 더 나음
배경 정보
- mdoc(7)은 1990년대 4.4BSD에서 도입된 포맷
- man(7)은 1979년~1989년 사이에 사용된 고전 포맷으로, 현재는 거의 사용되지 않음
슬랙봇 알림에서 첫줄만 보고 바로 공감해서 클릭했습니다. 저도 리더가 문제라는 지적에 100% 동의합니다.
...근데 모던 인류는 man은 고사하고 터미널도 안 쓰는 것 같더라고요. rtfm은 낭만의 시대 유물이 되었네요.
Hacker News 의견
- mdoc와 mandb 형식의 문서 작성을 오랫동안 해왔지만, 언어를 마스터하는 것은 어렵다는 의견이 있음
- mdoc와 mandb는 roff 위에 있는 매크로 세트와 같음
- 모든 man 페이지를 Markdown으로 변환하여 시스템에서 표시하는 것을 제안하고 싶다는 생각을 함
- Markdown은 더 많은 도구를 가지고 있어 비기술적인 사용자도 쉽게 문서를 작성할 수 있음
- 하지만 Markdown은 형식화가 덜 되어 있어 다양한 프로그램에서 서로 다른 방언이 존재함
- Emacs에서 info 페이지를 탐색하는 것은 유용하며, man 페이지에서도 비슷한 작업을 할 수 있음
- 기존의 man 페이지의 풍부함은 많은 사람들이 인식하지 못하는 장점임
- Markdown으로 전환하려는 사람들에 대한 아쉬움이 있음
- Markdown으로 전환하면 기존 솔루션의 링크 및 일반적인 의미론을 구현하는 데 어려움이 있을 것임
- JSON으로 데이터를 이동한 사례를 보면, 복잡한 기능을 추가하려는 시도가 있음
- Vim의 내장 ft-man-plugin을 기본 man 페이지로 사용하는 것이 문제 해결에 도움이 됨
- 링크가 작동하고, 줄 바꿈 시 들여쓰기를 유지함
- less의 기본 설정을 개선할 수 있지만, 수평 스크롤링이 필요함
- 많은 웹 버전의 man 페이지가 단조로운 글꼴로 설정되어 있어 아쉬움
- OpenBSD의 온라인 man 페이지는 훌륭함
- 터미널에서 man 페이지를 읽는 것도 좋음
- 검색 기능과 반 페이지 스크롤링을 주로 사용함
- pinfo는 GNU Info 페이지를 보기 위한 것이지만, man 페이지도 표시할 수 있음
- 페이지 간의 교차 참조를 인식하고 탐색할 수 있음
- 특정 플래그의 설명으로 이동하는 기능이 있으면 좋겠다는 의견이 있음
- 현재는 정규 표현식을 사용하여 플래그 설명을 찾음
- mandoc 프로젝트를 고려할 것을 제안함
- 페이지를 의미론적으로 처리하여 더 나은 결과를 얻을 수 있음
- Markdown이 더 나은 솔루션이라는 의견이 있음
- 웹이나 코드 편집기에서 문서를 읽는 것에 익숙해져 있어 다른 인터페이스는 불편함
- 개발자들은 Markdown에 익숙하며, 대부분의 문서도 Markdown으로 작성됨
- man 페이지는 문서 작성자와 소비자 모두에게 열등함
저는 mac에서 아래처럼 선언해두고 pman ls처럼 사용해 pdf로 보곤합니다.
pman() {
mandoc -Tpdf "$(man -w $@)" | open -f -a Preview
}