Re: Question on set-window-margins

[Eli Zaretskii]

> From: John Yates <john@yates-sheets.org>
> Date: Thu, 4 Jan 2024 07:29:00 -0500
> Cc: nicolas.rougier@inria.fr, casouri@gmail.com, emacs-devel@gnu.org
> 
> On Wed, Jan 3, 2024 at 11:49 AM Eli Zaretskii <eliz@gnu.org> wrote:
> >
> > We do that when there are too many details to have them in the doc
> > string.  Otherwise, there's no need for a link because typing 'i' in
> > the *Help* buffer will show the corresponding documentation in the
> > manual.
> 
> A visual link has the virtue that it makes immediately clear case
> holds.

It is infeasible to maintain such a link in a doc string of every
symbol which is described in the manual(s), and unreasonable to expect
us to add a link to each doc string of such symbols.  There are too
many of them, and keeping the links up-to-date given the changes in
the manuals is a lot of work.  So we do that judiciously, where we
think it's needed; a judgment call.

> No link?  Then the doc string is equivalent to what one
> will find in the manual

That's not that easy, in general, since the manuals include a lot of
background explanations, cross-references to other related places,
etc., which are not pertinent for doc strings, but are still useful in
some, mostly rare, situations.  In fact, this case in point is a small
demonstration of that, as the caveat that was in the manual is not
really directly related to the documentation of the function per se.

Anyway, feel free to come on-board and start working on improving the
documentation, including, but not limited to, this aspect.  Me, I just
got up from adding a decent documentation to help-quick command, which
originally said just this:

  Display a quick-help buffer.

And believe me, this is not a solitary example.  So please forgive me
if, with such inadequacy in mind, I consider the hair-splitting
arguments of this discussion not my first priority, not even the
second.