GNU bug report logs - #15375
24.3.50; Elisp manual: mention what units are used for window margin functions

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 15375 in the body.
You can then email your comments to 15375 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: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.3.50; Elisp manual: mention what units are used for window margin
 functions
Date: Fri, 13 Sep 2013 15:17:31 -0700 (PDT)

(elisp) `Display Margins` talks a lot about window margins, but AFAICT
it never once says which units are used for the functions and variables
described there.  I'm guessing the unit is `frame-char-width', but Emacs
should tell us explicitly here.

Moreover, we don't even tell users what a nil value means, as opposed
to a whole number.

For example, right now, `M-: (window-margins)' returns `(nil)' for me,
which corresponds to both LEFT and RIGHT being nil.  What does a nil
value mean for each of these?


In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-08-31 on ODIEONE
Bzr revision: 114088 rgm <at> gnu.org-20130901021232-sazo0qla2qgcko95
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 'CFLAGS=-O0 -g3' LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15375 <at> debbugs.gnu.org
Subject: Re: bug#15375: 24.3.50;
 Elisp manual: mention what units are used for window margin functions
Date: Sat, 14 Sep 2013 12:27:52 +0300

> Date: Fri, 13 Sep 2013 15:17:31 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> (elisp) `Display Margins` talks a lot about window margins, but AFAICT
> it never once says which units are used for the functions and variables
> described there.  I'm guessing the unit is `frame-char-width', but Emacs
> should tell us explicitly here.

The units are character cells (a.k.a. "columns").

I fixed this in trunk revision 114279.

> Moreover, we don't even tell users what a nil value means, as opposed
> to a whole number.
> 
> For example, right now, `M-: (window-margins)' returns `(nil)' for me,
> which corresponds to both LEFT and RIGHT being nil.  What does a nil
> value mean for each of these?

Fixed that as well.

Thanks.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 15375 <at> debbugs.gnu.org
Subject: RE: bug#15375: 24.3.50; Elisp manual: mention what units are used for
 window margin functions
Date: Sat, 14 Sep 2013 08:18:38 -0700 (PDT)

> > (elisp) `Display Margins` talks a lot about window margins, but AFAICT
> > it never once says which units are used for the functions and variables
> > described there.  I'm guessing the unit is `frame-char-width', but Emacs
> > should tell us explicitly here.
> 
> The units are character cells (a.k.a. "columns").
> 
> I fixed this in trunk revision 114279.
> 
> > Moreover, we don't even tell users what a nil value means, as opposed
> > to a whole number.
> >
> > For example, right now, `M-: (window-margins)' returns `(nil)' for me,
> > which corresponds to both LEFT and RIGHT being nil.  What does a nil
> > value mean for each of these?
> 
> Fixed that as well.

Thanks.  Do you want me to close the bug, or do you want to?
(Dunno whether you wanted to keep it open for some reason.)

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15375 <at> debbugs.gnu.org
Subject: Re: bug#15375: 24.3.50;
 Elisp manual: mention what units are used for window margin functions
Date: Sat, 14 Sep 2013 18:29:36 +0300

> Date: Sat, 14 Sep 2013 08:18:38 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 15375 <at> debbugs.gnu.org
> 
> > > (elisp) `Display Margins` talks a lot about window margins, but AFAICT
> > > it never once says which units are used for the functions and variables
> > > described there.  I'm guessing the unit is `frame-char-width', but Emacs
> > > should tell us explicitly here.
> > 
> > The units are character cells (a.k.a. "columns").
> > 
> > I fixed this in trunk revision 114279.
> > 
> > > Moreover, we don't even tell users what a nil value means, as opposed
> > > to a whole number.
> > >
> > > For example, right now, `M-: (window-margins)' returns `(nil)' for me,
> > > which corresponds to both LEFT and RIGHT being nil.  What does a nil
> > > value mean for each of these?
> > 
> > Fixed that as well.
> 
> Thanks.  Do you want me to close the bug, or do you want to?
> (Dunno whether you wanted to keep it open for some reason.)

I left it open to allow you to review the changes.  You can do that
either by pointing your browser at
http://bzr.savannah.gnu.org/lh/emacs/trunk/annotate/head:/doc/lispref/display.texi
and going down to line 4160, or by waiting for the next binary
snapshot of the trunk.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 15375 <at> debbugs.gnu.org
Subject: RE: bug#15375: 24.3.50; Elisp manual: mention what units are used for
 window margin functions
Date: Sat, 14 Sep 2013 09:26:42 -0700 (PDT)

> I left it open to allow you to review the changes.  You can do that
> either by pointing your browser at
> http://bzr.savannah.gnu.org/lh/emacs/trunk/annotate/head:/doc/lispref/displa
> y.texi and going down to line 4160, or by waiting for the next binary
> snapshot of the trunk.

Thanks, and thanks for that URL & line #.

Looks good, but I have these minor suggestions, if you have the time:

1. Move the "(a.k.a.@: ``column'')" to the first occurrence of "character
cell".  I, for one, did not know the latter term, and wondered about it
until I got to that aka.

2. You can remove this part, as it is implied: "; if none of the two margins
exist, the function returns @code{(nil)}."  (It does not hurt, but in that
case please change "none" to "neither", to be clearer.)

3. You should add a comma before "and" in "The argument @var{left} controls
the left margin and @var{right} controls the right margin (default @code{0})."
               ,
Alternatively, you can use ";" instead of ", and", or split it into two
sentences.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15375-done <at> debbugs.gnu.org
Subject: Re: bug#15375: 24.3.50;
 Elisp manual: mention what units are used for window margin functions
Date: Sat, 14 Sep 2013 19:33:42 +0300

> Date: Sat, 14 Sep 2013 09:26:42 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 15375 <at> debbugs.gnu.org
> 
> 1. Move the "(a.k.a.@: ``column'')" to the first occurrence of "character
> cell".  I, for one, did not know the latter term, and wondered about it
> until I got to that aka.
> 
> 2. You can remove this part, as it is implied: "; if none of the two margins
> exist, the function returns @code{(nil)}."  (It does not hurt, but in that
> case please change "none" to "neither", to be clearer.)
> 
> 3. You should add a comma before "and" in "The argument @var{left} controls
> the left margin and @var{right} controls the right margin (default @code{0})."
>                ,
> Alternatively, you can use ";" instead of ", and", or split it into two
> sentences.

Done.

Previous Next

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