bug#22587: ‘guix edit’ & ‘M-x guix-edit' typo, rename, & mode change

[myglc2 <myglc2@gmail.com>]

Alex Kost <alezost@gmail.com> writes:

> myglc2 (2016-02-07 21:04 +0300) wrote:
>
>> From guix INFO:
>>
>> 6.2 Invoking ‘guix edit’
>> [...]
>> launches the program specified in the ‘VISUAL’ or in the ‘EDITOR’
>> environment variable to edit the recipe of GCC 4.8.4 and that of Vim."
>>
>> TYPO:
>>
>> "edit" (last line above) should be replaced with "view", "inspect", or
>> "examine".
>
> Just to mention - I like "edit" name :-)
>
>> RENAME:
>>
>> Calling these functions 'guix edit' and 'M-x guix-edit' implies that the
>> user will be able to modify the recipe, but this is not actually the
>> case. The functions should be given a more informative and accurate
>> name, such as: 'guix view', 'guix inspect', or 'guix examine'.
>
> Along with the package recipes that come with Guix, a user can also have
> his/her own packages (specified using GUIX_PACKAGE_PATH env var), and
> "guix edit my-super-package" opens a user's file with this package.  It
> is highly likely that this file is editable, so "guix edit" is a perfect
> name in this case I think.  IMO it's a user responsibility to understand
> what files can be edited and what cannot.
>

Sorry this is so long, but I think this is a useability issue that is
worth discussing more.

I understand your point-of-view, but I think it is much more
packager-centric than you should plan on your ultimate user base being.

If we think about the mix of guix users when it is more widely
successful, as I strongly believe it will be, a majority (80-90%) will
be "simply" managing and configuring their computer and/or user
account. They will NOT make packages.

If this is the case, the majority of people clicking on "guix edit" will
not understand "what files can be edited and what cannot." The very idea
that a recipe on their computer can make something they need will be a
radical leap. For these people, taking the fist look at a guix recipe
will be a step deeper into guix.

Such a user's first interaction might run along the lines of mine ...

- Hmm, I want to see an actual recipe.

- Oh wow, it says I can edit a recipe right here!

- Hmm, maybe I shouldn't because I don't want to break something.

- But they wouldn't call it "guix edit" if it wasn't OK to change stuff,
  right?

- OK, I'll give it a shot. I'll look at something I am familiar with ...

- 'guix edit screen'

- WOW look at that. Finds the recipe, opens an editor, COOL! 

- Hmm, I'mm make a little change, & see what happens.

    call-interactively: Buffer is read-only: #<buffer screen.scm> [18 times]

- OK, it is actually not that obvious or easy to get out of emacs at
  this point even for emacs users (try it). Now, pretend you know
  nothing about emacs. What would you be thinking and experiencing? A
  non-emacs user might be thinking -- "Why is it beeping! Did I do
  something wrong!  Is guix broken! ARGH! Let me out of this thing!"  --
  So I expect we have lost the emacs non-user right here, but me, I
  continued along ...

- Oh yeah, its read-only. No problem, I'll do ‘C-x C-q’

- Now, change save it ...

    Saving file /gnu/store/24mbii9wjlyzfzsqwfmcvz6vz2fv5n6g-guix-0.9.0.c3f29bc/share/guile/site/2.0/gnu/packages/screen.scm...
    Cannot write backup file; backing up in ~/.emacs.d/%backup%~
    Error: (file-error "Setting ACL" "read-only file system"
    "/gnu/store/24mbii9wjlyzfzsqwfmcvz6vz2fv5n6g-guix-0.9.0.c3f29bc/share/guile/site/2.
    Auto-saving...
    Auto-saving screen.scm: Opening output file: read-only file system,
    /gnu/store/24mbii9wjlyzfzsqwfmcvz6vz2fv5n6g-guix-0.9.0.c3f29bc/share/guile/site/2.0/gnu/packages/#screen.scm#
    Quit
    Auto-saving...
    Auto-saving screen.scm: Opening output file: read-only file system,
    /gnu/store/24mbii9wjlyzfzsqwfmcvz6vz2fv5n6g-guix-0.9.0.c3f29bc/share/guile/site/2.0/gnu/packages/#screen.scm#
    Quit

- ARGH! I have no idea where else I should save this. Let me out of here
  'C-g C-g C-g C-g C-g'!!

- WHEW, that was unpleasant!

- I must not be getting some big concept, I have to study the doc more.

So, I guess I am just saying...

Why point a new user taking their first look at a guix recipe down this
alley?

Can't we find a more user-friendly way to show them their first real
recipe?

> But I agree that this may be confusing, so maybe we should clarify the
> manual to explain in (info "(guix) Invoking guix edit") that store files
> must not be edited.
>
>> MODE CHANGE:
>>
>> In emacs, read-only .scm files should be opened in view-mode.
>
> I don't agree.  For example, when you open "/etc/hosts" (or whatever)
> file in Emacs, you get a message:
>
>   Note: file is write protected
>
> which indicates that it is opened read-only, but view-mode is not used
> by default.  You can enable it manually if you wish.  The same thing
> happens with package files.

Yes, of course, Emacs is a chainsaw. That is what we love about it.

But I believe that, for the majority of your future guix users, you
should think in terms of providing some protective gear and training
wheels.

Then you can use 'C-u' or something similar to empower the experienced
user.