setup-*.exe --help default explanation re -D/-L options [Was: [ANNOUNCEMENT] Updated: setup (2.917)]

setup-*.exe --help default explanation re -D/-L options [Was: [ANNOUNCEMENT] Updated: setup (2.917)]

[Adam Dinwoodie]

On  Mon, 31 Jan 2022 12:56:13 -0700, Brian Inglis wrote:
> On 2022-01-31 08:46, Andrey Repin wrote:
> > Greetings, Jon Turney!
> > 
> > > Probably what's wanted is to remember the state of those checkboxes, if
> > > this isn't the first time setup has been run?
> > 
> > That's a feature silently longed for for a loong time. :) But this is such a
> > low priority, very few people actually mentioned it in the past years.
> 
> It could usefully be added similarly to last-action:
> 
> 	$ fgrep -A1 action /etc/setup/setup.rc
> 	last-action
> 		Download,Install
> 
> last-shortcut:
> 	Desktop|StartMenu|none,...

This reminded me of a bug report I've been meaning to properly
characterise and report for a while, and also pointed me at a
workaround...

Currently, running `setup-*.exe --help` produces output that includes
the following:

    -D --download       Download packages from internet only
    -L --local-install  Install packages from local directory only

    The default is to both download and install packages, unless either
    --download or --local-install is specified.

I think the descriptions for the `-D` and `-L` options are misleading,
at least in combination with that final line, which is definitely wrong.
As I understand it, the actual behaviour would be better described by
something like the below:

    -D --download       Download packages from internet only, unless -L
                        is also specified
    -L --local-install  Install packages from local directory only,
                        unless -D is also specified

    If neither --download nor --local-install is specified, the default
    is to repeat the same action as from the previous run.  If no
    previous run can be found, the default is to perform both actions,
    and both actions can be explicitly requested by specifying both
    --download and --local-install.

In particular, the fact that the two options currently say they will
"only" do their action, and that the default is to perform both, lead me
to believe (a) the options were mutually exclusive and one would
presumably override the other, (b) this was probably a legacy from
before setup.rc stored the previous action, and therefore (c) if I was
running setup with `-q` or `-M`, there was no way to get the supposedly
default "do both" behaviour; I'd instead need to go through the full
GUI.

Having now seen how this setting is stored, I've realised I can just
call setup with `-DL` and it'll perform both actions again.  But I think
my assumption that "default" was supposed to mean "default always" not
"default only on first run" wasn't *entirely* PEBCAK (even if it mostly
was), so that help text would definitely benefit from being made a bit
more explicit.

(I'm aware my suggestion above is decidedly wordy; it's not intended to
be exactly what I think is required, only a first pass at clarifying the
key details I think are missing.)

Re: setup-*.exe --help default explanation re -D/-L options [Was: [ANNOUNCEMENT] Updated: setup (2.917)]

[Jon Turney]

On 31/01/2022 22:11, Adam Dinwoodie wrote:
> On  Mon, 31 Jan 2022 12:56:13 -0700, Brian Inglis wrote:
>> On 2022-01-31 08:46, Andrey Repin wrote:
>>> Greetings, Jon Turney!
>>>
>>>> Probably what's wanted is to remember the state of those checkboxes, if
>>>> this isn't the first time setup has been run?
>>>
>>> That's a feature silently longed for for a loong time. :) But this is such a
>>> low priority, very few people actually mentioned it in the past years.
>>
>> It could usefully be added similarly to last-action:
>>
>> 	$ fgrep -A1 action /etc/setup/setup.rc
>> 	last-action
>> 		Download,Install
>>
>> last-shortcut:
>> 	Desktop|StartMenu|none,...
> 
> This reminded me of a bug report I've been meaning to properly
> characterise and report for a while, and also pointed me at a
> workaround...
> 
> Currently, running `setup-*.exe --help` produces output that includes
> the following:
> 
>      -D --download       Download packages from internet only
>      -L --local-install  Install packages from local directory only
> 
>      The default is to both download and install packages, unless either
>      --download or --local-install is specified.
> 
> I think the descriptions for the `-D` and `-L` options are misleading,
> at least in combination with that final line, which is definitely wrong.
> As I understand it, the actual behaviour would be better described by
> something like the below:
> 
>      -D --download       Download packages from internet only, unless -L
>                          is also specified
>      -L --local-install  Install packages from local directory only,
>                          unless -D is also specified

One could just remove the word 'only'?

> 
>      If neither --download nor --local-install is specified, the default
>      is to repeat the same action as from the previous run.  If no
>      previous run can be found, the default is to perform both actions,
>      and both actions can be explicitly requested by specifying both
>      --download and --local-install.

Note that I tweaked the behaviour of this a bit in [1]

[1] 
https://cygwin.com/git/?p=cygwin-apps/setup.git;a=commit;h=147fc15d0222e050779b18a209991c258d85944f

I think that makes the current help text accurately describe 
non-interactive mode.

There are some cases in interactive mode which are obscure (e.g. '-M' 
without '-D' or '-L' gets you whatever mode you used last time without 
showing you what it was, but I'm not sure if that needs to be here.

> In particular, the fact that the two options currently say they will
> "only" do their action, and that the default is to perform both, lead me
> to believe (a) the options were mutually exclusive and one would
> presumably override the other, (b) this was probably a legacy from
> before setup.rc stored the previous action, and therefore (c) if I was
> running setup with `-q` or `-M`, there was no way to get the supposedly
> default "do both" behaviour; I'd instead need to go through the full
> GUI.
> 
> Having now seen how this setting is stored, I've realised I can just
> call setup with `-DL` and it'll perform both actions again.  But I think
> my assumption that "default" was supposed to mean "default always" not
> "default only on first run" wasn't *entirely* PEBCAK (even if it mostly
> was), so that help text would definitely benefit from being made a bit
> more explicit.
> 
> (I'm aware my suggestion above is decidedly wordy; it's not intended to
> be exactly what I think is required, only a first pass at clarifying the
> key details I think are missing.)

Perhaps the best thing would be to have something like 
'--mode={download, install, somebetterwordforboth}' and document '-D' 
and '-L' as short aliases for forms of that (which makes the modality 
clear).

Re: setup-*.exe --help default explanation re -D/-L options [Was: [ANNOUNCEMENT] Updated: setup (2.917)]

[Adam Dinwoodie]

On Tue, Feb 01, 2022 at 04:53:47PM +0000, Jon Turney wrote:
> On 31/01/2022 22:11, Adam Dinwoodie wrote:
> > On  Mon, 31 Jan 2022 12:56:13 -0700, Brian Inglis wrote:
> > > On 2022-01-31 08:46, Andrey Repin wrote:
> > > > Greetings, Jon Turney!
> > > > 
> > > > > Probably what's wanted is to remember the state of those checkboxes, if
> > > > > this isn't the first time setup has been run?
> > > > 
> > > > That's a feature silently longed for for a loong time. :) But this is such a
> > > > low priority, very few people actually mentioned it in the past years.
> > > 
> > > It could usefully be added similarly to last-action:
> > > 
> > > 	$ fgrep -A1 action /etc/setup/setup.rc
> > > 	last-action
> > > 		Download,Install
> > > 
> > > last-shortcut:
> > > 	Desktop|StartMenu|none,...
> > 
> > This reminded me of a bug report I've been meaning to properly
> > characterise and report for a while, and also pointed me at a
> > workaround...
> > 
> > Currently, running `setup-*.exe --help` produces output that includes
> > the following:
> > 
> >      -D --download       Download packages from internet only
> >      -L --local-install  Install packages from local directory only
> > 
> >      The default is to both download and install packages, unless either
> >      --download or --local-install is specified.
> > 
> > I think the descriptions for the `-D` and `-L` options are misleading,
> > at least in combination with that final line, which is definitely wrong.
> > As I understand it, the actual behaviour would be better described by
> > something like the below:
> > 
> >      -D --download       Download packages from internet only, unless -L
> >                          is also specified
> >      -L --local-install  Install packages from local directory only,
> >                          unless -D is also specified
> 
> One could just remove the word 'only'?

...yes, that would in fact work, and is clear.

> >      If neither --download nor --local-install is specified, the default
> >      is to repeat the same action as from the previous run.  If no
> >      previous run can be found, the default is to perform both actions,
> >      and both actions can be explicitly requested by specifying both
> >      --download and --local-install.
> 
> Note that I tweaked the behaviour of this a bit in [1]
> 
> [1] https://cygwin.com/git/?p=cygwin-apps/setup.git;a=commit;h=147fc15d0222e050779b18a209991c258d85944f
> 
> I think that makes the current help text accurately describe non-interactive
> mode.
> 
> There are some cases in interactive mode which are obscure (e.g. '-M'
> without '-D' or '-L' gets you whatever mode you used last time without
> showing you what it was, but I'm not sure if that needs to be here.

Ah, okay.  I think I hit this with `-M` and assumed -- evidently
incorrectly -- that the same behaviour would exist for `-q`.  I agree
the current text is entirely accurate for the fully non-interactive
mode.

I think this caught me out because I frequently run with `-M` -- I don't
care about most of the options, but I do want to see what packages are
about to be updated -- and I almost never want to use the download-only
or install-only modes.  But I used `-L` as a one-off when I was
uninstalling and reinstalling a bunch of packages and didn't want to hit
the network every time, then forgot about it.  And it wasn't until I was
musing about the fact that I hadn't seen any package updates for a few
weeks when trying to do my regular updates with `-M` that I realised
what had happened...

Given all that, I think everything seems sensible except for the fact
that `-M` doesn't follow the same behaviour as `-q`.

> > In particular, the fact that the two options currently say they will
> > "only" do their action, and that the default is to perform both, lead me
> > to believe (a) the options were mutually exclusive and one would
> > presumably override the other, (b) this was probably a legacy from
> > before setup.rc stored the previous action, and therefore (c) if I was
> > running setup with `-q` or `-M`, there was no way to get the supposedly
> > default "do both" behaviour; I'd instead need to go through the full
> > GUI.
> > 
> > Having now seen how this setting is stored, I've realised I can just
> > call setup with `-DL` and it'll perform both actions again.  But I think
> > my assumption that "default" was supposed to mean "default always" not
> > "default only on first run" wasn't *entirely* PEBCAK (even if it mostly
> > was), so that help text would definitely benefit from being made a bit
> > more explicit.
> > 
> > (I'm aware my suggestion above is decidedly wordy; it's not intended to
> > be exactly what I think is required, only a first pass at clarifying the
> > key details I think are missing.)
> 
> Perhaps the best thing would be to have something like '--mode={download,
> install, somebetterwordforboth}' and document '-D' and '-L' as short aliases
> for forms of that (which makes the modality clear).

I definitely see no harm in that approach, and I agreed that'd make
things clearer again.  But, as above, I think the key thing from my
perspective would be for `-M` and `-q` to have consistent behaviour.

Re: setup-*.exe --help default explanation re -D/-L options [Was: [ANNOUNCEMENT] Updated: setup (2.917)]

[Andrey Repin]

Greetings, Jon Turney!

>>      If neither --download nor --local-install is specified, the default
>>      is to repeat the same action as from the previous run.  If no
>>      previous run can be found, the default is to perform both actions,
>>      and both actions can be explicitly requested by specifying both
>>      --download and --local-install.

> Note that I tweaked the behaviour of this a bit in [1]

> [1] 
> https://cygwin.com/git/?p=cygwin-apps/setup.git;a=commit;h=147fc15d0222e050779b18a209991c258d85944f

> I think that makes the current help text accurately describe 
> non-interactive mode.

> There are some cases in interactive mode which are obscure (e.g. '-M' 
> without '-D' or '-L' gets you whatever mode you used last time without 
> showing you what it was, but I'm not sure if that needs to be here.

>> In particular, the fact that the two options currently say they will
>> "only" do their action, and that the default is to perform both, lead me
>> to believe (a) the options were mutually exclusive and one would
>> presumably override the other, (b) this was probably a legacy from
>> before setup.rc stored the previous action, and therefore (c) if I was
>> running setup with `-q` or `-M`, there was no way to get the supposedly
>> default "do both" behaviour; I'd instead need to go through the full
>> GUI.
>> 
>> Having now seen how this setting is stored, I've realised I can just
>> call setup with `-DL` and it'll perform both actions again.  But I think
>> my assumption that "default" was supposed to mean "default always" not
>> "default only on first run" wasn't *entirely* PEBCAK (even if it mostly
>> was), so that help text would definitely benefit from being made a bit
>> more explicit.
>> 
>> (I'm aware my suggestion above is decidedly wordy; it's not intended to
>> be exactly what I think is required, only a first pass at clarifying the
>> key details I think are missing.)

> Perhaps the best thing would be to have something like 
> '--mode={download, install, somebetterwordforboth}' and document '-D' 
> and '-L' as short aliases for forms of that (which makes the modality 
> clear).

Definitely no. You'd have to invent a "better word" first and that would be
a whole new layer of explanation.
I'd vote for removal of -M for unattended operations instead. (I.e. make -q
and -M mutually exclusive.)
I mean, this is an unattended operation, right? You HAVE TO be explicit in
what results are expected from it.


-- 
With best regards,
Andrey Repin
Thursday, February 3, 2022 11:35:30

Sorry for my terrible english...