bug#3314: 23.0.93; Emacs manual, node RegPos

bug#3314: 23.0.93; Emacs manual, node RegPos

[Drew Adams]

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)'
 

bug#3314: 23.0.93; Emacs manual, node RegPos

[Richard M Stallman]

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.

bug#3314: 23.0.93; Emacs manual, node RegPos

[Drew Adams]

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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Juri Linkov]

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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Drew Adams]

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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Drew Adams]

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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Juri Linkov]

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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Drew Adams]

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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Juri Linkov]

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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Drew Adams]

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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Stefan Monnier]

> 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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Richard M Stallman]

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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Richard M Stallman]

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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Kevin Rodgers]

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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@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/

bug#3314: 23.0.93; Emacs manual, node RegPos

[Richard Stallman]

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

bug#3314: 23.0.93; Emacs manual, node RegPos

[Lars Magne Ingebrigtsen]

Richard Stallman <rms@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/

bug#3314: 23.0.93; Emacs manual, node RegPos

[Lars Magne Ingebrigtsen]

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/

bug#3314: 23.0.93; Emacs manual, node RegPos

[Richard Stallman]

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