From: carlmarcos--- via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
To: Eli Zaretskii <eliz@gnu.org>
Cc: matt@rfc20.org, YE <yet@ego.team>,
uzibalqa@proton.me, larsi@gnus.org, 56870@debbugs.gnu.org
Subject: bug#56870: [PATCH] Re: bug#56870: company-dabbrev variable documentation
Date: Fri, 5 Aug 2022 13:36:35 +0200 (CEST) [thread overview]
Message-ID: <N8hmjWL--3-2@tutanota.com> (raw)
In-Reply-To: <83a68j0wwy.fsf@gnu.org>
Aug 5, 2022, 11:09 by eliz@gnu.org:
>> From: YE <yet@ego.team>
>> Cc: yet@ego.team, matt@rfc20.org, uzibalqa@proton.me, larsi@gnus.org,
>> 56870@debbugs.gnu.org
>> Date: Fri, 05 Aug 2022 12:10:33 +0300
>>
>> Eli Zaretskii <eliz@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.
>
next prev parent reply other threads:[~2022-08-05 11:36 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-08-01 3:54 bug#56870: company-dabbrev variable documentation uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-08-01 21:24 ` Matt Armstrong
2022-08-01 21:32 ` uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-08-01 21:49 ` Matt Armstrong
2022-08-01 21:55 ` uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-08-01 21:49 ` uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-08-02 10:20 ` Lars Ingebrigtsen
2022-08-02 10:34 ` uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-08-03 10:07 ` YE via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-08-03 18:41 ` Matt Armstrong
2022-08-03 18:50 ` carlmarcos--- via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-08-04 17:09 ` Matt Armstrong
[not found] ` <878ro4rl4l.fsf@rfc20.org-N8dpYwc----2>
2022-08-04 21:59 ` carlmarcos--- via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-08-04 16:06 ` bug#56870: [PATCH] " YE via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-08-04 16:41 ` Eli Zaretskii
2022-08-04 17:48 ` Matt Armstrong
2022-08-04 18:25 ` Eli Zaretskii
2022-08-05 9:10 ` YE via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-08-05 11:09 ` Eli Zaretskii
2022-08-05 11:36 ` carlmarcos--- via Bug reports for GNU Emacs, the Swiss army knife of text editors [this message]
2022-08-06 12:42 ` YE via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-08-06 13:19 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=N8hmjWL--3-2@tutanota.com \
--to=bug-gnu-emacs@gnu.org \
--cc=56870@debbugs.gnu.org \
--cc=carlmarcos@tutanota.com \
--cc=eliz@gnu.org \
--cc=larsi@gnus.org \
--cc=matt@rfc20.org \
--cc=uzibalqa@proton.me \
--cc=yet@ego.team \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
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 read-only IMAP folder(s) and NNTP newsgroup(s).