Re: [PATCH] Beautify usage messages

[Carsten Grohmann]

Am Donnerstag, 1. Oktober 2009 schrieb Daniele Forsi:
> 2009/10/1  <address@hidden>:
> > I did some research into standards / guidelines for usage messages and
> > found two documents: - Metasyntax
> > (http://en.wikipedia.org/wiki/Metasyntax)
> >  - Posix "Utility Argument Syntax"
> > (http://www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html)
> >
> > The current syntax (not the discussed patch) is Posix compliant. The
> > style with angle brackets are more like GNU.
> 
> I see that POSIX doesn't mention { and }
> the | alone should group the alternative just fine
> "8. Arguments separated by the '|' ( <vertical-line>) bar notation are
> mutually-exclusive."
> What do you think?
> 
>           --netmonitor {reset|off|field|devel|next|nr}
>           --getmms memory_type start [end] [{--mime|--pdu|--raw} file]
>           --divert {--op|-o} {register|enable|query|disable|erasure}
>                  {--type|-t} {all|busy|noans|outofreach|notavail}
>                  {--call|-c} {all|voice|fax|data}
>                  [{--timeout|-m} time_in_seconds]
>                  [{--number|-n} number]
>           --sendlogo {caller|op|picture} destination logofile
>           --setlogo {dealer|text} [text]
>           --getlogo {dealer|text}

I read the OpenLDAP documentation yesterday. One of the manpages contains:
 syncrepl     rid=<replica     ID>   provider=ldap[s]://<hostname>[:port]
      [type=refreshOnly|refreshAndPersist]        [interval=dd:hh:mm:ss]
      [retry=[<retry  interval>  <#  of retries>]+] searchbase=<base DN>
      [filter=<filter  str>]  [scope=sub|one|base]  [attrs=<attr  list>]
      [attrsonly]         [sizelimit=<limit>]        [timelimit=<limit>]
      [schemachecking=on|off]                    [starttls=yes|critical]

I see 3 possibilities for usage messages:
 1. Current scheme
  "--getmms memory_type start [end] [{--mime|--pdu|--raw} file]"

 2. Remove { and } only
 "--getmms memory_type start [end] [--mime|--pdu|--raw file]"

 3. Remove { and } as well as use angle brackets 
 "--getmms <memory type> <start> [end] [--mime|--pdu|--raw <file>]"

I'd like to switch the schema to possibility 3. It's easy to read and 
understand. Possibility 3 has an disadvantage, that you 
can't distinguish text elements from elements to replace.

What do you think?

Ciao,
Carsten