Có một định dạng tiêu chuẩn của Wikipedia cho văn bản trợ giúp dòng lệnh / shell?

Nếu không, có một tiêu chuẩn thực tế? Về cơ bản tôi đang viết một dòng lệnh trợ giúp văn bản như vậy:

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

Tôi đã làm điều đó từ cơ bản chỉ là đọc văn bản trợ giúp của các công cụ khác nhau, nhưng có một danh sách các hướng dẫn hay cái gì đó không? Ví dụ: tôi có sử dụng dấu ngoặc vuông hoặc dấu ngoặc đơn không? Làm thế nào để sử dụng khoảng cách? Điều gì xảy ra nếu đối số là một danh sách? Cảm ơn!

Thông thường, đầu ra trợ giúp của bạn nên bao gồm:

• Mô tả về những gì ứng dụng làm
• Cú pháp sử dụng, trong đó:
  • Sử dụng [options]để chỉ ra các tùy chọn đi đâu
  • arg_name cho một yêu cầu, số ít arg
  • [arg_name] cho một tùy chọn, số ít arg
  • arg_name... đối với một đối số bắt buộc trong đó có thể có nhiều (điều này là hiếm)
  • [arg_name...] cho một đối số mà bất kỳ số nào có thể được cung cấp
  • lưu ý rằng arg_namephải là một mô tả, tên ngắn, trong trường hợp thấp hơn, con rắn
• Một danh sách các tùy chọn được định dạng độc đáo, mỗi tùy chọn:
  • có một mô tả ngắn
  • hiển thị giá trị mặc định, nếu có
  • hiển thị các giá trị có thể, nếu điều đó áp dụng
  • Lưu ý rằng nếu một tùy chọn có thể chấp nhận một hình thức ngắn (ví dụ -l) hoặc một hình thức dài (ví dụ --list), hãy kết hợp chúng lại với nhau trên cùng một dòng, vì các mô tả của chúng sẽ giống nhau
• Chỉ báo ngắn gọn về vị trí của tệp cấu hình hoặc biến môi trường có thể là nguồn của các đối số dòng lệnh, ví dụ: GREP_OPTS
• Nếu có một trang man, hãy biểu thị như vậy, nếu không, chỉ báo ngắn gọn về nơi có thể tìm thấy trợ giúp chi tiết hơn

Lưu ý thêm rằng đây là hình thức tốt để chấp nhận cả hai -hvà --helpkích hoạt thông báo này và bạn sẽ hiển thị thông báo này nếu người dùng làm hỏng cú pháp dòng lệnh, ví dụ bỏ qua một đối số bắt buộc.

Hãy nhìn vào docopt . Đây là một tiêu chuẩn chính thức để ghi lại (và tự động phân tích cú pháp) các đối số dòng lệnh.

Ví dụ...

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>...

Tôi nghĩ rằng không có cú pháp tiêu chuẩn để sử dụng dòng lệnh, nhưng hầu hết sử dụng quy ước này:

Microsoft Cú pháp dòng lệnh , IBM có Cú pháp dòng lệnh tương tự

• Text without brackets or braces

  Các mục bạn phải nhập như hình
  
  

• <Text inside angle brackets>

  Giữ chỗ mà bạn phải cung cấp một giá trị
  
  

• [Text inside square brackets]

  Các mặt hàng tùy chọn
  
  

• {Text inside braces}

  Đặt các mặt hàng cần thiết; chọn một
  
  

• Thanh dọc {a|b}

  Dấu phân cách cho các mục loại trừ lẫn nhau; chọn một
  
  

• Dấu chấm lửng <file> …

  Các mục có thể được lặp đi lặp lại
  
  

Chúng tôi đang chạy Linux, một hệ điều hành chủ yếu tuân thủ POSIX. Các tiêu chuẩn POSIX cần có: Cú pháp đối số tiện ích .

• Một tùy chọn là một dấu gạch nối theo sau bởi một ký tự chữ và số, như thế này : -o.
• Một tùy chọn có thể yêu cầu một đối số (phải xuất hiện ngay sau tùy chọn); ví dụ, -o argumenthoặc -oargument.
• Các tùy chọn không yêu cầu đối số có thể được nhóm lại sau dấu gạch nối, vì vậy, ví dụ, -lsttương đương với -t -l -s.
• Các tùy chọn có thể xuất hiện theo bất kỳ thứ tự nào; do đó -lsttương đương với -tls.
• Tùy chọn có thể xuất hiện nhiều lần.
• Tùy chọn đi trước các đối số nonoption khác: -lstnonoption.
• Đối --số chấm dứt các tùy chọn.
• Các -tùy chọn thường được sử dụng để đại diện cho một trong những con suối đầu vào tiêu chuẩn.

Microsoft có thông số kỹ thuật tiêu chuẩn dòng lệnh của riêng họ :

Tài liệu này được tập trung tại các nhà phát triển các tiện ích dòng lệnh. Nói chung, mục tiêu của chúng tôi là trình bày một trải nghiệm người dùng dòng lệnh nhất quán, có thể kết hợp. Đạt được điều đó cho phép người dùng tìm hiểu một tập hợp các khái niệm cốt lõi (cú pháp, đặt tên, hành vi, v.v.) và sau đó có thể chuyển kiến ​​thức đó thành làm việc với một nhóm lệnh lớn. Các lệnh đó có thể xuất các luồng dữ liệu được chuẩn hóa theo định dạng chuẩn để cho phép bố cục dễ dàng mà không phải chịu trách nhiệm phân tích luồng văn bản đầu ra. Tài liệu này được viết để độc lập với bất kỳ triển khai cụ thể nào của trình bao, bộ tiện ích hoặc công nghệ tạo lệnh; tuy nhiên, Phụ lục J - Sử dụng Windows Powershell để triển khai Microsoft Command Line Standard cho thấy cách sử dụng Windows PowerShell sẽ cung cấp miễn phí nhiều hướng dẫn này.

Tiêu chuẩn mã hóa GNU là một tài liệu tham khảo tốt cho những thứ như thế này. Phần này đề cập đến đầu ra của --help. Trong trường hợp này nó không cụ thể lắm. Bạn có thể không thể sai khi in một bảng hiển thị các tùy chọn ngắn và dài và một mô tả ngắn gọn. Cố gắng có được khoảng cách giữa tất cả các đối số phù hợp để dễ đọc. Bạn có thể muốn cung cấp một mantrang (và có thể là một infohướng dẫn) cho công cụ của bạn để cung cấp một lời giải thích phức tạp hơn.

vâng, bạn đang đi đúng hướng.

có, dấu ngoặc vuông là chỉ báo thông thường cho các mục tùy chọn.

Thông thường, như bạn đã phác thảo, có một bản tóm tắt dòng lệnh ở trên cùng, theo sau là chi tiết, lý tưởng với các mẫu cho mỗi tùy chọn. (Ví dụ của bạn hiển thị các dòng ở giữa mỗi mô tả tùy chọn, nhưng tôi cho rằng đó là vấn đề chỉnh sửa và chương trình thực của bạn đưa ra danh sách tùy chọn thụt lề không có dòng trống ở giữa. Đây sẽ là tiêu chuẩn để tuân theo trong mọi trường hợp.)

Một xu hướng mới hơn, (có thể có một đặc tả POSIX giải quyết vấn đề này?), Là loại bỏ hệ thống trang man cho tài liệu, và bao gồm tất cả thông tin sẽ có trong một trang như một phần của program --helpđầu ra. Phần bổ sung này sẽ bao gồm các mô tả dài hơn, các khái niệm được giải thích, các mẫu sử dụng, các hạn chế và lỗi đã biết, cách báo cáo lỗi và có thể là phần 'xem thêm' cho các lệnh liên quan.

Tôi hi vọng cái này giúp được.

Tôi sẽ theo dõi các dự án chính thức như tar làm ví dụ. Theo ý kiến ​​của tôi giúp đỡ tin nhắn. cần phải đơn giản và mô tả càng tốt. Ví dụ sử dụng là tốt quá. Không có nhu cầu thực sự cho "trợ giúp tiêu chuẩn".