GNU bug report logs - #56870
company-dabbrev variable documentation

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 56870 in the body.
You can then email your comments to 56870 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: uzibalqa <uzibalqa <at> proton.me>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: company-dabbrev variable documentation
Date: Mon, 01 Aug 2022 03:54:04 +0000

[Message part 1 (text/plain, inline)]

I am setting company-dabbrev variables

(setq company-dabbrev-other-buffers 'all)
(setq company-dabbrev-ignore-case 'keep-prefix)

The documentation for the variables, says

If ‘all’, search all other buffers, except the ignored ones.

I find the documentation confusing because nowhere does it say that on should use 'all rather than all or "all".

[Message part 2 (text/html, inline)]

Message #8 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: Matt Armstrong <matt <at> rfc20.org>
To: uzibalqa <uzibalqa <at> proton.me>
Cc: 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: company-dabbrev variable documentation
Date: Mon, 01 Aug 2022 14:24:14 -0700

uzibalqa <uzibalqa <at> proton.me> writes:

> I am setting company-dabbrev variables
>
> (setq company-dabbrev-other-buffers 'all)
> (setq company-dabbrev-ignore-case 'keep-prefix)
>
> The documentation for the variables,  says
>
> If ‘all’, search all other buffers, except the ignored ones.
>
> I find the documentation confusing because nowhere does it say that on
> should use 'all rather than all or "all".

I can understand your confusion.

When working at the level of Emacs Lisp, keep a few things in mind:

a) Generally, in Emacs Lisp help, if you see something like ‘all’ it
means a lisp level symbol.  This could be a function name, variable, or
some other symbol.  This is part of the project's conventions, described
here:
https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html

b) When lisp level interfaces expect strings they generally say so, and
the examples use quotes like "this".

c) A bare all (without any quotes at all), is just a word, and not
a Lisp level function or variable.

Hope that helps!

Message #11 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: Matt Armstrong <matt <at> rfc20.org>
To: uzibalqa <uzibalqa <at> proton.me>
Cc: 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: company-dabbrev variable documentation
Date: Mon, 01 Aug 2022 14:49:15 -0700

uzibalqa <uzibalqa <at> proton.me> writes:

> On Monday, August 1st, 2022 at 9:24 PM, Matt Armstrong <matt <at> rfc20.org> wrote:
>> Hope that helps!
>
> It is a shame that documentation does not come with example.  It is
> what is much lacking.

I think the "friendly" way to customize Emacs is intended to be the
customization system:
https://www.gnu.org/software/emacs/manual/html_node/emacs/Easy-Customization.html
In most cases, the customize interface hides lisp level details from the
user.

There is project level goal that most of the useful customizations a
user can do in Emacs should be possible in the customize system, without
using lisp.  This is one reason the help text does not often describe
things with Lisp examples.  They would be of no use to the people using
the Customize interface, and possibly even confusing.

I still think your original point is a good one. I found the one piece
of documentation explaining how to write quoted things in Emacs
documentation, but I could not find a place explaining the conventions
for quoted things mean in Emacs help.  Perhaps another person can find
that, or suggest a way to explain it to new users.

Message #14 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: uzibalqa <uzibalqa <at> proton.me>
To: Matt Armstrong <matt <at> rfc20.org>
Cc: 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: company-dabbrev variable documentation
Date: Mon, 01 Aug 2022 21:32:00 +0000

------- Original Message -------
On Monday, August 1st, 2022 at 9:24 PM, Matt Armstrong <matt <at> rfc20.org> wrote:


> uzibalqa uzibalqa <at> proton.me writes:
>
> > I am setting company-dabbrev variables
> >
> > (setq company-dabbrev-other-buffers 'all)
> > (setq company-dabbrev-ignore-case 'keep-prefix)
> >
> > The documentation for the variables, says
> >
> > If ‘all’, search all other buffers, except the ignored ones.
> >
> > I find the documentation confusing because nowhere does it say that on
> > should use 'all rather than all or "all".
>
>
> I can understand your confusion.
>
> When working at the level of Emacs Lisp, keep a few things in mind:
>
> a) Generally, in Emacs Lisp help, if you see something like ‘all’ it
> means a lisp level symbol. This could be a function name, variable, or
> some other symbol. This is part of the project's conventions, described
> here:
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
>
> b) When lisp level interfaces expect strings they generally say so, and
> the examples use quotes like "this".
>
> c) A bare all (without any quotes at all), is just a word, and not
> a Lisp level function or variable.
>
> Hope that helps!

It is a shame that documentation does not come with example.  It is what is much lacking.

Message #17 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: uzibalqa <uzibalqa <at> proton.me>
To: Matt Armstrong <matt <at> rfc20.org>
Cc: 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: company-dabbrev variable documentation
Date: Mon, 01 Aug 2022 21:49:28 +0000

------- Original Message -------
On Monday, August 1st, 2022 at 9:32 PM, uzibalqa <uzibalqa <at> proton.me> wrote:


> ------- Original Message -------
> On Monday, August 1st, 2022 at 9:24 PM, Matt Armstrong matt <at> rfc20.org wrote:
>
>
>
> > uzibalqa uzibalqa <at> proton.me writes:
> >
> > > I am setting company-dabbrev variables
> > >
> > > (setq company-dabbrev-other-buffers 'all)
> > > (setq company-dabbrev-ignore-case 'keep-prefix)
> > >
> > > The documentation for the variables, says
> > >
> > > If ‘all’, search all other buffers, except the ignored ones.
> > >
> > > I find the documentation confusing because nowhere does it say that on
> > > should use 'all rather than all or "all".
> >
> > I can understand your confusion.
> >
> > When working at the level of Emacs Lisp, keep a few things in mind:
> >
> > a) Generally, in Emacs Lisp help, if you see something like ‘all’ it
> > means a lisp level symbol. This could be a function name, variable, or
> > some other symbol. This is part of the project's conventions, described
> > here:
> > https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
> >
> > b) When lisp level interfaces expect strings they generally say so, and
> > the examples use quotes like "this".
> >
> > c) A bare all (without any quotes at all), is just a word, and not
> > a Lisp level function or variable.
> >
> > Hope that helps!
>
>
> It is a shame that documentation does not come with example. It is what is much lacking.

Am also having difficulty showing documentation for company-dabbrev-* and company-dabbrev-code-* using `C-h v'.

Message #20 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: uzibalqa <uzibalqa <at> proton.me>
To: Matt Armstrong <matt <at> rfc20.org>
Cc: 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: company-dabbrev variable documentation
Date: Mon, 01 Aug 2022 21:55:51 +0000

------- Original Message -------
On Monday, August 1st, 2022 at 9:49 PM, Matt Armstrong <matt <at> rfc20.org> wrote:


> uzibalqa uzibalqa <at> proton.me writes:
>
> > On Monday, August 1st, 2022 at 9:24 PM, Matt Armstrong matt <at> rfc20.org wrote:
> >
> > > Hope that helps!
> >
> > It is a shame that documentation does not come with example. It is
> > what is much lacking.
>
>
> I think the "friendly" way to customize Emacs is intended to be the
> customization system:
> https://www.gnu.org/software/emacs/manual/html_node/emacs/Easy-Customization.html
> In most cases, the customize interface hides lisp level details from the
> user.
>
> There is project level goal that most of the useful customizations a
> user can do in Emacs should be possible in the customize system, without
> using lisp. This is one reason the help text does not often describe
> things with Lisp examples. They would be of no use to the people using
> the Customize interface, and possibly even confusing.

There can be a verbosity flag that can be used to show lisp usage following
the description.

> I still think your original point is a good one. I found the one piece
> of documentation explaining how to write quoted things in Emacs
> documentation, but I could not find a place explaining the conventions
> for quoted things mean in Emacs help. Perhaps another person can find
> that, or suggest a way to explain it to new users.

Such conventions should be described in the starting part of the documentation or in appendix.

Message #23 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Matt Armstrong <matt <at> rfc20.org>
Cc: uzibalqa <uzibalqa <at> proton.me>, 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: company-dabbrev variable documentation
Date: Tue, 02 Aug 2022 12:20:41 +0200

Matt Armstrong <matt <at> rfc20.org> writes:

> b) When lisp level interfaces expect strings they generally say so, and
> the examples use quotes like "this".
>
> c) A bare all (without any quotes at all), is just a word, and not
> a Lisp level function or variable.

So I don't think there's anything to fix in Emacs here -- we sometimes
say "the symbol `all'" if there's an unusual amount of possible
confusion present -- and I'm therefore closing this bug report.

Message #30 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: uzibalqa <uzibalqa <at> proton.me>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Matt Armstrong <matt <at> rfc20.org>, 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: company-dabbrev variable documentation
Date: Tue, 02 Aug 2022 10:34:36 +0000

------- Original Message -------
On Tuesday, August 2nd, 2022 at 10:20 AM, Lars Ingebrigtsen <larsi <at> gnus.org> wrote:


> Matt Armstrong matt <at> rfc20.org writes:
>
> > b) When lisp level interfaces expect strings they generally say so, and
> > the examples use quotes like "this".
> >
> > c) A bare all (without any quotes at all), is just a word, and not
> > a Lisp level function or variable.
>
>
> So I don't think there's anything to fix in Emacs here -- we sometimes
> say "the symbol `all'" if there's an unusual amount of possible
> confusion present -- and I'm therefore closing this bug report.

I still think you should be explicit as with "this", and present users with what they will actually use, 'this.

It is not good to expect a users to spend hours reading in the hope that he will eventually figure out that what is written in the documentation is not what you write in your code.  And then figure out how to solve it.

Message #33 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: YE <yet <at> ego.team>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Matt Armstrong <matt <at> rfc20.org>, uzibalqa <uzibalqa <at> proton.me>,
 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: company-dabbrev variable documentation
Date: Wed, 03 Aug 2022 13:07:02 +0300

> So I don't think there's anything to fix in Emacs here -- we sometimes
> say "the symbol `all'" if there's an unusual amount of possible
> confusion present -- and I'm therefore closing this bug report.

I'd still suggest considering documentation improvement in this regard.
Probably because I had the same confusion when started with Emacs, even
after having read the whole manual.

[Well, the info node `(elisp) Documentation Tips)' clarifies how to
document symbols :
>  When a documentation string refers to a Lisp symbol, write it as it
>      would be printed (which usually means in lower case), surrounding
>      it with curved single quotes (‘..’)
But Emacs beginner users don't seem to be the target auditory of this
page. And it still won't -- naturally -- explain how to _use_ such
symbols.]

One such possible place to adjust is the info node `(emacs) Examining'.
Maybe replace 'fill-column' example with the one that accepts a
documented symbol (f.i. 'default-justification', 'diff-refine',
'tab-always-complete') and use the symbol in the code below?

Another: info node `(emacs) Init Syntax' could probably state more
explicitly how to deal with the symbols.

Or mention symbols documentation/usage at the end of the info node
`(emacs) Variables', after the line "check the variable’s documentation
string to see what kind of value it expects".

WDYT?

Message #36 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: Matt Armstrong <matt <at> rfc20.org>
To: YE <yet <at> ego.team>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: uzibalqa <uzibalqa <at> proton.me>, 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: company-dabbrev variable documentation
Date: Wed, 03 Aug 2022 11:41:39 -0700

YE <yet <at> ego.team> writes:

>> So I don't think there's anything to fix in Emacs here -- we sometimes
>> say "the symbol `all'" if there's an unusual amount of possible
>> confusion present -- and I'm therefore closing this bug report.
>
> I'd still suggest considering documentation improvement in this regard.
> Probably because I had the same confusion when started with Emacs, even
> after having read the whole manual.
>
> [Well, the info node `(elisp) Documentation Tips)' clarifies how to
> document symbols :
>>  When a documentation string refers to a Lisp symbol, write it as it
>>      would be printed (which usually means in lower case), surrounding
>>      it with curved single quotes (‘..’)
> But Emacs beginner users don't seem to be the target auditory of this
> page. And it still won't -- naturally -- explain how to _use_ such
> symbols.]
>
> One such possible place to adjust is the info node `(emacs) Examining'.
> Maybe replace 'fill-column' example with the one that accepts a
> documented symbol (f.i. 'default-justification', 'diff-refine',
> 'tab-always-complete') and use the symbol in the code below?
>
> Another: info node `(emacs) Init Syntax' could probably state more
> explicitly how to deal with the symbols.
>
> Or mention symbols documentation/usage at the end of the info node
> `(emacs) Variables', after the line "check the variable’s documentation
> string to see what kind of value it expects".
>
> WDYT?

People learn in different ways, so perhaps we should do all of those
things?

I think improving the various manuals is always a good idea.  The hard
part is finding and encouraging people to contribute the work!  :-)  I
think the maintainers are quite receptive to improvements like this.

Another thing to keep in mind: most of the common languages these days
do not have symbols, so the very concept might be unfamiliar to new
users.

Another place that might improve is "An Introduction to Programming in
Emacs Lisp"
(https://www.gnu.org/software/emacs/manual/html_mono/eintr.html).  In my
opinion, it could do a better job explaining what a symbol is, how to
express them in code, quote them, how they are often used as "magic
values", etc.  It talks about them in context with "atoms" but that is
fairly esoteric.

FWIW I find that the classic book "A Gentle Introduction to Symbolic
Computaton" does a great job explaining what a symbol is.  It introduces
the idea of a symbol as the second fundamental concept of the language,
in the first chapter, right after functions.

https://www.cs.cmu.edu/~dst/LispBook/book.pdf

Turning back to Emacs' help system, I wonder if it could be made more
clear that all of these quoted "things" in help text are intended to be
lisp symbols.  Wild idea: always turn them into links.  An arbitrary
`foo' that isn't a function or variable would link to a synthetic help
page explaining that it is a symbol, how it might appear in lisp code,
link to an appropriate manual, etc.  Perhaps this would be too noisy...

Message #39 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: carlmarcos <at> tutanota.com
To: Matt Armstrong <matt <at> rfc20.org>
Cc: YE <yet <at> ego.team>, uzibalqa <uzibalqa <at> proton.me>,
 Lars Ingebrigtsen <larsi <at> gnus.org>, 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: company-dabbrev variable documentation
Date: Wed, 3 Aug 2022 20:50:44 +0200 (CEST)

Aug 3, 2022, 18:41 by matt <at> rfc20.org:

> YE <yet <at> ego.team> writes:
>
>>> So I don't think there's anything to fix in Emacs here -- we sometimes
>>> say "the symbol `all'" if there's an unusual amount of possible
>>> confusion present -- and I'm therefore closing this bug report.
>>>
>>
>> I'd still suggest considering documentation improvement in this regard.
>> Probably because I had the same confusion when started with Emacs, even
>> after having read the whole manual.
>>
>> [Well, the info node `(elisp) Documentation Tips)' clarifies how to
>> document symbols :
>>
>>> When a documentation string refers to a Lisp symbol, write it as it
>>>  would be printed (which usually means in lower case), surrounding
>>>  it with curved single quotes (‘..’)
>>>
>> But Emacs beginner users don't seem to be the target auditory of this
>> page. And it still won't -- naturally -- explain how to _use_ such
>> symbols.]
>>
>> One such possible place to adjust is the info node `(emacs) Examining'.
>> Maybe replace 'fill-column' example with the one that accepts a
>> documented symbol (f.i. 'default-justification', 'diff-refine',
>> 'tab-always-complete') and use the symbol in the code below?
>>
>> Another: info node `(emacs) Init Syntax' could probably state more
>> explicitly how to deal with the symbols.
>>
>> Or mention symbols documentation/usage at the end of the info node
>> `(emacs) Variables', after the line "check the variable’s documentation
>> string to see what kind of value it expects".
>>
>> WDYT?
>>
>
> People learn in different ways, so perhaps we should do all of those
> things?
>
> I think improving the various manuals is always a good idea.  The hard
> part is finding and encouraging people to contribute the work!  :-)  I
> think the maintainers are quite receptive to improvements like this.
>

I completely disagree.  The experience with maintainers has shown how unreceptive
they often get towards improvements like this.  Lars thought there isn't anything to fix
in Emacs and decided to close this bug report.



> Another thing to keep in mind: most of the common languages these days
> do not have symbols, so the very concept might be unfamiliar to new
> users.
>
> Another place that might improve is "An Introduction to Programming in
> Emacs Lisp"
> (https://www.gnu.org/software/emacs/manual/html_mono/eintr.html).  In my
> opinion, it could do a better job explaining what a symbol is, how to
> express them in code, quote them, how they are often used as "magic
> values", etc.  It talks about them in context with "atoms" but that is
> fairly esoteric.
>
> FWIW I find that the classic book "A Gentle Introduction to Symbolic
> Computaton" does a great job explaining what a symbol is.  It introduces
> the idea of a symbol as the second fundamental concept of the language,
> in the first chapter, right after functions.
>
> https://www.cs.cmu.edu/~dst/LispBook/book.pdf
>
> Turning back to Emacs' help system, I wonder if it could be made more
> clear that all of these quoted "things" in help text are intended to be
> lisp symbols.  Wild idea: always turn them into links.  An arbitrary
> `foo' that isn't a function or variable would link to a synthetic help
> page explaining that it is a symbol, how it might appear in lisp code,
> link to an appropriate manual, etc.  Perhaps this would be too noisy...
>

Message #42 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: YE <yet <at> ego.team>
To: Matt Armstrong <matt <at> rfc20.org>
Cc: yet <at> ego.team, uzibalqa <at> proton.me, larsi <at> gnus.org, 56870 <at> debbugs.gnu.org
Subject: [PATCH] Re: bug#56870: company-dabbrev variable documentation
Date: Thu, 04 Aug 2022 19:06:36 +0300

[Message part 1 (text/plain, inline)]

My take on the 'Init File' docs improvement is attached.

[0001-Expand-Init-File-documentation-in-Emacs-manual.patch (text/x-patch, attachment)]

Message #45 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: YE <yet <at> ego.team>
Cc: matt <at> rfc20.org, yet <at> ego.team, uzibalqa <at> proton.me, larsi <at> gnus.org,
 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: [PATCH] Re: bug#56870: company-dabbrev variable
 documentation
Date: Thu, 04 Aug 2022 19:41:06 +0300

> Cc: yet <at> ego.team, uzibalqa <at> proton.me, larsi <at> gnus.org, 56870 <at> debbugs.gnu.org
> Date: Thu, 04 Aug 2022 19:06:36 +0300
> From:  YE via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> My take on the 'Init File' docs improvement is attached.

Thanks.  However, this basically adds to the Emacs manual stuff whose
place is in the ELisp manual.  So I'm not sure we should start on this
slippery slope.  Users who need to write complex Lisp in their init
files need to read the ELisp manual anyway.

Message #48 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: Matt Armstrong <matt <at> rfc20.org>
To: carlmarcos <at> tutanota.com
Cc: YE <yet <at> ego.team>, uzibalqa <uzibalqa <at> proton.me>,
 Lars Ingebrigtsen <larsi <at> gnus.org>, 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: company-dabbrev variable documentation
Date: Thu, 04 Aug 2022 10:09:30 -0700

carlmarcos <at> tutanota.com writes:

> Aug 3, 2022, 18:41 by matt <at> rfc20.org:
>
>> I think the maintainers are quite receptive to improvements like
>> this.
>
> I completely disagree.  The experience with maintainers has shown how
> unreceptive they often get towards improvements like this.  Lars
> thought there isn't anything to fix in Emacs and decided to close this
> bug report.

I think reasonable people can disagree about what is and is not a
problem, is or is not an improvement, or even misunderstand eachother
entirely.  Sometimes patience and additional explanations are the way to
move forward.

In this case, I agree with Lars that the company-dabbrev docstring is
consistent with Emacs' usual way of writing docstrings.  I don't
actually see a clear way to improve the one docstring in isolation
without it becoming inconsistent with the rest of Emacs.  And so, I
would expect any improvement here to involve some discussion, since the
path forward isn't obvious.

Message #51 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: Matt Armstrong <matt <at> rfc20.org>
To: Eli Zaretskii <eliz <at> gnu.org>, YE <yet <at> ego.team>
Cc: yet <at> ego.team, uzibalqa <at> proton.me, larsi <at> gnus.org, 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: [PATCH] Re: bug#56870: company-dabbrev variable
 documentation
Date: Thu, 04 Aug 2022 10:48:47 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Cc: yet <at> ego.team, uzibalqa <at> proton.me, larsi <at> gnus.org, 56870 <at> debbugs.gnu.org
>> Date: Thu, 04 Aug 2022 19:06:36 +0300
>> From:  YE via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
>> 
>> My take on the 'Init File' docs improvement is attached.
>
> Thanks.  However, this basically adds to the Emacs manual stuff whose
> place is in the ELisp manual.  So I'm not sure we should start on this
> slippery slope.  Users who need to write complex Lisp in their init
> files need to read the ELisp manual anyway.

Eli, perhaps a single link to the ELisp manual near the beginning of
"(emacs) Init Syntax" would be acceptable?  The section is describing a
small subset of lisp, so I think such a link would be useful there.
(Way back when I was first learning Emacs it took me quite a while
before I realized that the ELisp manual existed at all.)

I tend to agree with you that "(emacs) Init Syntax" isn't a great place
to describe how various lisp constructs appear in help text, since it
its focus is how to write lisp code.  I would think that belongs
somewhere under "(emacs) Help".

Message #54 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Matt Armstrong <matt <at> rfc20.org>
Cc: yet <at> ego.team, uzibalqa <at> proton.me, larsi <at> gnus.org, 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: [PATCH] Re: bug#56870: company-dabbrev variable
 documentation
Date: Thu, 04 Aug 2022 21:25:24 +0300

> From: Matt Armstrong <matt <at> rfc20.org>
> Cc: yet <at> ego.team, uzibalqa <at> proton.me, larsi <at> gnus.org, 56870 <at> debbugs.gnu.org
> Date: Thu, 04 Aug 2022 10:48:47 -0700
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >> Cc: yet <at> ego.team, uzibalqa <at> proton.me, larsi <at> gnus.org, 56870 <at> debbugs.gnu.org
> >> Date: Thu, 04 Aug 2022 19:06:36 +0300
> >> From:  YE via "Bug reports for GNU Emacs,
> >>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> >> 
> >> My take on the 'Init File' docs improvement is attached.
> >
> > Thanks.  However, this basically adds to the Emacs manual stuff whose
> > place is in the ELisp manual.  So I'm not sure we should start on this
> > slippery slope.  Users who need to write complex Lisp in their init
> > files need to read the ELisp manual anyway.
> 
> Eli, perhaps a single link to the ELisp manual near the beginning of
> "(emacs) Init Syntax" would be acceptable?

Yes, that's a better idea.

Message #57 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: carlmarcos <at> tutanota.com
To: Matt Armstrong <matt <at> rfc20.org>
Cc: YE <yet <at> ego.team>, uzibalqa <uzibalqa <at> proton.me>,
 Lars Ingebrigtsen <larsi <at> gnus.org>, 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: company-dabbrev variable documentation
Date: Thu, 4 Aug 2022 23:59:25 +0200 (CEST)

Aug 4, 2022, 17:09 by matt <at> rfc20.org:

> carlmarcos <at> tutanota.com writes:
>
>> Aug 3, 2022, 18:41 by matt <at> rfc20.org:
>>
>>> I think the maintainers are quite receptive to improvements like
>>> this.
>>>
>>
>> I completely disagree.  The experience with maintainers has shown how
>> unreceptive they often get towards improvements like this.  Lars
>> thought there isn't anything to fix in Emacs and decided to close this
>> bug report.
>>
>
> I think reasonable people can disagree about what is and is not a
> problem, is or is not an improvement, or even misunderstand eachother
> entirely.  Sometimes patience and additional explanations are the way to
> move forward.
>
> In this case, I agree with Lars that the company-dabbrev docstring is
> consistent with Emacs' usual way of writing docstrings.  I don't
> actually see a clear way to improve the one docstring in isolation
> without it becoming inconsistent with the rest of Emacs.  And so, I
> would expect any improvement here to involve some discussion, since the
> path forward isn't obvious.
>
Sure.  But I found too much eagerness to close the discussion.  Many are putting too much focus
on consistency, when the aim should really be on equipping users with what is actually required  
for them to write code that works.  Rather than rely on assumptions that old timers consider of minor
importance.  Because in the end it is code that works which counts.  The less one tortures people, the better.

Message #60 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: YE <yet <at> ego.team>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: matt <at> rfc20.org, yet <at> ego.team, uzibalqa <at> proton.me, larsi <at> gnus.org,
 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: [PATCH] Re: bug#56870: company-dabbrev variable
 documentation
Date: Fri, 05 Aug 2022 12:10:33 +0300

Eli Zaretskii <eliz <at> gnu.org> writes:

>> My take on the 'Init File' docs improvement is attached.
>
> Thanks.  However, this basically adds to the Emacs manual stuff whose
> place is in the ELisp manual.

This patch clarifies _existing_ node of the Emacs manual:
1. Adds indexes.
2. Adds links to the ELisp manual for further reading.
3. Clarifies how to use _wide-spread_ symbols (extensively used by newbies).

Which part _exactly_ you don't find suitable for the Emacs manual?

Don't Symbols deserve the same attention as Numbers, Strings,
Characters described extensively in `(emacs) Init Syntax'?

Maybe, according to your point of view, this node should be removed from
the Emacs manual altogether, (linking to the ELisp manual)?

In my fresh memory, this part of the manual was one of the least helpful
and the most confusing. So my (vanishing) hope was to contribute a
little bit of improvement to it to help fellow beginner users, when one
of the issues with it was articulated.

Or should I submit a new bug report with the vague: `(emacs) Init File'
is confusing and isn't instructive enough for the newbies?

Many (if not most) of the beginners start tweaking Emacs via the init
file, not Customize interface. So well-written beginner instructions on
how to use init file is a _need_, not a whim.

> So I'm not sure we should start on this
> slippery slope.

We start on the slippery slope when the reported issues aren't resolved.

> Users who need to write complex Lisp in their init
> files need to read the ELisp manual anyway.

What part of the patch touches the "complex Lisp"?

Message #63 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: YE <yet <at> ego.team>
Cc: matt <at> rfc20.org, larsi <at> gnus.org, uzibalqa <at> proton.me, 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: [PATCH] Re: bug#56870: company-dabbrev variable
 documentation
Date: Fri, 05 Aug 2022 14:09:17 +0300

> From: YE <yet <at> ego.team>
> Cc: yet <at> ego.team, matt <at> rfc20.org, uzibalqa <at> proton.me, larsi <at> gnus.org,
> 	56870 <at> debbugs.gnu.org
> Date: Fri, 05 Aug 2022 12:10:33 +0300
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > Thanks.  However, this basically adds to the Emacs manual stuff whose
> > place is in the ELisp manual.
> 
> This patch clarifies _existing_ node of the Emacs manual:
> 1. Adds indexes.
> 2. Adds links to the ELisp manual for further reading.
> 3. Clarifies how to use _wide-spread_ symbols (extensively used by newbies).
> 
> Which part _exactly_ you don't find suitable for the Emacs manual?

All of it.  You explain some basics of Emacs Lisp, which any user who
is serious about customizing his/her Emacs should already know about,
by reading the relevant parts of the ELisp manual.

It goes without saying that this node of the Emacs manual is
intentionally incomplete, but making it complete would mean we'd need
to repeat a significant portion of text that is already in the ELisp
manual, because the missing bits are about Emacs Lisp, not about
anything special to the init files.

> Don't Symbols deserve the same attention as Numbers, Strings,
> Characters described extensively in `(emacs) Init Syntax'?

No, I don't think so.  And this is a slippery slope anyway, because
there's more about Lisp objects than just telling what you suggest to
tell.

> Maybe, according to your point of view, this node should be removed from
> the Emacs manual altogether, (linking to the ELisp manual)?

That'd be too drastic, IMO.  Simple customizations don't need detailed
knowledge of Lisp, and the node attempts to strike a balance between
being useful to beginners and including too much of ELisp.

> Or should I submit a new bug report with the vague: `(emacs) Init File'
> is confusing and isn't instructive enough for the newbies?

If you explain clearly enough what is confusing in that node, we could
try making it less confusing and more instructive, yes.

> > So I'm not sure we should start on this
> > slippery slope.
> 
> We start on the slippery slope when the reported issues aren't resolved.

That's a different slippery slope.

And I disagree that issues aren't resolved.  You might think they
aren't, because your opinions aren't accepted, but we don't promise we
will accept any opinion without considering its advantages and
disadvantages.

> > Users who need to write complex Lisp in their init
> > files need to read the ELisp manual anyway.
> 
> What part of the patch touches the "complex Lisp"?

This one, for example:

  +@item Other Lisp symbols:
  +@cindex Lisp symbol syntax
  +@cindex symbol syntax
  +Write a single-quote (@code{'}) followed by the symbol name
  +(@pxref{Symbols,,, elisp, The Emacs Lisp Reference Manual}).  Note
  +that documentation strings refer to symbols by their names only,
  +without the single-quote (@pxref{Documentation Tips,,, elisp, The
  +Emacs Lisp Reference Manual}).

Why does this text have to talk about doc strings, and what does it
have to do with the syntax of the init file?  And the node to which
you refer is a large and complex node, which is too much for simple
customizations that Init Syntax intends to cover.

Message #66 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: carlmarcos <at> tutanota.com
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: matt <at> rfc20.org, YE <yet <at> ego.team>, uzibalqa <at> proton.me, larsi <at> gnus.org,
 56870 <at> debbugs.gnu.org
Subject: Re: bug#56870: [PATCH] Re: bug#56870: company-dabbrev variable
 documentation
Date: Fri, 5 Aug 2022 13:36:35 +0200 (CEST)

Aug 5, 2022, 11:09 by eliz <at> gnu.org:

>> From: YE <yet <at> ego.team>
>> Cc: yet <at> ego.team, matt <at> rfc20.org, uzibalqa <at> proton.me, larsi <at> gnus.org,
>>  56870 <at> debbugs.gnu.org
>> Date: Fri, 05 Aug 2022 12:10:33 +0300
>>
>> Eli Zaretskii <eliz <at> gnu.org> writes:
>>
>> > Thanks.  However, this basically adds to the Emacs manual stuff whose
>> > place is in the ELisp manual.
>>
>> This patch clarifies _existing_ node of the Emacs manual:
>> 1. Adds indexes.
>> 2. Adds links to the ELisp manual for further reading.
>> 3. Clarifies how to use _wide-spread_ symbols (extensively used by newbies).
>>
>> Which part _exactly_ you don't find suitable for the Emacs manual?
>>
>
> All of it.  You explain some basics of Emacs Lisp, which any user who
> is serious about customizing his/her Emacs should already know about,
> by reading the relevant parts of the ELisp manual.
>
> It goes without saying that this node of the Emacs manual is
> intentionally incomplete, but making it complete would mean we'd need
> to repeat a significant portion of text that is already in the ELisp
> manual, because the missing bits are about Emacs Lisp, not about
> anything special to the init files.
>
>> Don't Symbols deserve the same attention as Numbers, Strings,
>> Characters described extensively in `(emacs) Init Syntax'?
>>
>
> No, I don't think so.  And this is a slippery slope anyway, because
> there's more about Lisp objects than just telling what you suggest to
> tell.
>
The docstring should mention that variable settings use symbol arguments.  


>> Maybe, according to your point of view, this node should be removed from
>> the Emacs manual altogether, (linking to the ELisp manual)?
>>
>
> That'd be too drastic, IMO.  Simple customizations don't need detailed
> knowledge of Lisp, and the node attempts to strike a balance between
> being useful to beginners and including too much of ELisp.
>
>> Or should I submit a new bug report with the vague: `(emacs) Init File'
>> is confusing and isn't instructive enough for the newbies?
>>
>
> If you explain clearly enough what is confusing in that node, we could
> try making it less confusing and more instructive, yes.
>
>> > So I'm not sure we should start on this
>> > slippery slope.
>>
>> We start on the slippery slope when the reported issues aren't resolved.
>>
>
> That's a different slippery slope.
>
> And I disagree that issues aren't resolved.  You might think they
> aren't, because your opinions aren't accepted, but we don't promise we
> will accept any opinion without considering its advantages and
> disadvantages.
>
>> > Users who need to write complex Lisp in their init
>> > files need to read the ELisp manual anyway.
>>
>> What part of the patch touches the "complex Lisp"?
>>
>
> This one, for example:
>
>  +@item Other Lisp symbols:
>  +@cindex Lisp symbol syntax
>  +@cindex symbol syntax
>  +Write a single-quote (@code{'}) followed by the symbol name
>  +(@pxref{Symbols,,, elisp, The Emacs Lisp Reference Manual}).  Note
>  +that documentation strings refer to symbols by their names only,
>  +without the single-quote (@pxref{Documentation Tips,,, elisp, The
>  +Emacs Lisp Reference Manual}).
>
> Why does this text have to talk about doc strings, and what does it
> have to do with the syntax of the init file?  And the node to which
> you refer is a large and complex node, which is too much for simple
> customizations that Init Syntax intends to cover.
>

Message #69 received at 56870 <at> debbugs.gnu.org (full text, mbox):

From: YE <yet <at> ego.team>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: matt <at> rfc20.org, yet <at> ego.team, uzibalqa <at> proton.me, larsi <at> gnus.org,
 56870 <at> debbugs.gnu.org
Subject: [PATCH] Re: bug#56870: company-dabbrev variable documentation
Date: Sat, 06 Aug 2022 15:42:15 +0300

[Message part 1 (text/plain, inline)]

>> Eli Zaretskii:

>> From: YE
>> Which part _exactly_ you don't find suitable for the Emacs manual?
>
> All of it.  You explain some basics of Emacs Lisp, which any user who
> is serious about customizing his/her Emacs should already know about,
> by reading the relevant parts of the ELisp manual.

>> Don't Symbols deserve the same attention as Numbers, Strings,
>> Characters described extensively in `(emacs) Init Syntax'?
>
> No, I don't think so.  And this is a slippery slope anyway, because
> there's more about Lisp objects than just telling what you suggest to
> tell.

>> What part of the patch touches the "complex Lisp"?
>
> Why does this text have to talk about doc strings, and what does it
> have to do with the syntax of the init file?  And the node to which
> you refer is a large and complex node, which is too much for simple
> customizations that Init Syntax intends to cover.
>

Thank you for the detailed response.

>> From: Matt Armstrong
>> Eli, perhaps a single link to the ELisp manual near the beginning of
>> "(emacs) Init Syntax" would be acceptable?
>
> Yes, that's a better idea.

One more tiny patch is attached.
It links 'Init Syntax' to the ELisp manual Introduction node.

[0001-Link-from-emacs-Init-Syntax-to-elisp-Introduction.patch (text/x-patch, attachment)]

Message #72 received at 56870-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: YE <yet <at> ego.team>
Cc: matt <at> rfc20.org, larsi <at> gnus.org, uzibalqa <at> proton.me,
 56870-done <at> debbugs.gnu.org
Subject: Re: [PATCH] Re: bug#56870: company-dabbrev variable documentation
Date: Sat, 06 Aug 2022 16:19:59 +0300

> From: YE <yet <at> ego.team>
> Cc: yet <at> ego.team, matt <at> rfc20.org, uzibalqa <at> proton.me, larsi <at> gnus.org,
>  56870 <at> debbugs.gnu.org
> Date: Sat, 06 Aug 2022 15:42:15 +0300
> 
> Thank you for the detailed response.
> 
> >> From: Matt Armstrong
> >> Eli, perhaps a single link to the ELisp manual near the beginning of
> >> "(emacs) Init Syntax" would be acceptable?
> >
> > Yes, that's a better idea.
> 
> One more tiny patch is attached.
> It links 'Init Syntax' to the ELisp manual Introduction node.

Thanks, installed on the release branch, and closing the bug.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.