# man 페이지는 훌륭해요, 문제는 man 리더입니다

> Clean Markdown view of GeekNews topic #20258. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=20258](https://news.hada.io/topic?id=20258)
- GeekNews Markdown: [https://news.hada.io/topic/20258.md](https://news.hada.io/topic/20258.md)
- Type: GN+
- Author: [xguru](https://news.hada.io/@xguru)
- Published: 2025-04-11T09:45:14+09:00
- Updated: 2025-04-11T09:45:14+09:00
- Original source: [whynothugo.nl](https://whynothugo.nl/journal/2025/04/09/man-pages-are-great-man-readers-are-the-problem/)
- Points: 12
- Comments: 6

## Summary

**man 페이지**는 링크 기능과 텍스트 재정렬 기능을 지원하지만, **man 페이지를 읽는 도구**가 이를 제대로 구현하지 못하고 있습니다. **mdoc 포맷**은 현대적이며 의미 기반의 마크업을 사용하고, **man 포맷**은 구식 포맷입니다. mdoc 포맷에는 **링크 매크로**가 포함되어 있어 HTML로 변환 시 실제 링크로 작동하지만, 터미널에서는 작동하지 않습니다. 문제를 해결하려면 **링크를 지원하는 새로운 페이지 뷰어**가 필요합니다.

## Topic Body

- 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년 사이에 사용된 고전 포맷으로, 현재는 거의 사용되지 않음

## Comments



### Comment 37042

- Author: scari
- Created: 2025-04-11T14:24:15+09:00
- Points: 1

슬랙봇 알림에서 첫줄만 보고 바로 공감해서 클릭했습니다. 저도 리더가 문제라는 지적에 100% 동의합니다.  
  
...근데 모던 인류는 man은 고사하고 터미널도 안 쓰는 것 같더라고요. rtfm은 낭만의 시대 유물이 되었네요.

### Comment 37037

- Author: winterjung
- Created: 2025-04-11T12:17:12+09:00
- Points: 3

저는 mac에서 아래처럼 선언해두고 `pman ls`처럼 사용해 pdf로 보곤합니다.  
```  
pman() {  
  mandoc -Tpdf "$(man -w $@)" | open -f -a Preview  
}  
```

### Comment 37190

- Author: pcj9024
- Created: 2025-04-15T12:07:01+09:00
- Points: 1
- Parent comment: 37037
- Depth: 1

대박꿀팁... 감사합니다

### Comment 37045

- Author: pkj3186
- Created: 2025-04-11T14:31:26+09:00
- Points: 1
- Parent comment: 37037
- Depth: 1

대박 감사합니다

### Comment 37033

- Author: bbulbum
- Created: 2025-04-11T11:26:43+09:00
- Points: 1

와 이거 너무 공감해요. man 을 잘 읽으면 정말 좋은데 잘 읽기가 너무 어려워요..

### Comment 37018

- Author: neo
- Created: 2025-04-11T09:45:14+09:00
- Points: 1

###### [Hacker News 의견](https://news.ycombinator.com/item?id=43631672) 
- 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 페이지는 문서 작성자와 소비자 모두에게 열등함