매뉴얼 페이지에 왜 예제가 없습니까?


52

대부분의 매뉴얼 페이지에 몇 가지 일반적인 예가 포함되지 않은 이유가 있습니까? 일반적으로 가능한 모든 옵션을 설명하지만 초보자가 "보통"사용 방법을 이해하기가 더 어려워집니다.


1
CR을 제거하는 것과 같이 귀중한 디스크 공간을 절약하고 싶었습니다. Cf. Beckett, Watt , p.8 : " 말한 후 과다 반사 대명사를 피함으로써 많은 귀중한 공간이 절약되었습니다 ."
피터-모니카 복원 복원

3
이 문제에 대한 해결 방법 중 하나는 tldr-pages.github.io 이지만 오프라인 액세스를 위해 모든 것을 쉽게 다운로드 할 수있는 이유는 알 수 없습니다.
Nathan Long

man jq1000 줄 이상의 예제가 있습니다 (Ubuntu 16.04에서)
Motte001

답변:


49

매뉴얼 페이지에 따라 다릅니다 ... 전통적으로, 이들은 예제 포함 된 섹션을 포함했습니다. 그러나 어떤 이유로 리눅스의 매뉴얼 페이지에서 일반적으로 누락되었습니다 (그리고 저는 요즘 가장 많이 사용되는 GNU 명령을 사용한다고 가정합니다). 반면에 Solaris에서는 거의 모든 매뉴얼 페이지에 예 섹션이 포함되어 있으며 종종 몇 가지 예가 있습니다.

내가 추측한다면, FSF / GNU는 오랫동안 man페이지 사용을 권장하지 않았고 대신 사용자가 정보를 문서화하는 것을 선호합니다. info페이지는 일반적으로 man 페이지보다 더 포괄적 인 경향, 그리고 않는 예를 포함한다. info페이지는 더 많은 주제입니다. 즉 관련 명령 (예 : 파일 찾기 명령)은 종종 함께 찾을 수 있습니다.

또 다른 이유는 GNU와 그 man페이지가 서로 다른 많은 운영 체제에서 사용 되기 때문일 수 있습니다 (다른 Linux 배포판 사이에는 많은 차이점이 있습니다). 의도적으로 출판사가 특정 OS / 디스트로와 관련된 예제를 추가했을 수도 있습니다.

또한 man페이지가 "초보자를 가르치기위한"의도가 아니라고 덧붙였습니다. UNIX는 컴퓨터 전문가 (이전의 "해커")가 개발했으며 컴퓨터 전문가가 사용하도록 고안되었습니다. 따라서 매뉴얼 페이지는 초보자를 가르치기위한 것이 아니라 모호한 옵션이나 이상한 파일 형식에 대한 미리 알림이 필요한 컴퓨터 전문가를 신속하게 지원하기 위해 만들어졌으며 이는 매뉴얼 페이지의 섹션 방식에 반영됩니다.

man따라서 페이지는

  • 당신의 기억을 상쾌하게하는 빠른 참조; 명령을 호출하는 방법을 보여주고 사용 가능한 옵션을 나열합니다.
  • 명령 의 모든 측면에 대한 깊고 철저한 기술 . 동료 컴퓨터 전문가를 위해 컴퓨터 전문가가 작성했습니다.
  • 명령이 사용하는 환경 변수 및 파일 (예 : 구성 파일) 목록.
  • 다른 문서 (예 : 책) 및 기타 man페이지 (예 : 구성 파일 및 관련 / 유사한 명령의 형식.

즉, man매뉴얼 페이지 자체를 넘어가는 것보다 사용법을 더 잘 설명 할 수 있기 때문에 페이지에 예제가 있어야 한다는 것에 매우 동의 합니다. 너무 나쁜 예는 일반적으로 Linux man페이지에서 사용할 수 없습니다 ...

Solaris 매뉴얼 페이지의 예제 부분 샘플-zfs (1M) :

(...)
실시 예
     예 1 ZFS 파일 시스템 계층 만들기

     다음 명령은 pool / home이라는 파일 시스템을 만듭니다.
     pool / home / bob이라는 파일 시스템. 마운트 포인트
     / export / home은 상위 파일 시스템에 설정되어 있으며
     자식 파일 시스템에 의해 자동 상속됩니다.

       # zfs는 수영장 / 가정을 만듭니다
       # zfs set mountpoint = / export / home 풀 / 홈
       # zfs는 pool / home / bob을 만듭니다.

     예 2 ZFS 스냅 샷 생성

     다음 명령은 어제라는 스냅 샷을 만듭니다.
     이 스냅 샷은 요청시 .zfs / snapshot에 마운트됩니다.
     pool / home / bob 파일 시스템의 루트에있는 디렉토리.

       # zfs 스냅 샷 풀 / 홈 / bob @ yesterday

     예 3 여러 스냅 샷 생성 및 삭제

     다음 명령은 이름이 어제 인 스냅 샷을 만듭니다.
     풀 / 홈 및 모든 하위 파일 시스템 마다
     스냅 샷은 요청시 .zfs / snapshot 디렉토리에 마운트됩니다.
     파일 시스템의 루트에서. 두 번째 명령은 파괴
     새로 생성 된 스냅 샷

       # zfs 스냅 샷 -r pool / home @ yesterday
       # zfs destroy -r pool / home @ yesterday

SunOS 5.11 최종 변경 : 2012 년 7 월 23 일 51

시스템 관리 명령 zfs (1M)

     예 4 파일 시스템 압축 비활성화 및 활성화

     다음 명령은 압축 속성을 비활성화합니다.
(...)

이 특정 매뉴얼 페이지에는 16 (!)과 같은 예제가 있습니다.
(그리고 나는이 명령에 대한 전체 매뉴얼 페이지를 읽는 대신 대부분이 예제를 따랐다는 것을 인정합니다 ...)


2
마지막 문장 은 매뉴얼에 예제가 있는 문제 를 강조합니다 . 도구의 특정 응용 프로그램의 의미를 완전히 이해하지 않고도 자신의 요구에 가장 잘 맞는 예를들 수 있습니다. 그리고 나중에, 나는 "나는 이것을 이렇게했다"라고 말할 수 있지만, 실제로 왜 또는 그 의미가 아닙니다.
Kusalananda

6
@Kusalananda 내 방어에서, 나는 다양한 옵션에 대해 내가 실제로 한 하위 명령에 대한 읽을 필요 (아직) 그냥 모든 것을 -. 그것은 단순히 내 사용과 관련이 없습니다 ... 오용의 위험에도 불구하고 예제 목적을 제공합니다. 명령의 가장 기본적인 사용법 만 있으면 모든 종소리와 휘파람에 대한 독서가 거의 필요하지 않습니다.
Baard Kopperud

@Kusalananda 명령에 따라 달라질 수도 있습니다. 내가 아는 대부분의 유닉스 및 GNU 유틸리티는 잘 문서화되어 있지만 합리적인 작업을 수행하려면 문서가 필요 합니다. 최신 Solaris 명령 (특히 zfs)은 매우 자연스럽게 설계되었습니다. 예를 들어, zfs destroy pool/filesystem기본 사용법이며 90 %의 사용 사례에 적합합니다. -rfor 와 같은 짧은 옵션 recursive은 의도하지 않은 부작용이있을 수 있으므로 사용하기 전에 상담해야합니다.
user121391

26

나는 이것에 대한 좋은 대답이 없다고 생각합니다. 문화적인 것입니다. 일부 매뉴얼 페이지에는 사용법이 있습니다. 예 man rsync. 매뉴얼 페이지 작성자에게 작성하여 샘플 사용법을 추가하도록 요청하거나 샘플 사용법 예제를 직접 제공하여 문화를 바꾸려고 시도 할 수 있습니다. 무료 소프트웨어 제작자에게 패치, 특히 문서 패치를 제공하는 경우 간단한 요청보다 원하는 결과를 얻을 가능성이 약 10 만 배 더 높습니다.


7

그것은 달려있다 :

  • 흥미로울만한 대부분의 프로그램은 처음에 문제를 해결하고 나중에 솔루션을 개선하기 위해 일정 기간 동안 개발되었습니다. 프로그램 개발자는 자신이 알아야 할 것으로 생각한 것을 설명합니다 (그리고 문서 는 해결하려는 문제가 아닙니다).
  • 일부 프로그램의 경우 개발자 는 특정 프로그램 (또는 라이브러리)을 사용하는 방법을 보여주는 샘플 프로그램 또는 스크립트 를 제공하는 것을 선호합니다 . 다시 말하지만 이것은 문제를 해결하기 위해 수행됩니다. 프로그램을보다 쉽게 ​​테스트 할 수 있습니다.

    일부 예제는 사용자의 버그 보고서를 기반으로 하고 설명서에서 부족한 부분을 찾은 경우를 기준으로합니다. 긴 예제는 매뉴얼에 거의 제공되지 않으며 짧은 예제는 사소하고 반복적이며 실제로 프로그램 작동 방식에 대한 체계적인 설명만큼 사용자에게 많은 통찰력을 제공하지 않는 문제가 있습니다.

  • 어떤 경우 에는 개발 프로세스에 관여 하지 않은 다른 사람들이 제공 한 문서를 찾을 수 있습니다 . 즉, 문서를 검토하는 것 외에는 개발자가 참여하지 않았습니다. 이러한 노력은 무시할 수 있습니다.

5
"그런 노력은 무시해도됩니다." 이것이 무엇을 의미하는지 잘 모르겠습니다.
Faheem Mitha

이 문서는 경험을 바탕으로하지 않을 때 유용한 정보를 제공하지 않습니다.
Thomas Dickey

실제로 경험에 근거하지 않은 문서는 부정적인 기여를 할 수 있습니다.
alephzero

물론-OP가 의심 할 여지가없는 몇 가지 예가이 범주에 속하기 때문에 언급했습니다 (이 포럼에 목록을 제공하지는 않겠습니다).
Thomas Dickey

2
@ThomasDickey. 이 평가에 완전히 동의하지 않습니다. 유틸리티를 작성하는 기능에는 반드시 최종 사용자에게 API를 설명하는 기능이 반드시 필요한 것은 아닙니다. T
chiggsy

6

매뉴얼 페이지에 대한 대안을 찾고 있다면 항상 bro pages를 시도 할 수 있습니다.이 명령은 명령에 다양한 예제 만 표시하며 커뮤니티 제출 예제 목록에서 투표 할 수 있습니다. 예를 들어, 명령 bro tar은 다음을 제공합니다.여기에 이미지 설명을 입력하십시오

당사 사이트를 사용함과 동시에 당사의 쿠키 정책개인정보 보호정책을 읽고 이해하였음을 인정하는 것으로 간주합니다.
Licensed under cc by-sa 3.0 with attribution required.