명령 행 / 쉘 도움말 텍스트에 "표준"형식이 있습니까?

그렇지 않은 경우 사실상의 표준이 있습니까? 기본적으로 나는 다음과 같은 명령 줄 도움말 텍스트를 작성하고 있습니다.

usage: app_name [options] required_input required_input2
  options:
    -a, --argument     Does something
    -b required     Does something with "required"
    -c, --command required     Something else
    -d [optlistitem1 optlistitem 2 ... ]     Something with list

기본적으로 다양한 도구의 도움말 텍스트를 읽음으로써 지침을 만들었지 만 지침 또는 기타 목록이 있습니까? 예를 들어 대괄호 나 괄호를 사용합니까? 간격을 사용하는 방법? 인수가 목록 인 경우 어떻게합니까? 감사!

일반적으로 도움말 출력에는 다음이 포함되어야합니다.

• 앱의 기능 설명
• 사용 구문 :
  • [options]옵션의 위치를 ​​나타내는 데 사용
  • arg_name 필요한 단수 인수
  • [arg_name] 선택적, 단일 arg
  • arg_name... 필요한 인수가 많은 경우 (이것은 드)니다)
  • [arg_name...] 임의의 숫자를 제공 할 수있는 인수
  • 참고 arg_name낮은, 뱀 경우에 설명해야한다, 짧은 이름,
• 멋지게 형식화 된 옵션 목록은 다음과 같습니다.
  • 간단한 설명이
  • 기본값이있는 경우 표시
  • 가능한 경우 가능한 값 표시
  • 옵션이 짧은 형식 (예 :) -l또는 긴 형식 (예 --list:)을 사용할 수있는 경우 설명이 동일하므로 동일한 행에 함께 포함하십시오.
• 명령 줄 인수의 소스가 될 수있는 구성 파일 또는 환경 변수의 위치에 대한 간략한 표시기 GREP_OPTS
• 매뉴얼 페이지가있는 경우 이와 같이 표시하십시오. 그렇지 않으면 자세한 도움말을 찾을 수있는 위치에 대한 간략한 표시기

그것의 좋은 양식이 모두를 받아 들일 것을 더주의 -h하고 --help이 메시지를 트리거 하고 이 메시지를 표시해야하는 경우 명령 줄 구문, 예를 생략 필요한 인수까지 사용자 놨.

docopt 를 보십시오 . 명령 행 인수를 문서화하고 자동으로 구문 분석하기위한 공식 표준입니다.

예를 들어 ...

Usage:
  my_program command --option <argument>
  my_program [<optional-argument>]
  my_program --another-option=<with-argument>
  my_program (--either-that-option | <or-this-argument>)
  my_program <repeating-argument> <repeating-argument>...

커맨드 라인 사용법에 대한 표준 구문은 없지만 대부분이 규칙을 사용합니다.

Microsoft 명령 줄 구문 , IBM은 비슷한 명령 줄 구문

• Text without brackets or braces

  표시된대로 입력해야하는 항목
  
  

• <Text inside angle brackets>

  값을 제공해야하는 자리 표시 자
  
  

• [Text inside square brackets]

  선택 품목
  
  

• {Text inside braces}

  필수 아이템 세트; 하나를 선택하십시오
  
  

• 세로 막대 {a|b}

  상호 배타적 인 품목을위한 분리기; 하나를 선택하십시오
  
  

• 생략 <file> …

  반복 할 수있는 항목
  
  

대부분 POSIX 호환 OS 인 Linux를 실행하고 있습니다. POSIX 표준은 다음과 같아야합니다. Utility Argument Syntax .

• 옵션은 이 같은 하나의 영숫자 문자 뒤에 하이픈이다 -o.
• 옵션에는 인수가 필요할 수 있습니다 (옵션 바로 뒤에 표시되어야 함). 예를 들어 -o argument또는 -oargument.
• 하이픈 뒤에 인수가 필요없는 옵션을 그룹화 할 수 있으므로 예를 들어와 -lst같습니다 -t -l -s.
• 옵션은 어떤 순서로나 나타날 수 있습니다. 따라서 -lst와 같습니다 -tls.
• 옵션이 여러 번 나타날 수 있습니다.
• 옵션은 다른 비 옵션 인수보다 우선합니다. -lst nonoption.
• 그만큼 --인수는 옵션을 종료합니다.
• 이 -옵션은 일반적으로 표준 입력 스트림 중 하나를 나타내는 데 사용됩니다.

Microsoft에는 자체 명령 줄 표준 사양이 있습니다 .

이 문서는 명령 줄 유틸리티 개발자를 대상으로합니다. 우리의 목표는 일관되고 구성 가능한 명령 행 사용자 경험을 제시하는 것입니다. 이를 통해 사용자는 핵심 개념 세트 (구문, 이름 지정, 동작 등)를 학습 한 다음 해당 지식을 큰 명령 세트로 작업하도록 변환 할 수 있습니다. 이러한 명령은 표준화 된 데이터 스트림을 표준화 된 형식으로 출력하여 출력 텍스트 스트림을 구문 분석 할 필요없이 쉽게 구성 할 수 있어야합니다. 이 문서는 쉘, 유틸리티 세트 또는 명령 작성 기술의 특정 구현과 무관하게 작성되었습니다. 그러나 부록 J-Windows Powershell을 사용한 Microsoft Command Line Standard 구현은 Windows PowerShell을 사용하여 이러한 많은 지침을 무료로 구현하는 방법을 보여줍니다.

GNU 코딩 표준은 이와 같은 것들에 대한 좋은 참고 자료입니다. 이 섹션 에서는의 출력을 다룹니다 --help. 이 경우 매우 구체적이지 않습니다. 짧고 긴 옵션과 간결한 설명을 보여주는 표를 인쇄하면 잘못 될 수 있습니다. 가독성을 위해 모든 인수 사이에 간격을 두십시오. 도구에 대한 자세한 설명을 제공 할 수있는 man페이지 (및 info설명서)를 제공 할 수 있습니다.

예, 당신은 올바른 길을 가고 있습니다.

그렇습니다. 대괄호는 옵션 품목에 대한 일반적인 지표입니다.

일반적으로 스케치 한대로 맨 위에 명령 줄 요약이 있으며 그 뒤에 세부적으로 각 옵션에 대한 샘플이 있습니다. (귀하의 예제는 각 옵션 설명 사이에 줄을 표시하지만 편집 문제이며 실제 프로그램은 들여 쓰기 옵션 목록을 사이에 빈 줄없이 출력한다고 가정합니다. 이것은 어떤 경우에도 따라야 할 표준입니다.)

최신 트렌드 (이 문제를 해결하는 POSIX 사양이있을 수 있습니까?)는 문서화를위한 맨 페이지 시스템을 제거하고 program --help출력의 일부로 맨 페이지에있을 모든 정보를 포함합니다 . 이 추가 정보에는 더 긴 설명, 개념 설명, 사용 샘플, 알려진 제한 사항 및 버그, 버그보고 방법 및 관련 명령에 대한 '참조'섹션이 포함됩니다.

이게 도움이 되길 바란다.

나는 tar와 같은 공식 프로젝트를 예로 들어 보겠습니다. 내 의견으로는 msg. 가능한 단순하고 설명 적이어야합니다. 사용 예도 좋습니다. "표준 도움말"이 실제로 필요하지 않습니다.