Re: Reorganizing guix package commands

[myglc2]

Alex Kost <address@hidden> writes:

> John Darrington (2016-04-20 08:34 +0300) wrote:
>
>> On Tue, Apr 19, 2016 at 11:45:26PM -0400, myglc2 wrote:
>>
>>      Table 2: Novice-friendly Commands
>>      =================================
>>      | existing command                       | new command           |
>>      |----------------------------------------+-----------------------|
>>      | guix package --list-available[=REGEXP] | guix available REGEXP |
>>      | guix package --search=REGEXP           | guix find REGEXP      |
>>      | guix package --show=PACKAGE            | guix show PACKAGE     |
>>      | guix package --install PACKAGE         | guix install PACKAGE  |
>>      | guix package --remove PACKAGE          | guix remove PACKAGE   |
>>      | guix package --list-installed[=REGEXP] | guix list             |
>>      | guix package --roll-back               | guix roll-back        |
>>
>>      This makes the most important new user commands simpler and it makes
>>      them appear in "guix help". IMO, this will go a long way to improving
>>      the novice user's experience.
>>
>> I agree this would make more sense.
>
> Oh, no!  I had an opposite idea: I think there should be only
> unambiguous subcommands!
>
>> 1. I never did understand why we use so many  -- flags.  Options are supposed
>>    to be just that:  Options to affect nuances about how the command should 
>> be
>>    executed. Eg "ls --color" (We don't type "file --list")  Options should 
>> not
>>    normally be used for selecting a command to run.
>
> I agree, I would prefer more actions/subcommands and less options/flags.
>
>> 2. However, I wonder if such an arrangement could come back and bite us?  For
>>    example there are a number of other things that one might want to remove, 
>> list, show or find -
>>    not just packages;  Profiles, services for example.  How would doing that 
>> fit
>>    into the above scheme?
>
> This is exactly why I think these commands (show, install, list, etc.)
> shouldn't be top-level.  IMO some of them should be inside "guix
> package" and some inside "guix profile".

Would we all agree with the following?

IMPLIED OBJECT (guix VERB ...)
PROS:
- less typing
CONS:
- each verb must be assigned to a single object type

EXPLICIT OBJECT (guix OBJECT VERB ...)
PROS:
- verb may be (re)used on multiple object types
CONS:
- more typing

For comparison, I tried to think of similarly complex command sets. For
example, I use 'git' and 'mdadm'. They both use a mixture of these
approaches that favors the implied object model.  mdadm mostly uses
options for actions and git mostly use sub-commands. IMO, both are
difficult to use.

It is not obvious to me that they would be improved by switching to a
pure explicit object model, but it would definitely mean more
typing. Looking at git help, the commands are grouped by pattern of use.
This seems like a good thing.

Re the EXPLICIT OBJECT model:

Elsewhere in this thread, Alex cites 'ip' as an example of a pure
explicit object command set. I don't use it enough to have an opinion,
but I see that 'ip help' does not show any VERBs (AKA COMMANDS), so I
don't know how I could actually do anything reading the ip help ;-(

Any other examples?

Based on this, my opinion is:

- we should use a mixture of the models. It might not be pure but it
  is a pattern that is familiar to users

- To increase ease of use, we should assign a one-to-one relationship
  between VERB <-> OBJECT for frequently used commands.

- I still like the original proposals above

New proposal: guix help should group commands by pattern of use.

Comments?

- George

***
git help
usage: git [--version] [--help] [-C <path>] [-c name=value]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           <command> [<args>]

These are common Git commands used in various situations:

start a working area (see also: git help tutorial)
   clone      Clone a repository into a new directory
   init       Create an empty Git repository or reinitialize an existing one

work on the current change (see also: git help everyday)
   add        Add file contents to the index
   mv         Move or rename a file, a directory, or a symlink
   reset      Reset current HEAD to the specified state
   rm         Remove files from the working tree and from the index

examine the history and state (see also: git help revisions)
   bisect     Use binary search to find the commit that introduced a bug
   grep       Print lines matching a pattern
   log        Show commit logs
   show       Show various types of objects
   status     Show the working tree status

grow, mark and tweak your common history
   branch     List, create, or delete branches
   checkout   Switch branches or restore working tree files
   commit     Record changes to the repository
   diff       Show changes between commits, commit and working tree, etc
   merge      Join two or more development histories together
   rebase     Forward-port local commits to the updated upstream head
   tag        Create, list, delete or verify a tag object signed with GPG

collaborate (see also: git help workflows)
   fetch      Download objects and refs from another repository
   pull       Fetch from and integrate with another repository or a local branch
   push       Update remote refs along with associated objects

'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.

***
mdadm is used for building, managing, and monitoring
Linux md devices (aka RAID arrays)
Usage: mdadm --create device options...
            Create a new array from unused devices.
       mdadm --assemble device options...
            Assemble a previously created array.
       mdadm --build device options...
            Create or assemble an array without metadata.
       mdadm --manage device options...
            make changes to an existing array.
       mdadm --misc options... devices
            report on or modify various md related devices.
       mdadm --grow options device
            resize/reshape an active array
       mdadm --incremental device
            add/remove a device to/from an array as appropriate
       mdadm --monitor options...
            Monitor one or more array for significant changes.
       mdadm device options...
            Shorthand for --manage.
Any parameter that does not start with '-' is treated as a device name
or, for --examine-bitmap, a file name.
The first such name is often the name of an md device.  Subsequent
names are often names of component devices.

 For detailed help on the above major modes use --help after the mode
 e.g.
         mdadm --assemble --help
 For general help on options use
         mdadm --help-options

***
ip help
Usage: ip [ OPTIONS ] OBJECT { COMMAND | help }
       ip [ -force ] -batch filename
where  OBJECT := { link | addr | addrlabel | route | rule | neigh | ntable |
                   tunnel | tuntap | maddr | mroute | mrule | monitor | xfrm |
                   netns | l2tp | tcp_metrics | token | netconf }
       OPTIONS := { -V[ersion] | -s[tatistics] | -d[etails] | -r[esolve] |
                    -f[amily] { inet | inet6 | ipx | dnet | bridge | link } |
                    -4 | -6 | -I | -D | -B | -0 |
                    -l[oops] { maximum-addr-flush-attempts } |
                    -o[neline] | -t[imestamp] | -b[atch] [filename] |
                    -rc[vbuf] [size]}