Question on set-window-margins

Question on set-window-margins

[Nicolas P. Rougier (inria)]

When I set margins on a window using 'set-window-margins', it 
works as expected until I switched to another buffer and margins 
are then reset to 0 on both sides. If I switch back to the 
original buffer, margins stay at 0. Does that mean that margins 
are not "attached" to the window nor to the buffer ?

The name of the function suggest it is attached to window (even 
though nothing is really specified in the documentation)  but I 
wonder if the 'set-window-margins' is actually meant to be 
transient ?

To keep margins attached to a buffer, I'm using the 
'window-state-change-hook' and a buffer local margin definition 
but maybe I missed a point.

Nicolas

-- 
Nicolas P. Rougier —— www.labri.fr/perso/nrougier
Institute of Neurodegenerative Diseases, Bordeaux

Re: Question on set-window-margins

[Eli Zaretskii]

> From: "Nicolas P. Rougier (inria)" <nicolas.rougier@inria.fr>
> Date: Tue, 02 Jan 2024 18:58:51 +0100
> 
> 
> When I set margins on a window using 'set-window-margins', it 
> works as expected until I switched to another buffer and margins 
> are then reset to 0 on both sides. If I switch back to the 
> original buffer, margins stay at 0. Does that mean that margins 
> are not "attached" to the window nor to the buffer ?
> 
> The name of the function suggest it is attached to window (even 
> though nothing is really specified in the documentation)  but I 
> wonder if the 'set-window-margins' is actually meant to be 
> transient ?
> 
> To keep margins attached to a buffer, I'm using the 
> 'window-state-change-hook' and a buffer local margin definition 
> but maybe I missed a point.

From the ELisp manual:

 -- Function: set-window-margins window left &optional right
     This function specifies the margin widths for window WINDOW, in
     character cell units.  The argument LEFT controls the left margin,
     and RIGHT controls the right margin (default ‘0’).

     If WINDOW is not large enough to accommodate margins of the desired
     width, this leaves the margins of WINDOW unchanged.

     The values specified here may be later overridden by invoking
     ‘set-window-buffer’ (*note Buffers and Windows::) on WINDOW with
     its KEEP-MARGINS argument ‘nil’ or omitted.

Re: Question on set-window-margins

[Nicolas P. Rougier (inria)]

Eli Zaretskii [2024-01-02 at 21:20] wrote:
> From the ELisp manual:
> 
>  -- Function: set-window-margins window left &optional right
>      This function specifies the margin widths for window 
>      WINDOW, in
>      character cell units.  The argument LEFT controls the left 
>      margin,
>      and RIGHT controls the right margin (default ‘0’).
> 
>      If WINDOW is not large enough to accommodate margins of the 
>      desired
>      width, this leaves the margins of WINDOW unchanged.
> 
>      The values specified here may be later overridden by 
>      invoking
>      ‘set-window-buffer’ (*note Buffers and Windows::) on WINDOW 
>      with
>      its KEEP-MARGINS argument ‘nil’ or omitted.

Thanks. The last paragraph is actually missing from function 
definition on 29.1 hence my question. 

Nicolas

-- 
Nicolas P. Rougier —— www.labri.fr/perso/nrougier
Institute of Neurodegenerative Diseases, Bordeaux

Re: Question on set-window-margins

[Eli Zaretskii]

> From: "Nicolas P. Rougier (inria)" <nicolas.rougier@inria.fr>
> Cc: emacs-devel@gnu.org
> Date: Tue, 02 Jan 2024 20:46:14 +0100
> 
> 
> Eli Zaretskii [2024-01-02 at 21:20] wrote:
> > From the ELisp manual:
> > 
> >  -- Function: set-window-margins window left &optional right
> >      This function specifies the margin widths for window 
> >      WINDOW, in
> >      character cell units.  The argument LEFT controls the left 
> >      margin,
> >      and RIGHT controls the right margin (default ‘0’).
> > 
> >      If WINDOW is not large enough to accommodate margins of the 
> >      desired
> >      width, this leaves the margins of WINDOW unchanged.
> > 
> >      The values specified here may be later overridden by 
> >      invoking
> >      ‘set-window-buffer’ (*note Buffers and Windows::) on WINDOW 
> >      with
> >      its KEEP-MARGINS argument ‘nil’ or omitted.
> 
> Thanks. The last paragraph is actually missing from function 
> definition on 29.1 hence my question. 

Sorry, I don't understand what you mean by "missing from function
definition".  Please elaborate.

Re: Question on set-window-margins

[Yuan Fu]

> On Jan 2, 2024, at 7:23 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: "Nicolas P. Rougier (inria)" <nicolas.rougier@inria.fr>
>> Cc: emacs-devel@gnu.org
>> Date: Tue, 02 Jan 2024 20:46:14 +0100
>> 
>> 
>> Eli Zaretskii [2024-01-02 at 21:20] wrote:
>>> From the ELisp manual:
>>> 
>>> -- Function: set-window-margins window left &optional right
>>>     This function specifies the margin widths for window 
>>>     WINDOW, in
>>>     character cell units.  The argument LEFT controls the left 
>>>     margin,
>>>     and RIGHT controls the right margin (default ‘0’).
>>> 
>>>     If WINDOW is not large enough to accommodate margins of the 
>>>     desired
>>>     width, this leaves the margins of WINDOW unchanged.
>>> 
>>>     The values specified here may be later overridden by 
>>>     invoking
>>>     ‘set-window-buffer’ (*note Buffers and Windows::) on WINDOW 
>>>     with
>>>     its KEEP-MARGINS argument ‘nil’ or omitted.
>> 
>> Thanks. The last paragraph is actually missing from function 
>> definition on 29.1 hence my question. 
> 
> Sorry, I don't understand what you mean by "missing from function
> definition".  Please elaborate.

I think Nicolas means that the last paragraph isn’t present in the docstring of set-window-margin. That paragraph is only in the manual. It might be a good idea to mention this caveat in the docstring.

Yuan

Re: Question on set-window-margins

[Nicolas P. Rougier (inria)]

Yuan Fu [2024-01-02 at 19:42] wrote:
> 
> I think Nicolas means that the last paragraph isn’t present in 
> the
> docstring of set-window-margin. That paragraph is only in the
> manual. It might be a good idea to mention this caveat in the
> docstring.

Exactly.

Nicolas

-- 
Nicolas P. Rougier —— www.labri.fr/perso/nrougier
Institute of Neurodegenerative Diseases, Bordeaux

Re: Question on set-window-margins

[Eli Zaretskii]

> From: "Nicolas P. Rougier (inria)" <nicolas.rougier@inria.fr>
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> Date: Wed, 03 Jan 2024 06:50:17 +0100
> 
> 
> Yuan Fu [2024-01-02 at 19:42] wrote:
> > 
> > I think Nicolas means that the last paragraph isn’t present in 
> > the
> > docstring of set-window-margin. That paragraph is only in the
> > manual. It might be a good idea to mention this caveat in the
> > docstring.
> 
> Exactly.

I added that, but I'm always surprised by people jumping to
conclusions without studying both the relevant doc string(s) and the
relevant descriptions in the manual.  Doc strings and the manuals have
different purposes and different size limitations, so it's
unreasonable to expect only one of them to include all of the
important information, let alone that of secondary importance,
caveats, etc.

Please always look up the functions you are interested in both in the
built-in help and in the manual, before you conclude that something is
strange or undocumented.

Re: Question on set-window-margins

[Nicolas P. Rougier (inria)]

Eli Zaretskii [2024-01-03 at 15:15] wrote:
> I added that, but I'm always surprised by people jumping to
> conclusions without studying both the relevant doc string(s) and 
> the
> relevant descriptions in the manual.  Doc strings and the 
> manuals have
> different purposes and different size limitations, so it's
> unreasonable to expect only one of them to include all of the
> important information, let alone that of secondary importance,
> caveats, etc.
> 
> Please always look up the functions you are interested in both 
> in the
> built-in help and in the manual, before you conclude that 
> something is
> strange or undocumented.

Well noted. But the manual needs some modification as well 
(suppressing "full"):

4.1 Finding More Information:

If you are interested, you can get the full documentation of any 
Emacs Lisp function at any time by typing C-h f and then the name 
of the function (and then RET). Similarly, you can get the full 
documentation for a variable by typing C-h v and then the name of 
the variable (and then RET). 

Nicolas

-- 
Nicolas P. Rougier —— www.labri.fr/perso/nrougier
Institute of Neurodegenerative Diseases, Bordeaux

Re: Question on set-window-margins

[John Yates]

On Wed, Jan 3, 2024 at 8:16 AM Eli Zaretskii <eliz@gnu.org> wrote:
>
> Doc strings and the manuals have
> different purposes and different size limitations, so it's
> unreasonable to expect only one of them to include all of the
> important information, let alone that of secondary importance,
> caveats, etc.

Might there be a way for a doc string to include an unobtrusive
small link to the full documentation?

Re: Question on set-window-margins

[Eli Zaretskii]

> From: "Nicolas P. Rougier (inria)" <nicolas.rougier@inria.fr>
> Cc: casouri@gmail.com, emacs-devel@gnu.org
> Date: Wed, 03 Jan 2024 15:05:13 +0100
> 
> > Please always look up the functions you are interested in both in
> > the built-in help and in the manual, before you conclude that
> > something is strange or undocumented.
> 
> Well noted. But the manual needs some modification as well 
> (suppressing "full"):
> 
> 4.1 Finding More Information:
> 
> If you are interested, you can get the full documentation of any 
> Emacs Lisp function at any time by typing C-h f and then the name 
> of the function (and then RET). Similarly, you can get the full 
> documentation for a variable by typing C-h v and then the name of 
> the variable (and then RET). 

I don't see what's wrong with that text (which is in the Emacs Lisp
Introduction manual).

Re: Question on set-window-margins

[Eli Zaretskii]

> From: John Yates <john@yates-sheets.org>
> Date: Wed, 3 Jan 2024 10:11:38 -0500
> Cc: "Nicolas P. Rougier (inria)" <nicolas.rougier@inria.fr>, casouri@gmail.com, emacs-devel@gnu.org
> 
> On Wed, Jan 3, 2024 at 8:16 AM Eli Zaretskii <eliz@gnu.org> wrote:
> >
> > Doc strings and the manuals have
> > different purposes and different size limitations, so it's
> > unreasonable to expect only one of them to include all of the
> > important information, let alone that of secondary importance,
> > caveats, etc.
> 
> Might there be a way for a doc string to include an unobtrusive
> small link to the full documentation?

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.

Re: Question on set-window-margins

[Nicolas P. Rougier (inria)]

Eli Zaretskii [2024-01-03 at 18:46] wrote:
> > If you are interested, you can get the full documentation of 
> > any 
> > Emacs Lisp function at any time by typing C-h f and then the 
> > name 
> > of the function (and then RET). Similarly, you can get the 
> > full 
> > documentation for a variable by typing C-h v and then the name 
> > of 
> > the variable (and then RET). 
> 
> I don't see what's wrong with that text (which is in the Emacs 
> Lisp
> Introduction manual).

I (maybe wrongly) understand from that sentence that I can get 
full documentation for a function by typing 'C-h f' which is 
obviously not the case because, as you underlined, other 
information is available in the manual. The "full" is misleading.

Nicolas

-- 
Nicolas P. Rougier —— www.labri.fr/perso/nrougier
Institute of Neurodegenerative Diseases, Bordeaux

Re: Question on set-window-margins

[Eli Zaretskii]

> From: "Nicolas P. Rougier (inria)" <nicolas.rougier@inria.fr>
> Cc: casouri@gmail.com, emacs-devel@gnu.org
> Date: Wed, 03 Jan 2024 18:24:03 +0100
> 
> 
> Eli Zaretskii [2024-01-03 at 18:46] wrote:
> > > If you are interested, you can get the full documentation of 
> > > any 
> > > Emacs Lisp function at any time by typing C-h f and then the 
> > > name 
> > > of the function (and then RET). Similarly, you can get the 
> > > full 
> > > documentation for a variable by typing C-h v and then the name 
> > > of 
> > > the variable (and then RET). 
> > 
> > I don't see what's wrong with that text (which is in the Emacs 
> > Lisp
> > Introduction manual).
> 
> I (maybe wrongly) understand from that sentence that I can get 
> full documentation for a function by typing 'C-h f' which is 
> obviously not the case because, as you underlined, other 
> information is available in the manual. The "full" is misleading.

That's not the manual from which to learn this stuff.

Re: Question on set-window-margins

[Nicolas P. Rougier (inria)]

Eli Zaretskii [2024-01-03 at 19:28] wrote:
> That's not the manual from which to learn this stuff.

C-h f describe-function

Display the full documentation of FUNCTION (a symbol).
When called from Lisp, FUNCTION may also be a function object.

Nicolas

-- 
Nicolas P. Rougier —— www.labri.fr/perso/nrougier
Institute of Neurodegenerative Diseases, Bordeaux

RE: [External] : Re: Question on set-window-margins

[Drew Adams]

> > Might there be a way for a doc string to include an unobtrusive
> > small link to the full documentation?

This has been suggested multiple times over the years.

I added it to *Help* in my library help-fns+.el in 2011.

A user option controls whether such a link is shown, and
if so, which manuals to check, and whether to check
automatically or only when you click the link.

> We do that when there are too many details to have them
> in the doc string.

Other reasons to do it are that the manual can provide
additional context, links, etc.  It's not only about
more details about the thing described in *Help*.

> Otherwise, there's no need for a link because typing 'i' in
> the *Help* buffer will show the corresponding documentation in the
> manual.

No need?  Can't argue about need.  But a link is more
obvious than knowing, or checking to find, binding `i'.
IOW, need or no need, a link to the manuals is useful.
___

https://www.emacswiki.org/emacs/HelpPlus#LinksToManuals

https://www.emacswiki.org/emacs/download/help-fns%2b.el

Re: Question on set-window-margins

[Jeremy Bryant]

Nicolas, you may be also interested in the following convenient way to access the
relevant manual (rather than the docstring)

C-h S set-window-margins

Because C-h S is bound to info-lookup-symbol.

"
Look up and display documentation of SYMBOL in the relevant Info manual.
SYMBOL should be an identifier: a function or method, a macro, a variable,
a data type, a class, etc.
"

I hope this is a useful suggestion



"Nicolas P. Rougier (inria)" <nicolas.rougier@inria.fr> writes:

> Eli Zaretskii [2024-01-03 at 19:28] wrote:
>> That's not the manual from which to learn this stuff.
>
> C-h f describe-function
>
> Display the full documentation of FUNCTION (a symbol).
> When called from Lisp, FUNCTION may also be a function object.
>
> Nicolas

Re: Question on set-window-margins

[Nicolas P. Rougier (inria)]

Jeremy Bryant [2024-01-03 at 21:52] wrote:
> Nicolas, you may be also interested in the following convenient 
> way to access the
> relevant manual (rather than the docstring)
> 
> C-h S set-window-margins
> 
> Because C-h S is bound to info-lookup-symbol.
> 
> "
> Look up and display documentation of SYMBOL in the relevant Info 
> manual.
> SYMBOL should be an identifier: a function or method, a macro, a 
> variable,
> a data type, a class, etc.
> "

It is, I didn't know the binding. Thanks.

Nicolas

-- 
Nicolas P. Rougier —— www.labri.fr/perso/nrougier
Institute of Neurodegenerative Diseases, Bordeaux

Re: Question on set-window-margins

[John Yates]

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.  No link?  Then the doc string is equivalent to what one
will find in the manual (or the function is not documented in any
manual).  Link present?  Then clearly there exists documentation
somewhere that goes beyond what is included in the doc string.

When I run describe function, along with the signature and the
actual doc string, I get additional boilerplate:

xxx-yyy-zzz is an autoloaded interactive byte-compiled Lisp
function in ‘xxx.el’.

<SIGNATURE>

<DOC STRING>

  Probably introduced at or before Emacs version ee.v.

Help-mode binds 's' to help-view-source.  That has prevented
us from supplying a visible link to the source.  Similarly, I
suggest that, when there exists a relevant, more detailed bit
of documentation, the first line could be extended to read:

xxx-yyy-zzz is an autoloaded interactive byte-compiled Lisp
function in ‘xxx.el’.  [full doc]

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.

Re: Question on set-window-margins

[Yuan Fu]

> On Jan 4, 2024, at 4:52 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> 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.

Helpful.el automatically inserts a button that links to the manual entry if it can find the symbol in the manual. It’s probably not perfect, but I frequently found it to be, well, helpful ;-)

The test function is defined as

(defun helpful--in-manual-p (sym)
  "Return non-nil if SYM is in an Info manual."
  (let ((completions
         (cl-letf (((symbol-function #'message)
                    (lambda (_format-string &rest _args))))
           (info-lookup->completions 'symbol 'emacs-lisp-mode))))
    (-when-let (buf (get-buffer " temp-info-look"))
      (kill-buffer buf))
    (or (assoc sym completions)
        (assoc-string sym completions))))

Yuan

Re: Question on set-window-margins

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Thu, 4 Jan 2024 16:25:26 -0800
> Cc: John Yates <john@yates-sheets.org>,
>  "Nicolas P. Rougier (inria)" <nicolas.rougier@inria.fr>,
>  emacs-devel@gnu.org
> 
> Helpful.el automatically inserts a button that links to the manual entry if it can find the symbol in the manual. It’s probably not perfect, but I frequently found it to be, well, helpful ;-)
> 
> The test function is defined as
> 
> (defun helpful--in-manual-p (sym)
>   "Return non-nil if SYM is in an Info manual."
>   (let ((completions
>          (cl-letf (((symbol-function #'message)
>                     (lambda (_format-string &rest _args))))
>            (info-lookup->completions 'symbol 'emacs-lisp-mode))))
>     (-when-let (buf (get-buffer " temp-info-look"))
>       (kill-buffer buf))
>     (or (assoc sym completions)
>         (assoc-string sym completions))))

Why not use the same code as in help-goto-info?

Re: Question on set-window-margins

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > 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.

This is true, but I would state it in a stronger way.  You can't write
a good manual by concatenating doc strings.  A doc string describes
one thing.  A good manual is not composed of pieces, each about one
thing.  That's not good writing for a manual.

See the GNU Coding Standards for more about this point, and how to
write a good manual.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)