GNU bug report logs - #3314
23.0.93; Emacs manual, node RegPos

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 3314 in the body.
You can then email your comments to 3314 AT debbugs.gnu.org in the normal way.

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

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <emacs-pretest-bug <at> gnu.org>
Subject: 23.0.93; Emacs manual, node RegPos
Date: Sat, 16 May 2009 15:29:42 -0700

1. The node name, `RegPos', is not too good. There is no need for
camelCase in node names, and `Reg Pos' would still be unnecessarily
abbreviated. Likewise, for the other register nodes (RegText, RegRect
etc.).  Emacs does not normally name Info nodes this way. Good node
names let you find appropriate nodes using completion etc.
 
2. Please mention the use of a prefix arg for`C-x r SPC'.  The doc
string for this command mentions `C-u', but the manual does not.
 
3. Please mention (here) that `C-x r j' will jump to any register that
saves a position (file, window/frame config), not just one created by
`C-x r SPC'. And, in particular, if you used a prefix arg with `C-x r
SPC', the saved frame config is restored.
 
4. Consider reorganizing the register doc, to mention that some
register commands store positional information (e.g. point, file,
window config, frame config), and others do not (text, rectangle,
number).  Mention that you can return to any saved position using `C-x
r j' - i.e., this works for point, file, and so on, and you can insert
any non-positional information using `C-x r i'.
 
IOW, divide the register commands into two groups: positional and
non-positional information.  For the first group, what you do with the
stored information is revisit the location.  For the second group,
what you do with the stored information is either modify it
(e.g. increment a number) or insert it as text in a buffer.  This
provides an overview, and makes clear that (1) `C-x r j' applies to
any saved positional information, and (2) `C-x r i' applies to any
non-positional information.
 
In GNU Emacs 23.0.93.1 (i386-mingw-nt5.1.2600)
 of 2009-05-02 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

Message #10 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Richard M Stallman <rms <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>, 3314 <at> debbugs.gnu.org
Cc: emacs-pretest-bug <at> gnu.org
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Sun, 17 May 2009 13:23:43 -0400

The reason for abbreviating some node names is to prevent the node's
first line (in the Info file) from wrapping in an ugly way.

Message #20 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <rms <at> gnu.org>, <3314 <at> debbugs.gnu.org>
Cc: <emacs-pretest-bug <at> gnu.org>
Subject: RE: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Sun, 17 May 2009 10:38:46 -0700

> The reason for abbreviating some node names is to prevent the node's
> first line (in the Info file) from wrapping in an ugly way.

Not a good solution, IMO.

Even if no good solution for the wrapping problem could be found, it is more
important that nodes have helpful names than that wrapping be avoided.

And a name can be helpful without being overly long.

And this and the other node names in this section would not be longer than most
if named normally: `Positional Register' as a  substitute for `RegPos' is not
longer than most other nodes.

I suspect that the reason we have RegPos and company is simply an oversight -
perhaps laziness or unconcern on the part of whoever named them.

Further evidence that this is an oversight is that the author didn't even use
`Reg Pos'. There is zero reason to use camelCase here.

Message #30 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 3314 <at> debbugs.gnu.org, <rms <at> gnu.org>, emacs-pretest-bug <at> gnu.org
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Sun, 17 May 2009 21:45:45 +0300

>> The reason for abbreviating some node names is to prevent the node's
>> first line (in the Info file) from wrapping in an ugly way.
>
> Not a good solution, IMO.
>
> Even if no good solution for the wrapping problem could be found, it is more
> important that nodes have helpful names than that wrapping be avoided.
>
> And a name can be helpful without being overly long.
>
> And this and the other node names in this section would not be longer than most
> if named normally: `Positional Register' as a  substitute for `RegPos' is not
> longer than most other nodes.

In your original bug report you wrote:

  Good node names let you find appropriate nodes using completion etc.

However, the name `Positional Register' makes it harder to find all
register related nodes using completion because it doesn't begin
with a common word.  Currently these node names begin with a common prefix
`Reg'.  So it would be better if they all had a common prefix that is
a complete and clear word `Register':

  RegPos     -> Register Positions
  RegText    -> Register Text
  RegRect    -> Register Rectangles
  RegConfig  -> Register Configurations
  RegNumbers -> Register Numbers
  RegFiles   -> Register Files

I see no problems with this change because an Info "breadcrumb" line
is still short, e.g.

  (emacs)Top > Registers > Register Rectangles

and the header line will fit into 80 columns as well.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #40 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Juri Linkov'" <juri <at> jurta.org>
Cc: <3314 <at> debbugs.gnu.org>, <rms <at> gnu.org>,
        <emacs-pretest-bug <at> gnu.org>
Subject: RE: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Sun, 17 May 2009 12:00:05 -0700

> In your original bug report you wrote:
> 
>   Good node names let you find appropriate nodes using completion etc.
> 
> However, the name `Positional Register' makes it harder to find all
> register related nodes using completion because it doesn't begin
> with a common word.  Currently these node names begin with a 
> common prefix `Reg'.  So it would be better if they all had a
> common prefix that is a complete and clear word `Register':
> 
>   RegPos     -> Register Positions
>   RegText    -> Register Text
>   RegRect    -> Register Rectangles
>   RegConfig  -> Register Configurations
>   RegNumbers -> Register Numbers
>   RegFiles   -> Register Files

I agree 100%. Thanks.

Message #50 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Drew Adams'" <drew.adams <at> oracle.com>, "'Juri Linkov'" <juri <at> jurta.org>
Cc: <3314 <at> debbugs.gnu.org>, <rms <at> gnu.org>,
        <emacs-pretest-bug <at> gnu.org>
Subject: RE: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Sun, 17 May 2009 12:05:27 -0700

> >   RegPos     -> Register Positions
> >   RegText    -> Register Text
> >   RegRect    -> Register Rectangles
> >   RegConfig  -> Register Configurations
> >   RegNumbers -> Register Numbers
> >   RegFiles   -> Register Files
> 
> I agree 100%. Thanks.

Oops - except it would be better not to let those names suggest that "register"
is used here as an adjective. It's not about a register position; it's about a
positional register.

So perhaps:

Register, Position
Register, Text
Register, Rectangle
Register, Frames/Windows
Register, Number
Register, File

All use the singular except Frames or Windows, which is a (singular)
configuration of frames or windows.

"Configuration" alone is not too helpful.
"Frames/Windows" is only 1 char longer.
"Frames or Windows" is 4 chars longer.

Message #60 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Juri Linkov'" <juri <at> jurta.org>
Cc: <3314 <at> debbugs.gnu.org>, <rms <at> gnu.org>,
        <emacs-pretest-bug <at> gnu.org>
Subject: RE: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Sun, 17 May 2009 12:47:21 -0700

> >> >   RegPos     -> Register Positions
> >> >   RegText    -> Register Text
> >> >   RegRect    -> Register Rectangles
> >> >   RegConfig  -> Register Configurations
> >> >   RegNumbers -> Register Numbers
> >> >   RegFiles   -> Register Files
> >>
> >> I agree 100%. Thanks.
> >
> > Oops - except it would be better not to let those names 
> suggest that "register"
> > is used here as an adjective. It's not about a register 
> position; it's about a
> > positional register.
> >
> > So perhaps:
> >
> > Register, Position
> > Register, Text
> > Register, Rectangle
> > Register, Frames/Windows
> > Register, Number
> > Register, File
> 
> You cannot use periods, commas, colons or parentheses within 
> a node name.

Then:

Register - Position
Register - Text
Register - Rectangle
Register - Frames/Windows
Register - Number
Register - File

If the nound comes first, for completion purposes etc., then some separator must
be used to eliminate interpretation of the same word ("register") as an
adjective.

However, elsewhere we generally do not bother much to put the noun first, to
facilitate completion etc. We use, for example:

Basic Parameters
Position Parameters
Size Parameters
Layout Parameters
...

not

Parameters - Basic
Parameters - Position
Parameters - Size
Parameters - Layout

Message #65 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: <3314 <at> debbugs.gnu.org>, <rms <at> gnu.org>,
        <emacs-pretest-bug <at> gnu.org>
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Sun, 17 May 2009 22:17:19 +0300

>> >   RegPos     -> Register Positions
>> >   RegText    -> Register Text
>> >   RegRect    -> Register Rectangles
>> >   RegConfig  -> Register Configurations
>> >   RegNumbers -> Register Numbers
>> >   RegFiles   -> Register Files
>>
>> I agree 100%. Thanks.
>
> Oops - except it would be better not to let those names suggest that "register"
> is used here as an adjective. It's not about a register position; it's about a
> positional register.
>
> So perhaps:
>
> Register, Position
> Register, Text
> Register, Rectangle
> Register, Frames/Windows
> Register, Number
> Register, File

You cannot use periods, commas, colons or parentheses within a node name.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #80 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: <3314 <at> debbugs.gnu.org>, <rms <at> gnu.org>,
        <emacs-pretest-bug <at> gnu.org>
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Mon, 18 May 2009 00:27:32 +0300

> Then:
>
> Register - Position
> Register - Text
> Register - Rectangle
> Register - Frames/Windows
> Register - Number
> Register - File

Can we find a grammatical form that would allow putting the word
`Register' first?  I imagine the following variant is acceptable:

Register for Position
Register for Text
Register for Rectangle
Register for Frames/Windows
Register for Number
Register for File

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #90 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Juri Linkov'" <juri <at> jurta.org>
Cc: <3314 <at> debbugs.gnu.org>, <rms <at> gnu.org>,
        <emacs-pretest-bug <at> gnu.org>
Subject: RE: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Sun, 17 May 2009 14:38:27 -0700

> > Register - Position
> > Register - Text
> > Register - Rectangle
> > Register - Frames/Windows
> > Register - Number
> > Register - File
> 
> Can we find a grammatical form that would allow putting the word
> `Register' first?  I imagine the following variant is acceptable:
> 
> Register for Position
> Register for Text
> Register for Rectangle
> Register for Frames/Windows
> Register for Number
> Register for File

Sure, that's even clearer, though a bit longer.

Message #100 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 3314 <at> debbugs.gnu.org, "'Juri Linkov'" <juri <at> jurta.org>,
        rms <at> gnu.org, emacs-pretest-bug <at> gnu.org
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Sun, 17 May 2009 23:24:57 -0400

> However, elsewhere we generally do not bother much to put the noun
> first, to facilitate completion etc.  We use, for example:

Indeed: using such "common prefix for completion" principles amounts to
imposing a hierarchical structure, which we already have elsewhere.
So I don't think it's very useful: if you want to see nodes that relate
to "Register", you can simply do "m Regi TAB RET" and that node lists
pretty much the entries you've given as example.

OTOH I agree that it would be good to replace "RegPos" with something
more explicit such as "Position Registers".

FWIW (assuming more explicit names are used) you can also use
"*Register" and then hit TAB to see the entries that contain "Register"
somewhere.  This also reduces the need for such common prefixes.

This doesn't mean that common prefixes aren't good, but just that they
are very secondary in this case.  Clear names are much more important.


        Stefan

Message #110 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Richard M Stallman <rms <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: juri <at> jurta.org, 3314 <at> debbugs.gnu.org, emacs-pretest-bug <at> gnu.org
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Mon, 18 May 2009 12:44:40 -0400

    However, elsewhere we generally do not bother much to put the noun first, to
    facilitate completion etc. We use, for example:

    Basic Parameters
    Position Parameters

I used to put the common word last
to facilitate completion in the menu which those nodes appear in.
Just `ba' will complete to `Basic Parameters'.  Just
`p' will complete to `Position Parameters'.

Message #115 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Richard M Stallman <rms <at> gnu.org>
To: Juri Linkov <juri <at> jurta.org>, 3314 <at> debbugs.gnu.org
Cc: drew.adams <at> oracle.com, 3314 <at> debbugs.gnu.org,
        emacs-pretest-bug <at> gnu.org
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Mon, 18 May 2009 12:45:26 -0400

    Register for Position
    Register for Text
    Register for Rectangle
    Register for Frames/Windows

These are so long they will surely make the first lines too long.
(Putting `Register' first is misguided in the first place.)

Message #130 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Rodgers <kevin.d.rodgers <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Cc: emacs-pretest-bug <at> gnu.org
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Thu, 21 May 2009 22:36:28 -0600

Drew Adams wrote:
>> The reason for abbreviating some node names is to prevent the node's
>> first line (in the Info file) from wrapping in an ugly way.
> 
> Not a good solution, IMO.
> 
> Even if no good solution for the wrapping problem could be found, it is more
> important that nodes have helpful names than that wrapping be avoided.

Determine how many characters can be displayed, truncate the node name 
accordingly, and add the help-echo text property with the full node name.

-- 
Kevin Rodgers
Denver, Colorado, USA

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 'Juri Linkov' <juri <at> jurta.org>, rms <at> gnu.org,
	Drew Adams <drew.adams <at> oracle.com>, 3314 <at> debbugs.gnu.org
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Mon, 11 Jul 2011 17:42:41 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> OTOH I agree that it would be good to replace "RegPos" with something
> more explicit such as "Position Registers".

I have now renamed all these nodes using this naming scheme.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

From: Richard Stallman <rms <at> gnu.org>
To: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Cc: juri <at> jurta.org, monnier <at> iro.umontreal.ca, drew.adams <at> oracle.com,
	3314 <at> debbugs.gnu.org
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Tue, 12 Jul 2011 15:06:38 -0400

    > OTOH I agree that it would be good to replace "RegPos" with something
    > more explicit such as "Position Registers".

    I have now renamed all these nodes using this naming scheme.

The reason I wrote name such as RegPos was to make the first
line of the Info file short enough to fit in a screen line.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use free telephony http://directory.fsf.org/category/tel/

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: rms <at> gnu.org
Cc: juri <at> jurta.org, monnier <at> iro.umontreal.ca, drew.adams <at> oracle.com,
	3314 <at> debbugs.gnu.org
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Tue, 12 Jul 2011 21:34:21 +0200

Richard Stallman <rms <at> gnu.org> writes:

> The reason I wrote name such as RegPos was to make the first
> line of the Info file short enough to fit in a screen line.

The first line of the Info file?

Oh, the next/prev line?  Yes, after the renaming, there's one line
that's longer than 80 characters:

File: emacs,  Node: Text Registers,  Next: Rectangle Registers,  Prev: Position Registers,  Up: Registers

Hm...

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: rms <at> gnu.org
Cc: juri <at> jurta.org, monnier <at> iro.umontreal.ca, drew.adams <at> oracle.com,
	3314 <at> debbugs.gnu.org
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Tue, 12 Jul 2011 21:42:33 +0200

However, there's lots of these too-long lines in the emacs info files:

File: emacs,  Node: Blank Lines,  Next: Continuation Lines,  Prev: Basic Help,  Up: Basic
File: emacs,  Node: Minibuffer Edit,  Next: Completion,  Prev: Minibuffer File,  Up: Minibuffer

etc etc.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

From: Richard Stallman <rms <at> gnu.org>
To: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Cc: 3314 <at> debbugs.gnu.org
Subject: Re: bug#3314: 23.0.93; Emacs manual, node RegPos
Date: Wed, 13 Jul 2011 14:32:08 -0400

    > The reason I wrote name such as RegPos was to make the first
    > line of the Info file short enough to fit in a screen line.

    The first line of the Info file?

Sorry, I meant the first line of the node -- as you figured out.

    However, there's lots of these too-long lines in the emacs info files:

That is true.  I did not push to get rid of all of them.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use free telephony http://directory.fsf.org/category/tel/

Previous Next

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