Esiste un formato "standard" per il testo di aiuto della riga di comando / shell?

In caso contrario, esiste uno standard di fatto? Fondamentalmente sto scrivendo un testo di aiuto dalla riga di comando in questo modo:

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

L'ho fatto praticamente leggendo il testo di aiuto di vari strumenti, ma esiste un elenco di linee guida o qualcosa del genere? Ad esempio, utilizzo parentesi quadre o parentesi? Come usare la spaziatura? Cosa succede se l'argomento è un elenco? Grazie!

In genere, l'output della guida dovrebbe includere:

• Descrizione di ciò che fa l'app
• Sintassi d'uso, che:
  • Utilizza [options]per indicare dove vanno le opzioni
  • arg_name per un arg richiesto, singolare
  • [arg_name] per un arg opzionale, singolare
  • arg_name... per un argomento richiesto di cui possono essercene molti (questo è raro)
  • [arg_name...] per un arg per il quale è possibile fornire qualsiasi numero
  • si noti che arg_namedovrebbe essere un nome descrittivo, abbreviato, in minuscolo, caso di serpente
• Un elenco di opzioni ben formattate, ognuna:
  • avere una breve descrizione
  • mostrando il valore predefinito, se ce n'è uno
  • mostrando i possibili valori, se applicabile
  • Si noti che se un'opzione può accettare una forma breve (ad esempio -l) o una forma lunga (ad esempio --list), includerli insieme sulla stessa riga, poiché le loro descrizioni saranno le stesse
• Breve indicatore della posizione dei file di configurazione o delle variabili di ambiente che potrebbero essere la fonte degli argomenti della riga di comando, ad es GREP_OPTS
• Se è presente una pagina man, indicare come tale, altrimenti un breve indicatore di dove è possibile trovare un aiuto più dettagliato

Si noti inoltre che è una buona forma accettare entrambi -he --helpattivare questo messaggio e che è necessario mostrare questo messaggio se l'utente confonde la sintassi della riga di comando, ad esempio omette un argomento richiesto.

Dai un'occhiata a docopt . È uno standard formale per documentare (e analizzare automaticamente) gli argomenti della riga di comando.

Per esempio...

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

Penso che non ci sia sintassi standard per l'utilizzo della riga di comando, ma la maggior parte usa questa convenzione:

Sintassi della riga di comando di Microsoft , IBM ha una sintassi della riga di comando simile

• Text without brackets or braces

  Articoli che devi digitare come mostrato
  
  

• <Text inside angle brackets>

  Segnaposto per il quale è necessario fornire un valore
  
  

• [Text inside square brackets]

  Articoli opzionali
  
  

• {Text inside braces}

  Set di articoli richiesti; scegline uno
  
  

• Barra verticale {a|b}

  Separatore per articoli reciprocamente esclusivi; scegline uno
  
  

• ellissi <file> …

  Articoli che possono essere ripetuti
  
  

Stiamo eseguendo Linux, un sistema operativo per lo più conforme a POSIX. Gli standard POSIX dovrebbero essere: Sintassi dell'argomento utility .

• Un'opzione è un trattino seguito da un singolo carattere alfanumerico, in questo modo: -o.
• Un'opzione può richiedere un argomento (che deve apparire immediatamente dopo l'opzione); per esempio, -o argumento -oargument.
• Le opzioni che non richiedono argomenti possono essere raggruppate dopo un trattino, quindi, ad esempio, -lstè equivalente a -t -l -s.
• Le opzioni possono apparire in qualsiasi ordine; quindi -lstequivale a -tls.
• Le opzioni possono apparire più volte.
• Le opzioni precedono altri argomenti di non -lstopzione : non opzione.
• L' --argomento termina le opzioni.
• L' -opzione viene in genere utilizzata per rappresentare uno dei flussi di input standard.

Microsoft ha le proprie specifiche standard da riga di comando :

Questo documento è destinato agli sviluppatori di utility da riga di comando. Collettivamente, il nostro obiettivo è presentare un'esperienza utente coerente e compostabile dalla riga di comando. Un risultato che consente a un utente di apprendere un insieme di concetti di base (sintassi, denominazione, comportamenti, ecc.) E quindi di essere in grado di tradurre tale conoscenza in un grande insieme di comandi. Tali comandi dovrebbero essere in grado di generare flussi di dati standardizzati in un formato standardizzato per consentire una facile composizione senza l'onere di analizzare i flussi di testo di output. Questo documento è scritto per essere indipendente da qualsiasi implementazione specifica di una shell, set di utilità o tecnologie di creazione di comandi; tuttavia, l'Appendice J - L'uso di Windows Powershell per implementare Microsoft Command Line Standard mostra come l'uso di Windows PowerShell fornirà gratuitamente l'implementazione di molte di queste linee guida.

Lo standard di codifica GNU è un buon riferimento per cose come questa. Questa sezione tratta dell'output di --help. In questo caso non è molto specifico. Probabilmente non puoi sbagliare con la stampa di una tabella che mostra le opzioni brevi e lunghe e una descrizione sintetica. Cerca di ottenere la spaziatura tra tutti gli argomenti giusti per la leggibilità. Probabilmente vuoi fornire una manpagina (e possibilmente un infomanuale) affinché il tuo strumento fornisca una spiegazione più elaborata.

si, sei sulla strada giusta.

sì, le parentesi quadre sono il solito indicatore di articoli opzionali.

In genere, come è stato delineato, nella parte superiore è presente un riepilogo della riga di comando, seguito da dettagli, idealmente con esempi per ciascuna opzione. (Il tuo esempio mostra le righe tra ogni descrizione dell'opzione, ma suppongo che sia un problema di modifica e che il tuo programma reale produca elenchi di opzioni rientrate senza righe vuote tra queste. Questo sarebbe lo standard da seguire in ogni caso.)

Una tendenza più recente, (forse esiste una specifica POSIX che si rivolge a questo?), È l'eliminazione del sistema della pagina man per la documentazione e includendo tutte le informazioni che sarebbero in una pagina man come parte della program --help dell'output. Questo extra includerà descrizioni più lunghe, concetti spiegati, esempi di utilizzo, limitazioni e bug noti, come segnalare un bug e possibilmente una sezione "vedi anche" per i comandi correlati.

Spero che aiuti.

Seguirei progetti ufficiali come tar come esempio. Secondo me aiutare msg. deve essere il più semplice e descrittivo possibile. Anche gli esempi di utilizzo sono buoni. Non è necessario un "aiuto standard".