zsh-workers
 help / color / mirror / Atom feed
* PATCH: list units in brackets at the end of completion group descriptions
@ 2021-08-27 11:52 Oliver Kiddle
  2021-08-27 12:10 ` Daniel Shahaf
  2021-08-27 14:44 ` Mikael Magnusson
  0 siblings, 2 replies; 4+ messages in thread
From: Oliver Kiddle @ 2021-08-27 11:52 UTC (permalink / raw)
  To: Zsh workers

Continuing with the bulk completion fixups for single issues, this
applies the convention of units in round brackets at the end of the
per-group descriptions just before the defaults I was adding in 49156
in square brackets. There aren't so many here because this is harder to
grep for and we mostly already do this consistently. For anyone writing
completions (or --help output), I'd recommend always considering units
and defaults because it's not always obvious.

There might be some more useful way we might indicate where suffixes can
be appended to a value to denote units. Completing them after a number
doesn't really make the options clear before a number has been entered.
Perhaps an initial slash, e.g. 'timeout (seconds) [5] /ms /us /ns'

As I've alluded to before, with consistent forms, _description could
parse these and allow formatting for these components to be configured.
But how often do we put random comments in brackets in descriptions or
other things that would break this? Yet more backslashes will be ugly.

Oliver

diff --git Completion/Debian/Command/_dak Completion/Debian/Command/_dak
index 8ecfd84b3..9976c7371 100644
--- Completion/Debian/Command/_dak
+++ Completion/Debian/Command/_dak
@@ -207,7 +207,7 @@ case $cmd in
 
 (poolize)
     args+=(
-  '(-l --limit)'{-l,--limit=}'[only migrate amount of packages]:amount in kb:'
+  '(-l --limit)'{-l,--limit=}'[only migrate amount of packages]:amount (kb)'
   '(-n --no-action)'{-n,--no-action}'[do not do anything]'
   '(-v --verbose)'{-v,--verbose}'[explain what is being done]'
     )
diff --git Completion/Linux/Command/_tpb Completion/Linux/Command/_tpb
index c4c4c2bbd..2bdee0942 100644
--- Completion/Linux/Command/_tpb
+++ Completion/Linux/Command/_tpb
@@ -9,7 +9,7 @@ _arguments \
   '(-x --xevents)'{-x,--xevents=}':state:(on off)' \
   '(-m --mixer)'{-m,--mixer=}':state:(on off)' \
   '(-o --osd)'{-o,--osd=}':state:(on off)' \
-  '(-p --poll)'{-p,--poll=}':delay in microseconds:' \
+  '(-p --poll)'{-p,--poll=}':delay (microseconds)' \
   '(-t --thinkpad)'{-t,--thinkpad=}':command to execute:_command_names' \
   '(-H --home)'{-H,--home=}':command to execute:_command_names' \
   '(-S --search)'{-S,--search=}':command to execute:_command_names' \
diff --git Completion/Mandriva/Command/_urpmi Completion/Mandriva/Command/_urpmi
index 9ab9e45b7..be6350129 100644
--- Completion/Mandriva/Command/_urpmi
+++ Completion/Mandriva/Command/_urpmi
@@ -73,7 +73,7 @@ _urpmi() {
 
   opts_net=(
     "($help --wget)--curl[use curl to retrieve distant files]"
-    "($help)--limit-rate[limit the download speed (b/s)]:download speed in b/s: "
+    "($help)--limit-rate[limit the download speed]:download speed (b/s)"
     "($help)--proxy:proxy host:_hosts"
     "($help)--proxy-user:proxy user:_users"
     "($help --curl)--wget[use wget to retrieve distant files]"
diff --git Completion/Unix/Command/_cpio Completion/Unix/Command/_cpio
index 699b1d8f2..20f8c712d 100644
--- Completion/Unix/Command/_cpio
+++ Completion/Unix/Command/_cpio
@@ -25,15 +25,15 @@ else
 	   '--message=:message at end of volume:'
 	   '--null' '--reset-access-time'
 	   '--verbose' '--dot' '--append'
-	   '--block-size=:block size in 512 byte units:'
+           '--block-size=:block size (512 byte units)'
 	   '--dereference'
-	   '--io-size=:block size in bytes'
+           '--io-size=:block size (bytes)'
 	   '--quiet' '--force-local'  '--help'   '--version')
     fi
     args+=(
 	  '-A[append files to archive]'
 	  '-B[block size 5120 bytes with special file]'
-	  '-C[set block size per record]:block size in bytes:(8192)'
+          '-C[set block size per record]:block size (bytes)'
 	  '-F[set archive file to use]:archive file:->afile'
 	  '(-H)-c[read/write header in ASCII]'
 	  "(-c)-H[set format type for archive header]:$fmts"
@@ -49,7 +49,7 @@ else
             '--preserve-modification-time' '--numeric'
 	    '--rename' '--list' '--swap-bytes' '--swap-halfwords'
 	    '--dot' '--unconditional' '--verbose'
-	    '--block-size=:block size in 512 byte units:'
+            '--block-size=:block size (512 byte units)'
 	    '--swap-halfwords'
 	    '--io-size=:block size in bytes:'
 	    '--pattern-file=:file with list of patterns:_files'
@@ -63,7 +63,7 @@ else
 	  '-b[reverse bytes in word]'
 	  '-B[block size 5120 bytes with special file]'
 	  '-d[create directories as needed]'
-	  '-C[set block size per record]:block size in bytes:(8192)'
+          '-C[set block size per record]:block size (bytes)'
 	  '-E[read filenames from file]:file name for list of files:_files'
 	  '-f[only copy files not matching patterns]'
 	  '-F[set archive file to use]:archive file:->afile'
diff --git Completion/Unix/Command/_dropbox Completion/Unix/Command/_dropbox
index 115f9eb45..45c77ae09 100644
--- Completion/Unix/Command/_dropbox
+++ Completion/Unix/Command/_dropbox
@@ -55,8 +55,8 @@ else
 
     (throttle)
     _arguments \
-      '2:download limit in KB/s:(unlimited)' \
-      '3:upload limit in KB/s:(unlimited)'
+      '2:download limit (KB/s):(unlimited)' \
+      '3:upload limit (KB/s):(unlimited)'
     ;;
 
     (*)
diff --git Completion/Unix/Command/_growisofs Completion/Unix/Command/_growisofs
index 8f4da4030..206d2c2c7 100644
--- Completion/Unix/Command/_growisofs
+++ Completion/Unix/Command/_growisofs
@@ -270,7 +270,7 @@ else
     '-sort[sort files on the image based on weights defined in the given file]:sort-weighting file:_files' \
     '-sparc-label[set the sun disk-label-name used for the -sparc-boot option]:label' \
     '-split-output[split the output image into several files ~1GiB in size]' \
-    '-stream-media-size[enable streaming operation and set media size to given number of sectors]:media size in sectors' \
+    '-stream-media-size[enable streaming operation and set media size to given number of sectors]:media size (sectors)' \
     '-stream-file-name[reserved for future use]:name' \
     '-sunx86-boot[specify a comma-separated list of file-system images needed to make a bootable Solaris-x86-CD]:list' \
     '-sunx86-label[specify the SVr4 disk-label-name for the SVr4 disk-label created with the -sunx86-boot option]:label' \
diff --git Completion/Unix/Command/_mysql_utils Completion/Unix/Command/_mysql_utils
index a7b285f1c..9f70687b0 100644
--- Completion/Unix/Command/_mysql_utils
+++ Completion/Unix/Command/_mysql_utils
@@ -220,8 +220,8 @@ _mysql_utils() {
   )
 
   _mysql_variables_opts=(
-    '--max_allowed_packet[maximum allowed packet size]:packet size in bytes'
-    '--net_buffer_length[network buffer length]:buffer length in bytes'
+    '--max_allowed_packet[maximum allowed packet size]:packet size (bytes)'
+    '--net_buffer_length[network buffer length]:buffer length (bytes)'
     '--connect_timeout:timeout'
     '--select_limit:limit'
     '--max_join_size:size'
diff --git Completion/Unix/Command/_perforce Completion/Unix/Command/_perforce
index cb6cdb79f..a52ac1d06 100644
--- Completion/Unix/Command/_perforce
+++ Completion/Unix/Command/_perforce
@@ -2668,12 +2668,12 @@ _perforce_cmd_passwd() {
 _perforce_cmd_ping() {
   _arguments -s : \
     '-c[specify count of messages]:count of messages: ' \
-    '-t[specify total time of test]:time in seconds: ' \
+    '-t[specify total time of test]:time (seconds)' \
     '-i[specify iterations for test]:number of iterations: ' \
     '-f[transmit continuously without waiting for responses]' \
-    '-p[specify pause between tests]:pause in seconds: ' \
-    '-s[specify send size]:send size in octets: ' \
-    '-r[specify receive size]:receive size in octets: '
+    '-p[specify pause between tests]:pause (seconds)' \
+    '-s[specify send size]:send size (octets)' \
+    '-r[specify receive size]:receive size (octets)'
 }
 
 
@@ -2942,7 +2942,7 @@ _perforce_cmd_status() {
 _perforce_cmd_sizes() {
   _arguments -s : \
     '-a[list all revisions in range]' \
-    '-b[specify blocksize]:blocksize in bytes: ' \
+    '-b[specify blocksize]:blocksize (bytes)' \
     '(-H)-h[print sizes in human-readable form (GiB)]' \
     '(-h)-H[print sizes in human-readable form (GB)]' \
     '-m[limit max files]:max files: ' \
diff --git Completion/Unix/Command/_transmission Completion/Unix/Command/_transmission
index 8951eacb0..c060cbae3 100644
--- Completion/Unix/Command/_transmission
+++ Completion/Unix/Command/_transmission
@@ -13,10 +13,10 @@ local general_options=(
 )
 # `general_actions`: *actions* that can be specified when a specific set of torrents is either specified or either not
 local general_actions=(
-  '(- :)'{-gsr,--global-seedratio}'[all torrents, unless overridden by a per-torrent setting, should seed until a specific ratio]:ratio:{_message "ratio in kB/sec"}'
+  '(- :)'{-gsr,--global-seedratio}'[all torrents, unless overridden by a per-torrent setting, should seed until a specific ratio]:ratio (kB/s)'
   '(- :)'{-GSR,--no-global-seedratio}'[all torrents, unless overridden by a per-torrent setting, should seed regardless of ratio]'
   '(- :)'{-pr,--peers}'[set the maximum number of peers]:number: '
-  '(- :)'{-d+,--downlimit=}'[limit the maximum download speed to limit kB/s]:limit:{_message "limit in kB/sec"}'
+  '(- :)'{-d+,--downlimit=}'[limit the maximum download speed to limit kB/s]:limit (kB/s)'
   '(- :)'{-D,--no-downlimit}'[disable download speed limits]'
 )
 # `global_only_actions`: *actions* that can be specified only when no specific torrent is specified
@@ -27,8 +27,8 @@ local global_only_actions=(
   '(- :)'{-asu,--alt-speed-uplimit}'[limit the alternate upload speed to limit kilobytes per second]'
   '(- :)'{-asc,--alt-speed-scheduler}'[use the scheduled on/off times]'
   '(- :)'{-asc,--not-alt-speed-scheduler}'[don'"'"'t use the scheduled on/off times]'
-  '(- :)--alt-speed-time-begin[time to start using the alt speed limits]:hhmm:_transmission-remote_time'
-  '(- :)--alt-speed-time-end[time to stop using the alt speed limits]:hhmm:_transmission-remote_time'
+  '(- :)--alt-speed-time-begin[time to start using the alt speed limits]:time (HHMM)'
+  '(- :)--alt-speed-time-end[time to stop using the alt speed limits]:time (HHMM)'
   '(- :)--alt-speed-days[set the number of days on which to enable the speed scheduler]:days:_transmission-remote_days'
   '(- :)--torrent-done-script[specify a file to run each time a torrent finishes]:script:_files'
   '(- :)--no-torrent-done-script[don'"'"'t run any script when a torrent finishes]'
@@ -51,7 +51,7 @@ local global_only_actions=(
   '(- :)'{-M,--no-portmap}'[disable portmapping]'
   '(- :)'{-o,--dht}'[enable distributed hash table]'
   '(- :)'{-O,--no-dht}'[disable distributed hash table]'
-  '(- :)'{-u,--uplimit}'[limit the maximum upload speed to limit kB/s]:limit:{_message "limit in kB/sec"}'
+  '(- :)'{-u,--uplimit}'[limit the maximum upload speed to limit kB/s]:limit (kB/s)'
   '(- :)'{-U,--no-uplimit}'[disable upload speed limits]'
   '(- :)--utp[enable uTP for peer connections]'
   '(- :)--no-utp[disable uTP for peer connections]'
@@ -89,7 +89,7 @@ local torrent_action_only_actions=(
   {-rad,--remove-and-delete}'[remove the current torrent(s) and delete the downloaded data]'
   '--reannounce[reannounce the current torrent(s)]'
   '--move[move the current torrents'"'"' data from their current locations to the specified directory]:{_files -/}'
-  {-sr+,--seedratio=}'[let the current torrent(s) seed until a specific ratio]:ratio:{_message "ratio in kB/sec"}'
+  {-sr+,--seedratio=}'[let the current torrent(s) seed until a specific ratio]:ratio'
   {-SR,--no-seedratio}'[let the current torrent(s) use the global seedratio settings]'
   {-hl,--honor-session}'[make the current torrent(s) honor the session limits]'
   {-HL,--no-honor-session}'[make the current torrent(s) not honor the session limits]'
@@ -104,12 +104,6 @@ local torrent_action_only_actions=(
 
 # helper functions
 
-# complete argument specified after global only action: `--alt-speed-time-begin`
-# completes time in HHMM format
-(( $+functions[_transmission-remote_time] )) ||
-_transmission-remote_time(){
-  _message "time in format HHMS"
-}
 # complete argument specified after global only action: `--alt-speed-days`
 # completes days in a list such as "2,4-6".
 (( $+functions[_transmission-remote_days] )) ||
diff --git Completion/X/Command/_urxvt Completion/X/Command/_urxvt
index 661897c3a..2d7c09579 100644
--- Completion/X/Command/_urxvt
+++ Completion/X/Command/_urxvt
@@ -43,8 +43,8 @@ _x_arguments \
   '-sl:save lines' \
   '-embed:window id to embed terminal in:_x_window' \
   '-pty-fd:file descriptor of pty to use' \
-  '-w:external border in pixels' \
-  '-b:internal border in pixels' \
+  {-bw,-w}':external border (pixels)' \
+  '-b:internal border (pixels)' \
   '-lsp:number of extra pixels between rows' \
   '-letsp:letter spacing adjustment' \
   '-mod:meta modifier:_x_modifier' \


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: PATCH: list units in brackets at the end of completion group descriptions
  2021-08-27 11:52 PATCH: list units in brackets at the end of completion group descriptions Oliver Kiddle
@ 2021-08-27 12:10 ` Daniel Shahaf
  2021-08-27 14:44 ` Mikael Magnusson
  1 sibling, 0 replies; 4+ messages in thread
From: Daniel Shahaf @ 2021-08-27 12:10 UTC (permalink / raw)
  To: zsh-workers

Oliver Kiddle wrote on Fri, 27 Aug 2021 11:52 +00:00:
> There might be some more useful way we might indicate where suffixes can
> be appended to a value to denote units. Completing them after a number
> doesn't really make the options clear before a number has been entered.
> Perhaps an initial slash, e.g. 'timeout (seconds) [5] /ms /us /ns'

This design first says "Input a value in seconds", then the default
value, then goes back to say that other units are possible.

I think we should try for a design with more locality in the provision
of information.  For instance, assuming the default unit may also be
specified explicitly:

    timeout [5 = 5s]
    # This intends to communicate that both «5» and «5s» are valid inputs, and equivalent.

    timeout [5] ; hr/[s]/ms/us/ns
    # Indicate the default value and default unit separately, indicating all units in a group

I'm sure there are better options than these.

Cheers,

Daniel


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: PATCH: list units in brackets at the end of completion group descriptions
  2021-08-27 11:52 PATCH: list units in brackets at the end of completion group descriptions Oliver Kiddle
  2021-08-27 12:10 ` Daniel Shahaf
@ 2021-08-27 14:44 ` Mikael Magnusson
  2021-08-27 16:14   ` Oliver Kiddle
  1 sibling, 1 reply; 4+ messages in thread
From: Mikael Magnusson @ 2021-08-27 14:44 UTC (permalink / raw)
  To: Oliver Kiddle; +Cc: Zsh workers

On 8/27/21, Oliver Kiddle <opk@zsh.org> wrote:
> Continuing with the bulk completion fixups for single issues, this
> applies the convention of units in round brackets at the end of the
> per-group descriptions just before the defaults I was adding in 49156
> in square brackets. There aren't so many here because this is harder to
> grep for and we mostly already do this consistently. For anyone writing
> completions (or --help output), I'd recommend always considering units
> and defaults because it's not always obvious.
>
> There might be some more useful way we might indicate where suffixes can
> be appended to a value to denote units. Completing them after a number
> doesn't really make the options clear before a number has been entered.
> Perhaps an initial slash, e.g. 'timeout (seconds) [5] /ms /us /ns'
>
> As I've alluded to before, with consistent forms, _description could
> parse these and allow formatting for these components to be configured.
> But how often do we put random comments in brackets in descriptions or
> other things that would break this? Yet more backslashes will be ugly.
>
> Oliver
>
> diff --git Completion/Debian/Command/_dak Completion/Debian/Command/_dak
> index 8ecfd84b3..9976c7371 100644
> --- Completion/Debian/Command/_dak
> +++ Completion/Debian/Command/_dak
> @@ -207,7 +207,7 @@ case $cmd in
>
>  (poolize)
>      args+=(
> -  '(-l --limit)'{-l,--limit=}'[only migrate amount of packages]:amount in
> kb:'
> +  '(-l --limit)'{-l,--limit=}'[only migrate amount of packages]:amount
> (kb)'
>    '(-n --no-action)'{-n,--no-action}'[do not do anything]'
>    '(-v --verbose)'{-v,--verbose}'[explain what is being done]'
>      )
> diff --git Completion/Mandriva/Command/_urpmi
> Completion/Mandriva/Command/_urpmi
> index 9ab9e45b7..be6350129 100644
> --- Completion/Mandriva/Command/_urpmi
> +++ Completion/Mandriva/Command/_urpmi
> @@ -73,7 +73,7 @@ _urpmi() {
>
>    opts_net=(
>      "($help --wget)--curl[use curl to retrieve distant files]"
> -    "($help)--limit-rate[limit the download speed (b/s)]:download speed in
> b/s: "
> +    "($help)--limit-rate[limit the download speed]:download speed (b/s)"
>      "($help)--proxy:proxy host:_hosts"
>      "($help)--proxy-user:proxy user:_users"
>      "($help --curl)--wget[use wget to retrieve distant files]"
> diff --git Completion/Unix/Command/_dropbox
> Completion/Unix/Command/_dropbox
> index 115f9eb45..45c77ae09 100644
> --- Completion/Unix/Command/_dropbox
> +++ Completion/Unix/Command/_dropbox
> @@ -55,8 +55,8 @@ else
>
>      (throttle)
>      _arguments \
> -      '2:download limit in KB/s:(unlimited)' \
> -      '3:upload limit in KB/s:(unlimited)'
> +      '2:download limit (KB/s):(unlimited)' \
> +      '3:upload limit (KB/s):(unlimited)'
>      ;;
>
>      (*)

some inconsistencies here with kilos and bytes, it should always be kB
although I doubt anyone would ever think kilobits or kelvinbytes are
refered to in these contexts. The urpmi one should probably be spelled
out as bytes/s or B/s though (somehow it feels less clear to me
without the kilo). Perhaps worth a separate batch cleanup.

-- 
Mikael Magnusson


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: PATCH: list units in brackets at the end of completion group descriptions
  2021-08-27 14:44 ` Mikael Magnusson
@ 2021-08-27 16:14   ` Oliver Kiddle
  0 siblings, 0 replies; 4+ messages in thread
From: Oliver Kiddle @ 2021-08-27 16:14 UTC (permalink / raw)
  To: Mikael Magnusson; +Cc: Zsh workers

Mikael Magnusson wrote:
> > -      '3:upload limit in KB/s:(unlimited)'

> some inconsistencies here with kilos and bytes, it should always be kB
> although I doubt anyone would ever think kilobits or kelvinbytes are
> refered to in these contexts. The urpmi one should probably be spelled
> out as bytes/s or B/s though (somehow it feels less clear to me
> without the kilo). Perhaps worth a separate batch cleanup.

I intentionally left them exactly as they were before. That should
be done as a separate cleanup but is not really something I'm keen
to tackle because you'd have to look into each programme to find out
whether it is bits or bytes and kilo or kibi. I'd guess there are plenty
more of these too.

For bandwidth, bits rather than bytes is actually fairly likely.

Oliver


^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2021-08-27 16:14 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-08-27 11:52 PATCH: list units in brackets at the end of completion group descriptions Oliver Kiddle
2021-08-27 12:10 ` Daniel Shahaf
2021-08-27 14:44 ` Mikael Magnusson
2021-08-27 16:14   ` Oliver Kiddle

zsh-workers

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.vuxu.org/zsh-workers

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 zsh-workers zsh-workers/ https://inbox.vuxu.org/zsh-workers \
		zsh-workers@zsh.org
	public-inbox-index zsh-workers

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.vuxu.org/vuxu.archive.zsh.workers


code repositories for the project(s) associated with this inbox:

	https://git.vuxu.org/mirror/zsh/

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git