zsh-users
 help / color / mirror / code / Atom feed
* Most minimal configuration challenge
@ 2022-08-27  4:30 Felipe Contreras
  2022-08-27 16:10 ` Daniel Shahaf
  2022-09-02  1:36 ` Vincent Lefevre
  0 siblings, 2 replies; 40+ messages in thread
From: Felipe Contreras @ 2022-08-27  4:30 UTC (permalink / raw)
  To: Zsh Users

Hi,

Now and again I cleanup my entire configuration for various reasons.
By doing that multiple times I've figured out which options I really
need, which are nice to have, and which I don't want.

Sometimes I wonder if there's anybody who doesn't use some of these.
For example, my guess is 99.99% of all people use compinit.

If I was a newcomer to zsh I would probably need some of these as
well, especially compinit.

Anyway, here is the most minimal configuration I can live with:

  fpath=(~/.zsh $fpath)

  HISTFILE=~/.history
  HISTSIZE=10000
  SAVEHIST=50000

  autoload -U compinit && compinit

  autoload -U promptinit && promptinit
  prompt felipec

  setopt inc_append_history

  bindkey -e
  bindkey "\e[H" beginning-of-line
  bindkey "\e[F" end-of-line
  bindkey "\e[A" history-beginning-search-backward
  bindkey "\e[B" history-beginning-search-forward
  bindkey "\e[3~" delete-char

I need every single line.

Although I usually use a much bigger configuration, I'm able to live
with this minimal configuration for a while.

Does anybody have a similar list of options they absolutely can't live
without? How long can you live with such a minimal configuration?

Cheers.

-- 
Felipe Contreras


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

* Re: Most minimal configuration challenge
  2022-08-27  4:30 Most minimal configuration challenge Felipe Contreras
@ 2022-08-27 16:10 ` Daniel Shahaf
  2022-08-27 19:32   ` Vincent Bernat
  2022-08-28 18:57   ` Felipe Contreras
  2022-09-02  1:36 ` Vincent Lefevre
  1 sibling, 2 replies; 40+ messages in thread
From: Daniel Shahaf @ 2022-08-27 16:10 UTC (permalink / raw)
  To: zsh-users

Felipe Contreras wrote on Sat, 27 Aug 2022 04:30 +00:00:
> Does anybody have a similar list of options they absolutely can't live
> without?

Off the top of my head, there are:

- zsh-newuser-install
- some distros' default dotfiles
- zsh-guide, a dotfile generator, curated by Matthew
- zsh-sensible, example dotfiles, curated by me
- the various prompts shipping with zsh itself

And probably a few others that I don't remember off the top of my head.  Apologies to them.

We should probably collect all these links and put them in the FAQ or something.

My personal list also has two non-zsh settings: MANOPT=--no-hyphenation
and guicursor=a:blinkon0 ;-)


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

* Re: Most minimal configuration challenge
  2022-08-27 16:10 ` Daniel Shahaf
@ 2022-08-27 19:32   ` Vincent Bernat
  2022-08-27 20:04     ` Lawrence Velázquez
  2022-08-28 18:57   ` Felipe Contreras
  1 sibling, 1 reply; 40+ messages in thread
From: Vincent Bernat @ 2022-08-27 19:32 UTC (permalink / raw)
  To: zsh-users

On 2022-08-27 18:10, Daniel Shahaf wrote:
> - zsh-guide, a dotfile generator, curated by Matthew
> - zsh-sensible, example dotfiles, curated by me

I am unable to find both of them. Could you provide the URL for them?

Thanks!


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

* Re: Most minimal configuration challenge
  2022-08-27 19:32   ` Vincent Bernat
@ 2022-08-27 20:04     ` Lawrence Velázquez
  2022-08-27 23:53       ` Ray Andrews
  0 siblings, 1 reply; 40+ messages in thread
From: Lawrence Velázquez @ 2022-08-27 20:04 UTC (permalink / raw)
  To: Vincent Bernat; +Cc: zsh-users

On Sat, Aug 27, 2022, at 3:32 PM, Vincent Bernat wrote:
> On 2022-08-27 18:10, Daniel Shahaf wrote:
>> - zsh-guide, a dotfile generator, curated by Matthew
>> - zsh-sensible, example dotfiles, curated by me
>
> I am unable to find both of them. Could you provide the URL for them?

https://storage.googleapis.com/zsh-guide/index.html
https://github.com/phy1729/zsh-guide

https://gitlab.com/zsh-sensible/zsh-sensible/

-- 
vq


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

* Re: Most minimal configuration challenge
  2022-08-27 20:04     ` Lawrence Velázquez
@ 2022-08-27 23:53       ` Ray Andrews
  2022-08-28  7:53         ` zzapper
  2022-08-28 10:30         ` Daniel Shahaf
  0 siblings, 2 replies; 40+ messages in thread
From: Ray Andrews @ 2022-08-27 23:53 UTC (permalink / raw)
  To: zsh-users

On 2022-08-27 13:04, Lawrence Velázquez wrote:
> On Sat, Aug 27, 2022, at 3:32 PM, Vincent Bernat wrote:
>> On 2022-08-27 18:10, Daniel Shahaf wrote:
>>> - zsh-guide, a dotfile generator, curated by Matthew
It would have been sweet to have had that when I first got started. Come 
to that, it will still be fun to play with and see what it generates.  
Felipe is right that configuration help is conspicuous by its absence.  
Some actually useful default configurations, along with explanation, 
would sure be nice.   Mine is a trial and error sort of thing.  
Unfortunately, I tweek something and only realize months later that I 
broke something that only shows up in esoteric situations, like no 
completions on the night of the full moon.  The degree of control is 
astonishing, but one gets lost.
>>> - zsh-sensible, example dotfiles, curated by me
I can't see any document or overview or explanation at all.




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

* Re: Most minimal configuration challenge
  2022-08-27 23:53       ` Ray Andrews
@ 2022-08-28  7:53         ` zzapper
  2022-08-28 10:30         ` Daniel Shahaf
  1 sibling, 0 replies; 40+ messages in thread
From: zzapper @ 2022-08-28  7:53 UTC (permalink / raw)
  To: zsh-users


On 28/08/2022 00:53, Ray Andrews wrote:
>  Felipe is right that configuration help is conspicuous by its 
> absence. Some actually useful default configurations, along with 
> explanation, would sure be nice.   Mine is a trial and error sort of 
> thing.  Unfortunately, I tweek something and only realize months later 
> that I broke something that only shows up in esoteric situations, like 
> no completions on the night of the full moon.

did you try ?

setopt NightFullMoon

>
>


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

* Re: Most minimal configuration challenge
  2022-08-27 23:53       ` Ray Andrews
  2022-08-28  7:53         ` zzapper
@ 2022-08-28 10:30         ` Daniel Shahaf
  2022-08-28 13:59           ` Ray Andrews
  1 sibling, 1 reply; 40+ messages in thread
From: Daniel Shahaf @ 2022-08-28 10:30 UTC (permalink / raw)
  To: zsh-users

Ray Andrews wrote on Sat, 27 Aug 2022 23:53 +00:00:
> On 2022-08-27 13:04, Lawrence Velázquez wrote:
>> On Sat, Aug 27, 2022, at 3:32 PM, Vincent Bernat wrote:
>>> On 2022-08-27 18:10, Daniel Shahaf wrote:
>>>> - zsh-guide, a dotfile generator, curated by Matthew
> It would have been sweet to have had that when I first got started. Come 
> to that, it will still be fun to play with and see what it generates.  
> Felipe is right that configuration help is conspicuous by its absence.  
> Some actually useful default configurations, along with explanation, 
> would sure be nice.   Mine is a trial and error sort of thing.  
> Unfortunately, I tweek something and only realize months later that I 
> broke something that only shows up in esoteric situations,

Sounds like you need a test suite for your zshrc.

Or perhaps you would be better served by a /smaller/ zshrc, so fewer
things can go wrong in the first place.

>>>> - zsh-sensible, example dotfiles, curated by me
> I can't see any document or overview or explanation at all.

Thanks for the report.  Yes, I should add docs, but that's not at the
top of my list.  In the meantime, just open the zshrc in that directory
and see what's in it.  There is little else there.

Thanks again.

Daniel


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

* Re: Most minimal configuration challenge
  2022-08-28 10:30         ` Daniel Shahaf
@ 2022-08-28 13:59           ` Ray Andrews
  2022-08-28 18:29             ` Daniel Shahaf
  2022-08-28 18:58             ` Bart Schaefer
  0 siblings, 2 replies; 40+ messages in thread
From: Ray Andrews @ 2022-08-28 13:59 UTC (permalink / raw)
  To: zsh-users


> Sounds like you need a test suite for your zshrc.
Sometimes it's a guess what some change might do, one does not even know 
what to expect.
Particularly the 'completion' stuff is baffling.  Here's mine, it sorta 
works but I despair at
understanding the syntax:

(Mind, sagacious as always, IIRC, Bart explained that this stuff was 
written by some Polish genius who
then disappeared and left the mere mortals trying to figure out how to 
drive it or improve it but
committed to using it anyway because it was so awesomely powerful. Sorta 
like using Thor's Hammer to
drive nails.)

------------------------------------

# 
=============================================================================
# COMPLETIONS:

zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS}
zstyle ':completion:*' auto-description 'specify: %d'
zstyle ':completion:*' format 'Completing %d'
zstyle ':completion:*' list-prompt %SAt %p: Hit TAB 'for more', or the 
char to insert%s
zstyle ':completion:*' select-prompt %SScrolling active: current 
selection at %p%s

# allow approximate
# Original: zstyle ':completion:*' completer _complete _match _approximate

#{
# This will not complete:
# Sky\ above\ 49°30\'N\ 123°30\'W\ at\ Sun\ 2020\ Dec\ 20\ 20\ 26_files/
# ... it won't finish the " _files " part:
# As of 2021-02-08 it *will* complete but it takes three presses of TAB:
#zstyle ':completion:*' completer _files _expand _complete

# This completes on one press of TAB.
zstyle ':completion:*' completer _expand _complete _files
#}

#Tab completion should be case-insensitive.
# Original: zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'
zstyle ':completion:*' matcher-list '' 'm:{a-z}={A-Z}' 
'm:{a-zA-Z}={A-Za-z}' 'r:|[._-]=* r:|=* l:|=*'

zstyle ':completion:*' verbose true
zstyle ':completion:*:match:*' original only
zstyle ':completion:*:approximate:*' max-errors 1 numeric
zstyle ':completion:*:expand:*' tag-order all-expansions
# cd should not select parent dir:
zstyle ':completion:*:cd:*' ignore-parents parent pwd

# End of completions.

-----------------------------------------------------------

... the docs do everything but help you understand.

>
> Or perhaps you would be better served by a /smaller/ zshrc, so fewer
> things can go wrong in the first place.

Yeah, that gets back to the original point,  what do we really need?  
One should build up from the
basics one step at a time, while understanding exactly what one is 
doing.  If we had lots of beginners
it would be fun to have a sort of 'configuration club' where folks could 
share and compare.  But I'll never
forget my first efforts to get Linux working, CLI was bash of course and 
out of the box it comes with NOTHING,
not even command recall, not even a working backspace key -- DOS was 
sophisticated by comparison -- and
I almost quit.  Same with zsh -- out of the box it's stone-age naked.  
Why?  Give the beginner something
with basic functionality, like a backspace key.
>
> Thanks for the report.  Yes, I should add docs, but that's not at the
> top of my list.  In the meantime, just open the zshrc in that directory
> and see what's in it.  There is little else there.

Good, next time I'm in a shelling mood, I'll look forward to checking 
those out.  It is almost
always the case that resources are there, if only one can find them.



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

* Re: Most minimal configuration challenge
  2022-08-28 13:59           ` Ray Andrews
@ 2022-08-28 18:29             ` Daniel Shahaf
  2022-08-31  9:28               ` Vincent Lefevre
  2022-08-28 18:58             ` Bart Schaefer
  1 sibling, 1 reply; 40+ messages in thread
From: Daniel Shahaf @ 2022-08-28 18:29 UTC (permalink / raw)
  To: zsh-users

Ray Andrews wrote on Sun, 28 Aug 2022 13:59 +00:00:
>> Sounds like you need a test suite for your zshrc.
> Sometimes it's a guess what some change might do, one does not even
> know what to expect. Particularly the 'completion' stuff is baffling.
> Here's mine, it sorta works but I despair at understanding the syntax:

zstyle has been explained multiple times in the past so you might want
to look those up and ask about parts that are unclear to you.

In short, «zstyle ':foo:bar:*:baz' key v1 v2» translates as "When
library foo asks for the value of key in a situation of the form
bar:*:baz, tell it the answer is «v1 v2»".

> Give the beginner something with basic functionality, like a
> backspace key.

[Just quoting this so it isn't lost in the noise.]


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

* Re: Most minimal configuration challenge
  2022-08-27 16:10 ` Daniel Shahaf
  2022-08-27 19:32   ` Vincent Bernat
@ 2022-08-28 18:57   ` Felipe Contreras
  1 sibling, 0 replies; 40+ messages in thread
From: Felipe Contreras @ 2022-08-28 18:57 UTC (permalink / raw)
  To: Daniel Shahaf; +Cc: zsh-users

On Sat, Aug 27, 2022 at 11:11 AM Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
>
> Felipe Contreras wrote on Sat, 27 Aug 2022 04:30 +00:00:
> > Does anybody have a similar list of options they absolutely can't live
> > without?
>
> Off the top of my head, there are:
>
> - zsh-newuser-install
> - some distros' default dotfiles
> - zsh-guide, a dotfile generator, curated by Matthew
> - zsh-sensible, example dotfiles, curated by me
> - the various prompts shipping with zsh itself

Looking at them seems like the options that virtually everyone sets are:

  HISTFILE
  HISTSIZE
  SAVEHIST

  compinit
  bindkey -e

-- 
Felipe Contreras


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

* Re: Most minimal configuration challenge
  2022-08-28 13:59           ` Ray Andrews
  2022-08-28 18:29             ` Daniel Shahaf
@ 2022-08-28 18:58             ` Bart Schaefer
  2022-08-28 19:23               ` Felipe Contreras
  2022-08-28 19:35               ` Ray Andrews
  1 sibling, 2 replies; 40+ messages in thread
From: Bart Schaefer @ 2022-08-28 18:58 UTC (permalink / raw)
  To: Ray Andrews; +Cc: zsh-users

On Sun, Aug 28, 2022 at 6:59 AM Ray Andrews <rayandrews@eastlink.ca> wrote:
>
> Give the beginner something
> with basic functionality, like a backspace key.

Er, what?

Zsh by default has for years bound both ^? (del) and ^H (backspace) to
backward-delete-char.  What else are you expecting?

There is the complication that the keypad-delete key can send two or
more different multi-character sequences and some keyboards might
attach one of those to the key that is labeled backspace, and there's
really no way for the shell to know what it should do with that ...
but that's a historic problem with keyboards and terminal drivers, not
with the shell per se.


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

* Re: Most minimal configuration challenge
  2022-08-28 18:58             ` Bart Schaefer
@ 2022-08-28 19:23               ` Felipe Contreras
  2022-08-28 19:35               ` Ray Andrews
  1 sibling, 0 replies; 40+ messages in thread
From: Felipe Contreras @ 2022-08-28 19:23 UTC (permalink / raw)
  To: Bart Schaefer; +Cc: Ray Andrews, zsh-users

On Sun, Aug 28, 2022 at 2:00 PM Bart Schaefer <schaefer@brasslantern.com> wrote:
>
> On Sun, Aug 28, 2022 at 6:59 AM Ray Andrews <rayandrews@eastlink.ca> wrote:
> >
> > Give the beginner something
> > with basic functionality, like a backspace key.
>
> Er, what?
>
> Zsh by default has for years bound both ^? (del) and ^H (backspace) to
> backward-delete-char.  What else are you expecting?

This is what I always do:

  bindkey "\e[3~" delete-char

-- 
Felipe Contreras


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

* Re: Most minimal configuration challenge
  2022-08-28 18:58             ` Bart Schaefer
  2022-08-28 19:23               ` Felipe Contreras
@ 2022-08-28 19:35               ` Ray Andrews
  1 sibling, 0 replies; 40+ messages in thread
From: Ray Andrews @ 2022-08-28 19:35 UTC (permalink / raw)
  To: zsh-users

On 2022-08-28 11:58, Bart Schaefer wrote:
> On Sun, Aug 28, 2022 at 6:59 AM Ray Andrews <rayandrews@eastlink.ca> wrote:
>
> Er, what?
>
> Zsh by default has for years bound both ^? (del) and ^H (backspace) to
> backward-delete-char.  What else are you expecting?
Maybe that was just bash, I could be getting my wires crossed.  What 
remains is that
overwhelming sense of things being very unhelpful for the beginner. But 
I would say that
the default install of zsh should be friendlier.  Memory fades tho, it's 
many years ago.




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

* Re: Most minimal configuration challenge
  2022-08-28 18:29             ` Daniel Shahaf
@ 2022-08-31  9:28               ` Vincent Lefevre
  2022-08-31 14:17                 ` Ray Andrews
  2022-09-02  9:26                 ` Daniel Shahaf
  0 siblings, 2 replies; 40+ messages in thread
From: Vincent Lefevre @ 2022-08-31  9:28 UTC (permalink / raw)
  To: zsh-users

On 2022-08-28 18:29:27 +0000, Daniel Shahaf wrote:
> Ray Andrews wrote on Sun, 28 Aug 2022 13:59 +00:00:
> >> Sounds like you need a test suite for your zshrc.
> > Sometimes it's a guess what some change might do, one does not even
> > know what to expect. Particularly the 'completion' stuff is baffling.
> > Here's mine, it sorta works but I despair at understanding the syntax:
> 
> zstyle has been explained multiple times in the past so you might want
> to look those up and ask about parts that are unclear to you.
> 
> In short, «zstyle ':foo:bar:*:baz' key v1 v2» translates as "When
> library foo asks for the value of key in a situation of the form
> bar:*:baz, tell it the answer is «v1 v2»".

Perhaps there should be a zsh function that translates a zstyle line
to plain English. :-)

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)


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

* Re: Most minimal configuration challenge
  2022-08-31  9:28               ` Vincent Lefevre
@ 2022-08-31 14:17                 ` Ray Andrews
  2022-09-01 21:52                   ` Felipe Contreras
                                     ` (2 more replies)
  2022-09-02  9:26                 ` Daniel Shahaf
  1 sibling, 3 replies; 40+ messages in thread
From: Ray Andrews @ 2022-08-31 14:17 UTC (permalink / raw)
  To: zsh-users

On 2022-08-31 02:28, Vincent Lefevre wrote:

>> In short, «zstyle ':foo:bar:*:baz' key v1 v2» translates as "When
>> library foo asks for the value of key in a situation of the form
>> bar:*:baz, tell it the answer is «v1 v2»".
> Perhaps there should be a zsh function that translates a zstyle line
> to plain English. :-)
>
Yup.  Unfortunately we tend to think that experts are the ones who 
should write
documentation, but they are unqualified.  They write sentences that explain
what they already know back to themselves.  It's like learning Coptic 
from a book
written in Coptic.  Only people who have just now learned something can
explain it in a way that other people who want to learn it can relate to 
because
only the learner has the mind of a learner.  Experts have the mind of 
experts.
So the above no doubt makes perfect sense to the expert who wrote it and 
already
understands it, but is useless to me.  The whole world suffers from 
this, but
especially the computer world.




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

* Re: Most minimal configuration challenge
  2022-08-31 14:17                 ` Ray Andrews
@ 2022-09-01 21:52                   ` Felipe Contreras
  2022-09-02  1:41                     ` Lawrence Velázquez
  2022-09-02  1:26                   ` Lawrence Velázquez
  2022-09-02  9:53                   ` Daniel Shahaf
  2 siblings, 1 reply; 40+ messages in thread
From: Felipe Contreras @ 2022-09-01 21:52 UTC (permalink / raw)
  To: Ray Andrews; +Cc: zsh-users

On Wed, Aug 31, 2022 at 9:17 AM Ray Andrews <rayandrews@eastlink.ca> wrote:
>
> On 2022-08-31 02:28, Vincent Lefevre wrote:
>
> >> In short, «zstyle ':foo:bar:*:baz' key v1 v2» translates as "When
> >> library foo asks for the value of key in a situation of the form
> >> bar:*:baz, tell it the answer is «v1 v2»".
> > Perhaps there should be a zsh function that translates a zstyle line
> > to plain English. :-)
> >
> Yup.  Unfortunately we tend to think that experts are the ones who
> should write
> documentation, but they are unqualified.  They write sentences that explain
> what they already know back to themselves.  It's like learning Coptic
> from a book
> written in Coptic.  Only people who have just now learned something can
> explain it in a way that other people who want to learn it can relate to
> because
> only the learner has the mind of a learner.  Experts have the mind of
> experts.
> So the above no doubt makes perfect sense to the expert who wrote it and
> already
> understands it, but is useless to me.  The whole world suffers from
> this, but
> especially the computer world.

This is very true, in fact this bias has a name: "the curse of
knowledge" [1], and it's something every writer should keep in mind.

Unfortunately the only antidote is for zsh newcomers to become more
active in the development of zsh which seems to be quite balkanized
between the old guard (the actual developers of zsh), and the new kids
(oh-my-zsh, Powershell 10K, etc). This bridge should be reduced.

Also, the zsh site using a style of 1990 doesn't particularly help.

Cheers.

[1] https://en.wikipedia.org/wiki/Curse_of_knowledge

-- 
Felipe Contreras


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

* Re: Most minimal configuration challenge
  2022-08-31 14:17                 ` Ray Andrews
  2022-09-01 21:52                   ` Felipe Contreras
@ 2022-09-02  1:26                   ` Lawrence Velázquez
  2022-09-02  1:49                     ` Felipe Contreras
  2022-09-02 13:32                     ` Ray Andrews
  2022-09-02  9:53                   ` Daniel Shahaf
  2 siblings, 2 replies; 40+ messages in thread
From: Lawrence Velázquez @ 2022-09-02  1:26 UTC (permalink / raw)
  To: Ray Andrews; +Cc: zsh-users

On Wed, Aug 31, 2022, at 10:17 AM, Ray Andrews wrote:
> On 2022-08-31 02:28, Vincent Lefevre wrote:
>
>>> In short, «zstyle ':foo:bar:*:baz' key v1 v2» translates as "When
>>> library foo asks for the value of key in a situation of the form
>>> bar:*:baz, tell it the answer is «v1 v2»".
>> Perhaps there should be a zsh function that translates a zstyle line
>> to plain English. :-)
>>
> Yup.  Unfortunately we tend to think that experts are the ones who 
> should write
> documentation, but they are unqualified.  They write sentences that explain
> what they already know back to themselves.  It's like learning Coptic 
> from a book
> written in Coptic.

This is common enough, but...

> Only people who have just now learned something can
> explain it in a way that other people who want to learn it can relate to 
> because
> only the learner has the mind of a learner.

Someone who has "just now learned something" has the shallowest
possible understanding of it and can only perpetuate that shallow
understanding.  That is certainly all that is necessary in some
contexts, but it is not true education; it is sharing tips and
tricks.

The ideal educator pairs a deep knowledge of their field with an
equally deep sensitivity for the needs of their students.  It is
difficult to acquire just one of these things, let alone both, which
is why great educators are few and far between.

> Experts have the mind of 
> experts.
> So the above no doubt makes perfect sense to the expert who wrote it and 
> already
> understands it, but is useless to me.

I think this is pretty harsh toward Daniel.  I have no doubt he
could have written a more verbose and comprehensive explanation in
a paragraph or two, but I wouldn't have been surprised if you'd
objected to its wordiness.

-- 
vq


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

* Re: Most minimal configuration challenge
  2022-08-27  4:30 Most minimal configuration challenge Felipe Contreras
  2022-08-27 16:10 ` Daniel Shahaf
@ 2022-09-02  1:36 ` Vincent Lefevre
  1 sibling, 0 replies; 40+ messages in thread
From: Vincent Lefevre @ 2022-09-02  1:36 UTC (permalink / raw)
  To: zsh-users

Concerning the bindings, I find the following for [Tab] very useful.
This is inspired by

  https://www.zsh.org/mla/users/2004/msg00743.html

(zsh-users 7732).

history-search-or-expand-or-complete()
{
  if [[ -z "$BUFFER" && -z "$PREBUFFER" ]] then
    zle history-incremental-search-backward "$@"
  else
    zle expand-or-complete "$@"
  fi
}
zle -N history-search-or-expand-or-complete
bindkey '\t' history-search-or-expand-or-complete

A [Tab] character at the beginning of the buffer is useless,
while a backward history search is common, and [Tab] is easier
to type than Ctrl-R.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)


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

* Re: Most minimal configuration challenge
  2022-09-01 21:52                   ` Felipe Contreras
@ 2022-09-02  1:41                     ` Lawrence Velázquez
  0 siblings, 0 replies; 40+ messages in thread
From: Lawrence Velázquez @ 2022-09-02  1:41 UTC (permalink / raw)
  To: Felipe Contreras, Ray Andrews; +Cc: zsh-users

On Thu, Sep 1, 2022, at 5:52 PM, Felipe Contreras wrote:
> Unfortunately the only antidote is for zsh newcomers to become more
> active in the development of zsh which seems to be quite balkanized
> between the old guard (the actual developers of zsh), and the new kids
> (oh-my-zsh, Powershell 10K, etc). This bridge should be reduced.

Roman (the primary author of Powerlevel10k) and Sebastian Gniazdowski
(a major contributor to zinit) are regulars here.

I think omz contributors have reported bugs before.

-- 
vq


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

* Re: Most minimal configuration challenge
  2022-09-02  1:26                   ` Lawrence Velázquez
@ 2022-09-02  1:49                     ` Felipe Contreras
  2022-09-02  5:40                       ` Lawrence Velázquez
                                         ` (3 more replies)
  2022-09-02 13:32                     ` Ray Andrews
  1 sibling, 4 replies; 40+ messages in thread
From: Felipe Contreras @ 2022-09-02  1:49 UTC (permalink / raw)
  To: Lawrence Velázquez; +Cc: Ray Andrews, zsh-users

On Thu, Sep 1, 2022 at 8:27 PM Lawrence Velázquez <larryv@zsh.org> wrote:
> On Wed, Aug 31, 2022, at 10:17 AM, Ray Andrews wrote:
> > On 2022-08-31 02:28, Vincent Lefevre wrote:

> >>> In short, «zstyle ':foo:bar:*:baz' key v1 v2» translates as "When
> >>> library foo asks for the value of key in a situation of the form
> >>> bar:*:baz, tell it the answer is «v1 v2»".
> >> Perhaps there should be a zsh function that translates a zstyle line
> >> to plain English. :-)
> >>
> > Yup.  Unfortunately we tend to think that experts are the ones who
> > should write
> > documentation, but they are unqualified.  They write sentences that explain
> > what they already know back to themselves.  It's like learning Coptic
> > from a book
> > written in Coptic.
>
> This is common enough, but...
>
> > Only people who have just now learned something can
> > explain it in a way that other people who want to learn it can relate to
> > because
> > only the learner has the mind of a learner.
>
> Someone who has "just now learned something" has the shallowest
> possible understanding of it and can only perpetuate that shallow
> understanding.

That is not quite true. Yes, the vast majority of newcomers have the
shallowest understanding of zsh, but not necessarily of shells,
programming languages, configuration systems, or any number of things
that might be relevant.

This would be like saying a programmer entering the world of economics
only has the shallowest of understandings and therefore cannot provide
anything of value. Yeah, maybe not provide any value of economic
theory, but he can provide value in data processing... which is what
shapes economic theories. Or that a patent clerk cannot provide value
in physics... Albert Einstein would beg to disagree.

Value can come from unexpected places.

> That is certainly all that is necessary in some
> contexts, but it is not true education; it is sharing tips and
> tricks.
>
> The ideal educator pairs a deep knowledge of their field with an
> equally deep sensitivity for the needs of their students.  It is
> difficult to acquire just one of these things, let alone both, which
> is why great educators are few and far between.

But the true value of educators comes from the fact that they are in
the frontlines of knowledge acquisition. The main reason they know
what explanations work better is constant feedback from students.

The clueless students are an essential part of the equation.

> > Experts have the mind of
> > experts.
> > So the above no doubt makes perfect sense to the expert who wrote it and
> > already
> > understands it, but is useless to me.
>
> I think this is pretty harsh toward Daniel.  I have no doubt he
> could have written a more verbose and comprehensive explanation in
> a paragraph or two, but I wouldn't have been surprised if you'd
> objected to its wordiness.

It's not either or. I constantly try to put myself in the shoes of
newcomers, and sometimes an explanation I give is deemed not clear
enough. Does that mean I failed and I'm stupid? No, it's just
feedback, I can try another one.

People who are not constantly being subject to criticism often think
it's something negative, but it isn't, it's just an opportunity to try
something better.

Ultimately the people who should judge prose meant for newcomers, are
newcomers. If they say it isn't clear, then it isn't clear.

To think otherwise would be like a comic saying his joke is great
because all his fellow comics agree, if it bombs with audiences it
just means the audiences don't understand comedy. No, the whole point
is that audiences like it, if they don't, then it's not a great joke.

-- 
Felipe Contreras


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

* Re: Most minimal configuration challenge
  2022-09-02  1:49                     ` Felipe Contreras
@ 2022-09-02  5:40                       ` Lawrence Velázquez
  2022-09-02  7:38                         ` Felipe Contreras
  2022-09-02 10:36                       ` Daniel Shahaf
                                         ` (2 subsequent siblings)
  3 siblings, 1 reply; 40+ messages in thread
From: Lawrence Velázquez @ 2022-09-02  5:40 UTC (permalink / raw)
  To: Felipe Contreras; +Cc: Ray Andrews, zsh-users

On Thu, Sep 1, 2022, at 9:49 PM, Felipe Contreras wrote:
> On Thu, Sep 1, 2022 at 8:27 PM Lawrence Velázquez <larryv@zsh.org> wrote:
>> On Wed, Aug 31, 2022, at 10:17 AM, Ray Andrews wrote:
>> > Only people who have just now learned something can
>> > explain it in a way that other people who want to learn it can relate to
>> > because
>> > only the learner has the mind of a learner.
>>
>> Someone who has "just now learned something" has the shallowest
>> possible understanding of it and can only perpetuate that shallow
>> understanding.
>
> That is not quite true. Yes, the vast majority of newcomers have the
> shallowest understanding of zsh, but not necessarily of shells,
> programming languages, configuration systems, or any number of things
> that might be relevant.
>
> This would be like saying a programmer entering the world of economics
> only has the shallowest of understandings and therefore cannot provide
> anything of value.

You are misrepresenting what I said.

> Yeah, maybe not provide any value of economic
> theory, but he can provide value in data processing...

Absolutely, but one would not say this programmer, who has just
learned some basic economics for their job, is the only one who can
write good Econ 101 textbooks.

> Or that a patent clerk cannot provide value
> in physics... Albert Einstein would beg to disagree.

This is not a serious example.  Come on.

> But the true value of educators comes from the fact that they are in
> the frontlines of knowledge acquisition. The main reason they know
> what explanations work better is constant feedback from students.
>
> The clueless students are an essential part of the equation.

I did not say otherwise.

> Ultimately the people who should judge prose meant for newcomers, are
> newcomers. If they say it isn't clear, then it isn't clear.

Obviously.

-- 
vq


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

* Re: Most minimal configuration challenge
  2022-09-02  5:40                       ` Lawrence Velázquez
@ 2022-09-02  7:38                         ` Felipe Contreras
  0 siblings, 0 replies; 40+ messages in thread
From: Felipe Contreras @ 2022-09-02  7:38 UTC (permalink / raw)
  To: Lawrence Velázquez; +Cc: Ray Andrews, zsh-users

On Fri, Sep 2, 2022 at 12:41 AM Lawrence Velázquez <larryv@zsh.org> wrote:
> On Thu, Sep 1, 2022, at 9:49 PM, Felipe Contreras wrote:
> > On Thu, Sep 1, 2022 at 8:27 PM Lawrence Velázquez <larryv@zsh.org> wrote:
> >> On Wed, Aug 31, 2022, at 10:17 AM, Ray Andrews wrote:

> >> > Only people who have just now learned something can
> >> > explain it in a way that other people who want to learn it can relate to
> >> > because
> >> > only the learner has the mind of a learner.
> >>
> >> Someone who has "just now learned something" has the shallowest
> >> possible understanding of it and can only perpetuate that shallow
> >> understanding.
> >
> > That is not quite true. Yes, the vast majority of newcomers have the
> > shallowest understanding of zsh, but not necessarily of shells,
> > programming languages, configuration systems, or any number of things
> > that might be relevant.
> >
> > This would be like saying a programmer entering the world of economics
> > only has the shallowest of understandings and therefore cannot provide
> > anything of value.
>
> You are misrepresenting what I said.

No, I'm pretty certain you said newcomers "can only perpetuate that
shallow understanding", but that's not true, that's not the *only*
thing they can do. Sometimes they can come up with a new
interpretation, or maybe an analogy nobody had thought of before.
Sometimes they can even make suggestions to change things so this
understanding is simplified, or perhaps even unnecessary.

I don't think you meant to say that, but that's what you literally said.

> > Ultimately the people who should judge prose meant for newcomers, are
> > newcomers. If they say it isn't clear, then it isn't clear.
>
> Obviously.

Then we are in agreement. A zsh veteran expert saying "this should be
good for all newcomers" is not proof that it's truly good for all
newcomers, the feedback from newcomers is still important.

Cheers.

-- 
Felipe Contreras


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

* Re: Most minimal configuration challenge
  2022-08-31  9:28               ` Vincent Lefevre
  2022-08-31 14:17                 ` Ray Andrews
@ 2022-09-02  9:26                 ` Daniel Shahaf
  2022-09-02 14:44                   ` Vincent Lefevre
  1 sibling, 1 reply; 40+ messages in thread
From: Daniel Shahaf @ 2022-09-02  9:26 UTC (permalink / raw)
  To: zsh-users

Vincent Lefevre wrote on Wed, Aug 31, 2022 at 11:28:31 +0200:
> On 2022-08-28 18:29:27 +0000, Daniel Shahaf wrote:
> > Ray Andrews wrote on Sun, 28 Aug 2022 13:59 +00:00:
> > >> Sounds like you need a test suite for your zshrc.
> > > Sometimes it's a guess what some change might do, one does not even
> > > know what to expect. Particularly the 'completion' stuff is baffling.
> > > Here's mine, it sorta works but I despair at understanding the syntax:
> > 
> > zstyle has been explained multiple times in the past so you might want
> > to look those up and ask about parts that are unclear to you.
> > 
> > In short, «zstyle ':foo:bar:*:baz' key v1 v2» translates as "When
> > library foo asks for the value of key in a situation of the form
> > bar:*:baz, tell it the answer is «v1 v2»".
> 
> Perhaps there should be a zsh function that translates a zstyle line
> to plain English. :-)

What do you have in mind, exactly?  It'd be pretty easy to write
something that, say, runs «zstyle -L» and applies the sh-to-English
mechanical transformation I did above.  That's just a compiler…


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

* Re: Most minimal configuration challenge
  2022-08-31 14:17                 ` Ray Andrews
  2022-09-01 21:52                   ` Felipe Contreras
  2022-09-02  1:26                   ` Lawrence Velázquez
@ 2022-09-02  9:53                   ` Daniel Shahaf
  2 siblings, 0 replies; 40+ messages in thread
From: Daniel Shahaf @ 2022-09-02  9:53 UTC (permalink / raw)
  To: Ray Andrews; +Cc: zsh-users

Ray Andrews wrote on Wed, Aug 31, 2022 at 07:17:32 -0700:
> On 2022-08-31 02:28, Vincent Lefevre wrote:
> 
> > > In short, «zstyle ':foo:bar:*:baz' key v1 v2» translates as "When
> > > library foo asks for the value of key in a situation of the form
> > > bar:*:baz, tell it the answer is «v1 v2»".
> So the above no doubt makes perfect sense to the expert who wrote it
> and already understands it, but is useless to me.

Of course it is.  It's just a summary of the answer, not the actual
answer itself.  If you want /that/, then either refer to the part of my
post which you trimmed:

> > > zstyle has been explained multiple times in the past so you might want
> > > to look those up and ask about parts that are unclear to you.

Or pay someone for personalized support.

Daniel


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

* Re: Most minimal configuration challenge
  2022-09-02  1:49                     ` Felipe Contreras
  2022-09-02  5:40                       ` Lawrence Velázquez
@ 2022-09-02 10:36                       ` Daniel Shahaf
  2022-09-02 14:26                         ` Ray Andrews
  2022-09-02 10:39                       ` [PATCH] zstyle: Correct and expand docs (was: Re: Most minimal configuration challenge) Daniel Shahaf
  2022-09-02 13:55                       ` Most minimal configuration challenge Ray Andrews
  3 siblings, 1 reply; 40+ messages in thread
From: Daniel Shahaf @ 2022-09-02 10:36 UTC (permalink / raw)
  To: zsh-users

Felipe Contreras wrote on Thu, Sep 01, 2022 at 20:49:52 -0500:
> On Thu, Sep 1, 2022 at 8:27 PM Lawrence Velázquez <larryv@zsh.org> wrote:
> > On Wed, Aug 31, 2022, at 10:17 AM, Ray Andrews wrote:
> > > Experts have the mind of experts.  So the above no doubt makes
> > > perfect sense to the expert who wrote it and already understands
> > > it, but is useless to me.
> >
> > I think this is pretty harsh toward Daniel.  I have no doubt he
> > could have written a more verbose and comprehensive explanation in
> > a paragraph or two, but I wouldn't have been surprised if you'd
> > objected to its wordiness.
> 

There's no easy way to explain zstyle in a sentence since it has so many
moving parts (keys, values, contexts, context patterns).

> It's not either or. I constantly try to put myself in the shoes of
> newcomers, and sometimes an explanation I give is deemed not clear
> enough. Does that mean I failed and I'm stupid? No, it's just
> feedback, I can try another one.
> 
> People who are not constantly being subject to criticism often think
> it's something negative, but it isn't, it's just an opportunity to try
> something better.
> 
> Ultimately the people who should judge prose meant for newcomers, are
> newcomers. If they say it isn't clear, then it isn't clear.

It wasn't meant to be clear.  It was meant to be a summary of the
answer, so that:

1. Anyone who RTFM'd following my post would know whether they were
reading the right part of the docs.

2. Anyone who /already knew/ the topic would know they could skip that
pointer to the docs.

3. Readers (including lurkers) would get a fishing rod rather than a fish.


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

* [PATCH] zstyle: Correct and expand docs (was: Re: Most minimal configuration challenge)
  2022-09-02  1:49                     ` Felipe Contreras
  2022-09-02  5:40                       ` Lawrence Velázquez
  2022-09-02 10:36                       ` Daniel Shahaf
@ 2022-09-02 10:39                       ` Daniel Shahaf
  2022-09-02 15:05                         ` Bart Schaefer
  2022-09-02 13:55                       ` Most minimal configuration challenge Ray Andrews
  3 siblings, 1 reply; 40+ messages in thread
From: Daniel Shahaf @ 2022-09-02 10:39 UTC (permalink / raw)
  To: zsh-users

I noticed the contradictory claims about equally v. more specific on
lines 55-56 of mod_zutil.yo, and along the way fixed some preëxisting
issues.

Daniel


diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index 3cf9e5028..ef0ee64a3 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -17,15 +17,16 @@ item(tt(zstyle -m) var(context) var(style) var(pattern))(
 This builtin command is used to define and lookup styles.  Styles are
 pairs of names and values, where the values consist of any number of
 strings.  They are stored together with patterns and lookup is done by
-giving a string, called the `em(context)', which is matched against the
-patterns.  The definition stored for the most specific pattern that matches
-will be returned.
+giving a string, called the `em(context)', which patterns are matched against.
+The definition stored for that style name the most specific pattern that
+matches the context will be returned.
 
+COMMENT(See the "Calculate the weight" common in Src/Modules/zutil.c)
 A pattern is considered to be more specific
 than another if it contains more components (substrings separated by
 colons) or if the patterns for the components are more specific, where 
 simple strings are considered to be more specific than patterns and
-complex patterns are considered to be more specific than the pattern
+any pattern other than `tt(*)' is considered to be more specific than the pattern
 `tt(*)'.  A `tt(*)' in the pattern will match zero or more characters
 in the context; colons are not treated specially in this regard.
 If two patterns are equally specific, the tie is broken in favour of
@@ -51,8 +52,19 @@ in order to retrieve your preference into the scalar variable tt($REPLY).
 On Sundays tt($REPLY) would be set to `tt(snow)'; in Europe it would be set
 to `tt(rain)'; and on Sundays in Europe it would be set to `tt(snow)' again,
 because the patterns `tt(:weather:europe:*)' and `tt(:weather:*:Sunday:*)' both
-match the var(context) argument to tt(zstyle -s), are equally specific, and the
-latter is more specific (because it has more colon-separated components).
+match the var(context) argument to tt(zstyle -s) and the
+latter pattern has more colon-separated components, and therefore is more
+specific.  A definition such as
+
+example(zstyle ':weather:e*:Sunday:*gib*' preferred-precipitation cloudless-skies)
+
+would be more specific still, since it has the same number of colon-separated
+components but the components are more specific; and the definition
+
+example(zstyle ':weather:europe:Sunday:waxing-gibbous' meteorites)
+
+would be more specific than any other definition that might also match,
+since none of its colon-separated components is a pattern.
 
 em(Usage)
 


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

* Re: Most minimal configuration challenge
  2022-09-02  1:26                   ` Lawrence Velázquez
  2022-09-02  1:49                     ` Felipe Contreras
@ 2022-09-02 13:32                     ` Ray Andrews
  2022-09-04  7:28                       ` Daniel Shahaf
  1 sibling, 1 reply; 40+ messages in thread
From: Ray Andrews @ 2022-09-02 13:32 UTC (permalink / raw)
  To: zsh-users

On 2022-09-01 18:26, Lawrence Velázquez wrote:
>
> Someone who has "just now learned something" has the shallowest
> possible understanding of it and can only perpetuate that shallow
> understanding.  That is certainly all that is necessary in some
> contexts, but it is not true education; it is sharing tips and
> tricks.
Of course.  But when  you just want to get something done and do not want
to be overwhelmed with all possible knowledge, the former is better.  
It's no
replacement for deep study, it's purpose it different.  When I first 
tried to
build zsh I was overwhelmed by documentation that covered all possible
worlds.  When I finally got it done -- with much help -- I wrote out what
worked for me in a half a page and even Peter said it was good.  It could
serve as an anecdote: 'try this'.  Two or three anecdotes and probably 90%
of situations would be covered and almost painlessly.  If you really need to
be inducted into the deeper mysteries then that's different, you will be
expecting to suffer and you will suffer.
>
> The ideal educator pairs a deep knowledge of their field with an
> equally deep sensitivity for the needs of their students.  It is
> difficult to acquire just one of these things, let alone both, which
> is why great educators are few and far between.

Too true.
>
> I think this is pretty harsh toward Daniel.
I wasn't thinking of Daniel.  I'm making a generalization. Mind ...

> I have no doubt he
> could have written a more verbose and comprehensive explanation in
> a paragraph or two, but I wouldn't have been surprised if you'd
> objected to its wordiness.

Nope, a paragraph or two would be just what I'd look for. Actually, as 
he explained it
in a single sentence, that would be just fine.  And I'm not throwing 
stones either --
I'm every bit as bad documenting my own code.  I, too, would need 
someone else
to read it, and document it cuz I am disabled by already understanding it.






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

* Re: Most minimal configuration challenge
  2022-09-02  1:49                     ` Felipe Contreras
                                         ` (2 preceding siblings ...)
  2022-09-02 10:39                       ` [PATCH] zstyle: Correct and expand docs (was: Re: Most minimal configuration challenge) Daniel Shahaf
@ 2022-09-02 13:55                       ` Ray Andrews
  2022-09-04  7:21                         ` Daniel Shahaf
  3 siblings, 1 reply; 40+ messages in thread
From: Ray Andrews @ 2022-09-02 13:55 UTC (permalink / raw)
  To: zsh-users

On 2022-09-01 18:49, Felipe Contreras wrote:
>
> The clueless students are an essential part of the equation.
When I'm critiquing a document I deliberately become dumb.  Even if I
get it, if I think it could have been explained better I'll act as tho I 
don't
get it.

>
> People who are not constantly being subject to criticism often think
> it's something negative, but it isn't, it's just an opportunity to try
> something better.
In the computer world some expert writes the doc and you take it or you 
leave it.
In the  world of writers, they get together in groups and *savage* each 
other's
work, they tear each other to shreds if they think something is not written
perfectly.  Then a style editor rips thru it.  Then a copy editor rips 
it to bits
one more time.  Then the publisher cuts out half of it and makes you rewrite
the other half.
>
> Ultimately the people who should judge prose meant for newcomers, are
> newcomers. If they say it isn't clear, then it isn't clear.

That's exactly it.



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

* Re: Most minimal configuration challenge
  2022-09-02 10:36                       ` Daniel Shahaf
@ 2022-09-02 14:26                         ` Ray Andrews
  2022-09-04  7:13                           ` Daniel Shahaf
  0 siblings, 1 reply; 40+ messages in thread
From: Ray Andrews @ 2022-09-02 14:26 UTC (permalink / raw)
  To: zsh-users

On 2022-09-02 03:36, Daniel Shahaf wrote:

Ironically this sentence would be the perfect start to some doc about
zstyle that was actually helpful:

> There's no easy way to explain zstyle in a sentence since it has so many
> moving parts (keys, values, contexts, context patterns).

... start off by letting the reader know that zstyle is the most complex
thing in the universe and even John von Neumann wouldn't get it
right away.

>
> 3. Readers (including lurkers) would get a fishing rod rather than a fish.
>
But sometimes what you want is a fish.  That's the perfect analogy tho.  
Sometimes I
want a fishing rod, sometimes I want a fish.  When it comes to 
documentation, they
are very different things.



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

* Re: Most minimal configuration challenge
  2022-09-02  9:26                 ` Daniel Shahaf
@ 2022-09-02 14:44                   ` Vincent Lefevre
  2022-09-04  6:42                     ` Daniel Shahaf
  0 siblings, 1 reply; 40+ messages in thread
From: Vincent Lefevre @ 2022-09-02 14:44 UTC (permalink / raw)
  To: zsh-users

On 2022-09-02 09:26:40 +0000, Daniel Shahaf wrote:
> Vincent Lefevre wrote on Wed, Aug 31, 2022 at 11:28:31 +0200:
> > On 2022-08-28 18:29:27 +0000, Daniel Shahaf wrote:
> > > zstyle has been explained multiple times in the past so you might want
> > > to look those up and ask about parts that are unclear to you.
> > > 
> > > In short, «zstyle ':foo:bar:*:baz' key v1 v2» translates as "When
> > > library foo asks for the value of key in a situation of the form
> > > bar:*:baz, tell it the answer is «v1 v2»".
> > 
> > Perhaps there should be a zsh function that translates a zstyle line
> > to plain English. :-)
> 
> What do you have in mind, exactly?  It'd be pretty easy to write
> something that, say, runs «zstyle -L» and applies the sh-to-English
> mechanical transformation I did above.  That's just a compiler…

The above is not very helpful for the end user.

For instance, "zstyle -L" gives in particular:

  zstyle :urlglobber url-local-schema ftp file
  zstyle ':url-quote-magic:*' url-metas '*?[]^(|)~#{}='

but I can't find any explanation about why it should be ":urlglobber"
and not something else. The man page looks similar for urlglobber and
url-quote-magic, though they look different above.

In the zshmodules(1) man page:

  For  example,  a  fictional  `weather' plugin might state in its
  documentation that it looks up the preferred-precipitation style
  under the `:weather:continent:day-of-the-week:phase-of-the-moon'
  context.  According to this, you might set the following in your
  zshrc:

    zstyle ':weather:europe:*' preferred-precipitation rain
    zstyle ':weather:*:Sunday:*' preferred-precipitation snow

So I would expect the translator to mention "continent",
"day-of-the-week" and "phase-of-the-moon" in its output.

Moreover, for ':completion:*', it is difficult to find the associated
documentation, because if one searches for "completion" in the zshall
man page, one gets too many matches.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)


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

* Re: [PATCH] zstyle: Correct and expand docs (was: Re: Most minimal configuration challenge)
  2022-09-02 10:39                       ` [PATCH] zstyle: Correct and expand docs (was: Re: Most minimal configuration challenge) Daniel Shahaf
@ 2022-09-02 15:05                         ` Bart Schaefer
  2022-09-04  6:51                           ` Daniel Shahaf
  0 siblings, 1 reply; 40+ messages in thread
From: Bart Schaefer @ 2022-09-02 15:05 UTC (permalink / raw)
  To: Daniel Shahaf; +Cc: zsh-users

On Fri, Sep 2, 2022 at 3:40 AM Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
>
> +The definition stored for that style name the most specific pattern that

Missing a word?


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

* Re: Most minimal configuration challenge
  2022-09-02 14:44                   ` Vincent Lefevre
@ 2022-09-04  6:42                     ` Daniel Shahaf
  2022-09-05  9:47                       ` Vincent Lefevre
  0 siblings, 1 reply; 40+ messages in thread
From: Daniel Shahaf @ 2022-09-04  6:42 UTC (permalink / raw)
  To: zsh-users

Vincent Lefevre wrote on Fri, Sep 02, 2022 at 16:44:34 +0200:
> On 2022-09-02 09:26:40 +0000, Daniel Shahaf wrote:
> > Vincent Lefevre wrote on Wed, Aug 31, 2022 at 11:28:31 +0200:
> > > On 2022-08-28 18:29:27 +0000, Daniel Shahaf wrote:
> > > > zstyle has been explained multiple times in the past so you might want
> > > > to look those up and ask about parts that are unclear to you.
> > > > 
> > > > In short, «zstyle ':foo:bar:*:baz' key v1 v2» translates as "When
> > > > library foo asks for the value of key in a situation of the form
> > > > bar:*:baz, tell it the answer is «v1 v2»".
> > > 
> > > Perhaps there should be a zsh function that translates a zstyle line
> > > to plain English. :-)
> > 
> > What do you have in mind, exactly?  It'd be pretty easy to write
> > something that, say, runs «zstyle -L» and applies the sh-to-English
> > mechanical transformation I did above.  That's just a compiler…
> 
> The above is not very helpful for the end user.
> 
> For instance, "zstyle -L" gives in particular:
> 
>   zstyle :urlglobber url-local-schema ftp file
>   zstyle ':url-quote-magic:*' url-metas '*?[]^(|)~#{}='
> 
> but I can't find any explanation about why it should be ":urlglobber"
> and not something else. The man page looks similar for urlglobber and
> url-quote-magic, though they look different above.
> 

By convention, context patterns are of the form «:foo:…» where «foo»
identifies a particular library / module / plugin for namespacing
reasons.  So, it says ":urlglobber" and not something else because
that's what the author of urlglobber named urlglobber.

> In the zshmodules(1) man page:
> 
>   For  example,  a  fictional  `weather' plugin might state in its
>   documentation that it looks up the preferred-precipitation style
>   under the `:weather:continent:day-of-the-week:phase-of-the-moon'
>   context.  According to this, you might set the following in your
>   zshrc:
> 
>     zstyle ':weather:europe:*' preferred-precipitation rain
>     zstyle ':weather:*:Sunday:*' preferred-precipitation snow
> 
> So I would expect the translator to mention "continent",
> "day-of-the-week" and "phase-of-the-moon" in its output.

The zstyle completion actually does this; try completing
«zstyle :vcs_info:<TAB>» or «zstyle :completion:<TAB>».

> Moreover, for ':completion:*', it is difficult to find the associated
> documentation, because if one searches for "completion" in the zshall
> man page, one gets too many matches.

In this case the best approach is to look for the style name.  In other
formats of the manual, each style name has its own index entry.

----

Potentially some of the above should be added to the manual.

Daniel
(I might not have time this morning to reply to all threads I participated in)


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

* Re: [PATCH] zstyle: Correct and expand docs (was: Re: Most minimal configuration challenge)
  2022-09-02 15:05                         ` Bart Schaefer
@ 2022-09-04  6:51                           ` Daniel Shahaf
  0 siblings, 0 replies; 40+ messages in thread
From: Daniel Shahaf @ 2022-09-04  6:51 UTC (permalink / raw)
  To: zsh-users

Bart Schaefer wrote on Fri, Sep 02, 2022 at 08:05:18 -0700:
> On Fri, Sep 2, 2022 at 3:40 AM Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
> >
> > +The definition stored for that style name the most specific pattern that
> 
> Missing a word?

Yes, but more importantly, the sentence could sound like context
patterns are tested first and only then a style definition is looked
for, meaning a more specific pattern that doesn't define the style /at
all/ [not simply define to an empty list] trumps less specific patterns
that do define the style.

Also, s/common/comment/ in the comment.

ENOTIME to revise right now.

Daniel


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

* Re: Most minimal configuration challenge
  2022-09-02 14:26                         ` Ray Andrews
@ 2022-09-04  7:13                           ` Daniel Shahaf
  2022-09-04 16:30                             ` Ray Andrews
  0 siblings, 1 reply; 40+ messages in thread
From: Daniel Shahaf @ 2022-09-04  7:13 UTC (permalink / raw)
  To: Ray Andrews; +Cc: zsh-users

Ray Andrews wrote on Fri, Sep 02, 2022 at 07:26:54 -0700:
> On 2022-09-02 03:36, Daniel Shahaf wrote:
> 
> Ironically this sentence would be the perfect start to some doc about
> zstyle that was actually helpful:
> 
> > There's no easy way to explain zstyle in a sentence since it has so many
> > moving parts (keys, values, contexts, context patterns).
> 
> ... start off by letting the reader know that zstyle is [complex]

Personally, I find that sentence doesn't actually convey any (objective)
information about what zstyle is or does, so it'd be among the first
things I'd cut.

You are of course welcome to grab a pen or a keyboard and write "Ray's
Introduction to zstyle" (or whatever you might call it) and start it
like that.  If you use a nice markdown editor and put it on github…

> > 
> > 3. Readers (including lurkers) would get a fishing rod rather than a fish.
> > 
> But sometimes what you want is a fish.  That's the perfect analogy tho. 
> Sometimes I
> want a fishing rod, sometimes I want a fish.  When it comes to
> documentation, they
> are very different things.

Perhaps what you have in mind here is the difference between a tutorial
or user manual on the one hand, and a reference manual on the other
hand.

zsh's manual is of the second kind.


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

* Re: Most minimal configuration challenge
  2022-09-02 13:55                       ` Most minimal configuration challenge Ray Andrews
@ 2022-09-04  7:21                         ` Daniel Shahaf
  2022-09-04 16:34                           ` Ray Andrews
  0 siblings, 1 reply; 40+ messages in thread
From: Daniel Shahaf @ 2022-09-04  7:21 UTC (permalink / raw)
  To: Ray Andrews; +Cc: zsh-users

Ray Andrews wrote on Fri, Sep 02, 2022 at 06:55:21 -0700:
> On 2022-09-01 18:49, Felipe Contreras wrote:
> > 
> > The clueless students are an essential part of the equation.
> When I'm critiquing a document I deliberately become dumb.  Even if I
> get it, if I think it could have been explained better I'll act as tho I
> don't get it.

You may wish to drop this approach forthwith and instead say "I think
this could be improved" in so many words.  

Daniel


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

* Re: Most minimal configuration challenge
  2022-09-02 13:32                     ` Ray Andrews
@ 2022-09-04  7:28                       ` Daniel Shahaf
  0 siblings, 0 replies; 40+ messages in thread
From: Daniel Shahaf @ 2022-09-04  7:28 UTC (permalink / raw)
  To: Ray Andrews; +Cc: zsh-users

Ray Andrews wrote on Fri, Sep 02, 2022 at 06:32:41 -0700:
> On 2022-09-01 18:26, Lawrence Velázquez wrote:
> > I have no doubt he
> > could have written a more verbose and comprehensive explanation in
> > a paragraph or two, but I wouldn't have been surprised if you'd
> > objected to its wordiness.
> 
> Nope, a paragraph or two would be just what I'd look for.

Those paragraphs are in the manual.


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

* Re: Most minimal configuration challenge
  2022-09-04  7:13                           ` Daniel Shahaf
@ 2022-09-04 16:30                             ` Ray Andrews
  0 siblings, 0 replies; 40+ messages in thread
From: Ray Andrews @ 2022-09-04 16:30 UTC (permalink / raw)
  To: zsh-users

On 2022-09-04 00:13, Daniel Shahaf wrote:
>
> Perhaps what you have in mind here is the difference between a tutorial
> or user manual on the one hand, and a reference manual on the other
> hand.
>
> zsh's manual is of the second kind.
>
Precisely.  The difference should be explicit.  Many times I've wanted 
actual help
with something and I end up with a reference manual whereas what I'm 
looking
for is a user's manual.



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

* Re: Most minimal configuration challenge
  2022-09-04  7:21                         ` Daniel Shahaf
@ 2022-09-04 16:34                           ` Ray Andrews
  0 siblings, 0 replies; 40+ messages in thread
From: Ray Andrews @ 2022-09-04 16:34 UTC (permalink / raw)
  To: zsh-users

On 2022-09-04 00:21, Daniel Shahaf wrote:
> Ray Andrews wrote on Fri, Sep 02, 2022 at 06:55:21 -0700:
>> On 2022-09-01 18:49, Felipe Contreras wrote:
>>> The clueless students are an essential part of the equation.
>> When I'm critiquing a document I deliberately become dumb.  Even if I
>> get it, if I think it could have been explained better I'll act as tho I
>> don't get it.
> You may wish to drop this approach forthwith and instead say "I think
> this could be improved" in so many words.

Possibly.  Being 'dumb' is faster and more focused.  If collaborating on 
the writing
of some doc, I'd take your approach tho, no need for the pretense.

>
> Daniel
>



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

* Re: Most minimal configuration challenge
  2022-09-04  6:42                     ` Daniel Shahaf
@ 2022-09-05  9:47                       ` Vincent Lefevre
  2022-09-12  8:59                         ` Daniel Shahaf
  0 siblings, 1 reply; 40+ messages in thread
From: Vincent Lefevre @ 2022-09-05  9:47 UTC (permalink / raw)
  To: zsh-users

On 2022-09-04 06:42:24 +0000, Daniel Shahaf wrote:
> Vincent Lefevre wrote on Fri, Sep 02, 2022 at 16:44:34 +0200:
> > For instance, "zstyle -L" gives in particular:
> > 
> >   zstyle :urlglobber url-local-schema ftp file
> >   zstyle ':url-quote-magic:*' url-metas '*?[]^(|)~#{}='
> > 
> > but I can't find any explanation about why it should be ":urlglobber"
> > and not something else. The man page looks similar for urlglobber and
> > url-quote-magic, though they look different above.
> 
> By convention, context patterns are of the form «:foo:…» where «foo»
> identifies a particular library / module / plugin for namespacing
> reasons.  So, it says ":urlglobber" and not something else because
> that's what the author of urlglobber named urlglobber.

This is still unclear. The zshcontrib(1) man page says:

        zstyle :bracketed-paste-magic paste-finish \
               quote-paste
        zstyle :bracketed-paste-magic:finish quote-style \
               qqq

But I don't see why ":bracketed-paste-magic" is used in the first line
instead of ":bracketed-paste-magic:*". Moreover, I don't see where the
context "finish" is described in the man pages.

> > In the zshmodules(1) man page:
> > 
> >   For  example,  a  fictional  `weather' plugin might state in its
> >   documentation that it looks up the preferred-precipitation style
> >   under the `:weather:continent:day-of-the-week:phase-of-the-moon'
> >   context.  According to this, you might set the following in your
> >   zshrc:
> > 
> >     zstyle ':weather:europe:*' preferred-precipitation rain
> >     zstyle ':weather:*:Sunday:*' preferred-precipitation snow
> > 
> > So I would expect the translator to mention "continent",
> > "day-of-the-week" and "phase-of-the-moon" in its output.
> 
> The zstyle completion actually does this; try completing
> «zstyle :vcs_info:<TAB>» or «zstyle :completion:<TAB>».

zstyle :vcs_info:<TAB>

just gives

Completing `context pattern' or `vcs'

This is not very informative. This is different from the man page,
which says "vcs-string".

zstyle :bracketed-paste-magic:<TAB>

is even less informative:

Completing `context pattern'

With "ls -<TAB>", I get a list of possible options together with
a short explanation. I would expect something like that with
"zstyle :completion:<TAB>" rather than just a list of the possible
completions.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)


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

* Re: Most minimal configuration challenge
  2022-09-05  9:47                       ` Vincent Lefevre
@ 2022-09-12  8:59                         ` Daniel Shahaf
  0 siblings, 0 replies; 40+ messages in thread
From: Daniel Shahaf @ 2022-09-12  8:59 UTC (permalink / raw)
  To: zsh-users

Vincent Lefevre wrote on Mon, Sep 05, 2022 at 11:47:34 +0200:
> On 2022-09-04 06:42:24 +0000, Daniel Shahaf wrote:
> > Vincent Lefevre wrote on Fri, Sep 02, 2022 at 16:44:34 +0200:
> > > For instance, "zstyle -L" gives in particular:
> > > 
> > >   zstyle :urlglobber url-local-schema ftp file
> > >   zstyle ':url-quote-magic:*' url-metas '*?[]^(|)~#{}='
> > > 
> > > but I can't find any explanation about why it should be ":urlglobber"
> > > and not something else. The man page looks similar for urlglobber and
> > > url-quote-magic, though they look different above.
> > 
> > By convention, context patterns are of the form «:foo:…» where «foo»
> > identifies a particular library / module / plugin for namespacing
> > reasons.  So, it says ":urlglobber" and not something else because
> > that's what the author of urlglobber named urlglobber.
> 
> This is still unclear. The zshcontrib(1) man page says:
> 
>         zstyle :bracketed-paste-magic paste-finish \
>                quote-paste
>         zstyle :bracketed-paste-magic:finish quote-style \
>                qqq
> 
> But I don't see why ":bracketed-paste-magic" is used in the first line
> instead of ":bracketed-paste-magic:*".

The context pattern must match the lookup's context.  The lookup of the
paste-finish style in the bracketed-paste-magic plugin are under the
context ":bracketed-paste-magic".  The pattern ":bracketed-paste-magic:*"
wouldn't match that context.

> Moreover, I don't see where the context "finish" is described in the
> man pages.

The context element "finish" is specific to the quote-paste helper
function.  (That's perhaps not clear from the documentation.)  The
possible values of that style are indeed undocumented.  Bart?

> > > In the zshmodules(1) man page:
> > > 
> > >   For  example,  a  fictional  `weather' plugin might state in its
> > >   documentation that it looks up the preferred-precipitation style
> > >   under the `:weather:continent:day-of-the-week:phase-of-the-moon'
> > >   context.  According to this, you might set the following in your
> > >   zshrc:
> > > 
> > >     zstyle ':weather:europe:*' preferred-precipitation rain
> > >     zstyle ':weather:*:Sunday:*' preferred-precipitation snow
> > > 
> > > So I would expect the translator to mention "continent",
> > > "day-of-the-week" and "phase-of-the-moon" in its output.
> > 
> > The zstyle completion actually does this; try completing
> > «zstyle :vcs_info:<TAB>» or «zstyle :completion:<TAB>».
> 
> zstyle :vcs_info:<TAB>
> 
> just gives
> 
> Completing `context pattern' or `vcs'
> 

Here it says «vcs» and offers the various valid values (plus or minus
quilt and hooks, but that's another story).

Under «zsh -f» the various valid values aren't completed until
vcs_info_printsys is callable.  Running vcs_info once does the trick.
Presumably _zstyle should «autoload vcs_info_printsys» before calling it.
Could someone test this, please?  (I'm ENOTIME.)

> This is not very informative. This is different from the man page,
> which says "vcs-string".
> 

Again, I'm ENOTIME, but patches are welcome.

> zstyle :bracketed-paste-magic:<TAB>
> 
> is even less informative:
> 
> Completing `context pattern'
> 

bracketed-paste-magic styles should /not/ be completed at this point.

Styles used by the quote-paste helper function /should/ be completed at
that point.  So, the problem is just that _zstyle doesn't know about the
styles used by that helper function.

_zstyle could be taught about bracketed-paste-magic and quote-paste…

… but it doesn't scale for _zstyle to know about any random zstyle-using
thing.  For instance, a third party plugin that looks up zstyles might
want implement completion for them.  It'd be a lot easier to do that if
_zstyle would, say, delegate to «_zstyle-foo» for completion related to
contexts of the form (:foo|:foo:*), and that function were implemented
by by the foo (possibly third-party) plugin.

> With "ls -<TAB>", I get a list of possible options together with
> a short explanation. I would expect something like that with
> "zstyle :completion:<TAB>" rather than just a list of the possible
> completions.

Patches welcome.  See _zstyle and _describe.

Cheers,

Daniel


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

end of thread, other threads:[~2022-09-12  9:01 UTC | newest]

Thread overview: 40+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-08-27  4:30 Most minimal configuration challenge Felipe Contreras
2022-08-27 16:10 ` Daniel Shahaf
2022-08-27 19:32   ` Vincent Bernat
2022-08-27 20:04     ` Lawrence Velázquez
2022-08-27 23:53       ` Ray Andrews
2022-08-28  7:53         ` zzapper
2022-08-28 10:30         ` Daniel Shahaf
2022-08-28 13:59           ` Ray Andrews
2022-08-28 18:29             ` Daniel Shahaf
2022-08-31  9:28               ` Vincent Lefevre
2022-08-31 14:17                 ` Ray Andrews
2022-09-01 21:52                   ` Felipe Contreras
2022-09-02  1:41                     ` Lawrence Velázquez
2022-09-02  1:26                   ` Lawrence Velázquez
2022-09-02  1:49                     ` Felipe Contreras
2022-09-02  5:40                       ` Lawrence Velázquez
2022-09-02  7:38                         ` Felipe Contreras
2022-09-02 10:36                       ` Daniel Shahaf
2022-09-02 14:26                         ` Ray Andrews
2022-09-04  7:13                           ` Daniel Shahaf
2022-09-04 16:30                             ` Ray Andrews
2022-09-02 10:39                       ` [PATCH] zstyle: Correct and expand docs (was: Re: Most minimal configuration challenge) Daniel Shahaf
2022-09-02 15:05                         ` Bart Schaefer
2022-09-04  6:51                           ` Daniel Shahaf
2022-09-02 13:55                       ` Most minimal configuration challenge Ray Andrews
2022-09-04  7:21                         ` Daniel Shahaf
2022-09-04 16:34                           ` Ray Andrews
2022-09-02 13:32                     ` Ray Andrews
2022-09-04  7:28                       ` Daniel Shahaf
2022-09-02  9:53                   ` Daniel Shahaf
2022-09-02  9:26                 ` Daniel Shahaf
2022-09-02 14:44                   ` Vincent Lefevre
2022-09-04  6:42                     ` Daniel Shahaf
2022-09-05  9:47                       ` Vincent Lefevre
2022-09-12  8:59                         ` Daniel Shahaf
2022-08-28 18:58             ` Bart Schaefer
2022-08-28 19:23               ` Felipe Contreras
2022-08-28 19:35               ` Ray Andrews
2022-08-28 18:57   ` Felipe Contreras
2022-09-02  1:36 ` Vincent Lefevre

Code repositories for project(s) associated with this public inbox

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

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).