Re: Documentation for "Clone Buffers" (corrected version)

Re: Documentation for "Clone Buffers" (corrected version)

[Alan Mackenzie]

[Re: My proposed patch to the Emacs manual, documenting the command
`clone-buffer'.]

On Sat, 28 Feb 2004, Richard Stallman wrote:

[Alan Mackenzie:]
>    I disagree.  I find clone-buffer exceptionally useful, as it is the
>    only way I know of having two *info* buffers displaying different
>    info files at the same time.

>The recommended method is to create one, do M-x rename-uniquely, then
>switch to some other buffer and do M-x info again.  This works for all
>sorts of special facilities.

Ah, right!  :-)  That's anything but user-friendly, though.  It's also
difficult to work out from the documentation.  I couldn't find any hint
of this procedure in the Info info pages, which is the first place I
looked, a year or three ago.

Maybe having two or more *info* buffers at a time is need peculiar to me,
but I would've thought it a fairly common requirement.  At the very
least, if people are going to be writing fine manuals, they'll probably
be wanting texinfo.info open in front of them.  (I still need to refer to
this continually, even after having written a moderate amount of
documentation.)  They'll also be wanting to have open the current version
of the info file whose source they're modifying.  At least, I do.  Making
it awkward having two *info*s (or at least awkward discovering how to) is
surely a discouragement from writing documentation.

I think a(n easy) method of opening a second *info* buffer is a Good
Thing.  Perhaps M-n `clone-buffer' isn't the most elegant command around,
but it's got to be better than M-x rename-uniquely etc., from a user's
point of view.

Incidentally, there isn't an entry in the Emacs manual's command index
for `rename-uniquely'.  Is this deliberate or is it a bug?

I'm rather surprised at the preference for leaving an Emacs command like
`clone-buffers' _undocumented_.  Does this perhaps signal an intention to
remove this command from Emacs?  If so, why?

I think the documentation in this area could do with improvement, and I'm
prepared to do more work on it myself, given pointers to the direction
this should take.

-- 
Alan Mackenzie (Munich, Germany)

Re: Documentation for "Clone Buffers" (corrected version)

[David Kastrup]

Alan Mackenzie <acm@muc.de> writes:

> [Re: My proposed patch to the Emacs manual, documenting the command
> `clone-buffer'.]
> 
> On Sat, 28 Feb 2004, Richard Stallman wrote:
> 
> [Alan Mackenzie:]
> >    I disagree.  I find clone-buffer exceptionally useful, as it is the
> >    only way I know of having two *info* buffers displaying different
> >    info files at the same time.
> 
> >The recommended method is to create one, do M-x rename-uniquely, then
> >switch to some other buffer and do M-x info again.  This works for all
> >sorts of special facilities.
> 
> Ah, right!  :-)  That's anything but user-friendly, though.  It's also
> difficult to work out from the documentation.  I couldn't find any hint
> of this procedure in the Info info pages, which is the first place I
> looked, a year or three ago.

Is the prefix argument of the following more user-friendly?

m runs the command Info-menu
   which is an interactive compiled Lisp function in `info'.
It is bound to m.
(Info-menu MENU-ITEM &optional FORK)

Go to the node pointed to by the menu item named (or abbreviated) MENU-ITEM.
The menu item should one of those listed in the current node's menu.
Completion is allowed, and the default menu item is the one point is on.
If FORK is non-nil (interactively with a prefix arg), show the node in
a new info buffer.  If FORK is a string, it is the name to use for the
new buffer.

[back]

Actually, it might be even more useful if the "d" command for going
to a new directory would also have this FORK functionality, since
_that_ is the point where one usually wants to start a new info
path.  And while we are at it, "t" could also make use of a FORK
prefix.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Documentation for "Clone Buffers" (corrected version)

[Alan Mackenzie]

On 9 Mar 2004, David Kastrup wrote:

Alan Mackenzie <acm@muc.de> writes:

>> [Re: My proposed patch to the Emacs manual, documenting the command
>> `clone-buffer'.]

>> On Sat, 28 Feb 2004, Richard Stallman wrote:

>> [Alan Mackenzie:]
>> >    I disagree.  I find clone-buffer exceptionally useful, as it is
>> >    the only way I know of having two *info* buffers displaying
>> >    different info files at the same time.

>> >The recommended method is to create one, do M-x rename-uniquely, then
>> >switch to some other buffer and do M-x info again.  This works for
>> >all sorts of special facilities.

>> Ah, right!  :-)  That's anything but user-friendly, though.  It's also
>> difficult to work out from the documentation.  I couldn't find any
>> hint of this procedure in the Info info pages, which is the first
>> place I looked, a year or three ago.

>Is the prefix argument of the following more user-friendly?

>m runs the command Info-menu
>   which is an interactive compiled Lisp function in `info'.
>It is bound to m.
>(Info-menu MENU-ITEM &optional FORK)

It is friendlier.  Sadly, it's not documented in the Info manual (at
least, it wasn't last time I looked).

[ .... ]

>Actually, it might be even more useful if the "d" command for going
>to a new directory would also have this FORK functionality, since
>_that_ is the point where one usually wants to start a new info
>path.  And while we are at it, "t" could also make use of a FORK
>prefix.

Yes, why don't we just FORK the whole lot of them?  n, p, u, m, d, f, l,
i, t, <CR>, as well as retaining M-n?

>David Kastrup

-- 
Alan Mackenzie (Munich, Germany)

Re: Documentation for "Clone Buffers" (corrected version)

[Luc Teirlinck]

Alan Mackenzie wrote:

   >Is the prefix argument of the following more user-friendly?

   >m runs the command Info-menu
   >   which is an interactive compiled Lisp function in `info'.
   >It is bound to m.
   >(Info-menu MENU-ITEM &optional FORK)

   It is friendlier.  Sadly, it's not documented in the Info manual (at
   least, it wasn't last time I looked).

I personally believe that M-n, C-u m and C-u g all should be
documented in info.texi.  If other people agree with this, then you
could do that, or I could.  (First we would have to double check
carefully that none of them already are, but I do not believe so.)

Sincerely,

Luc.

Re: Documentation for "Clone Buffers" (corrected version)

[Karl Berry]

    I personally believe that M-n, C-u m and C-u g all should be
    documented in info.texi.  

Yes.

    If other people agree with this, then you could do that, or I could.  

Please do (either of you).

    (First we would have to double check carefully that none of them
    already are, but I do not believe so.)

I don't see them either.

I'll also try to implement them in standalone Info, at some point.

Thanks,
k

Re: Documentation for "Clone Buffers" (corrected version)

[Luc Teirlinck]

What about the following patch to info.texi, documenting M-n, C-u m
and C-u g?  I could install in the Emacs CVS version of info.texi, if
desired.

===File ~/info.texi-diff====================================
*** info.texi.~1.39.~	Mon Mar  8 18:17:14 2004
--- info.texi	Sat Mar 13 20:22:30 2004
***************
*** 1004,1009 ****
--- 1004,1030 ----
  edit the Info file, so typing @kbd{e} there goes to the end of the
  current node.
  
+ @unnumberedsubsec @kbd{M-n} creates a cloned Info buffer in Emacs
+ 
+ @kindex M-n @r{(Info mode)}
+ @findex clone-buffer
+ @cindex cloning an Info buffer in Emacs
+   If you are reading Info in Emacs, you can select a new independent
+ Info buffer in another window by typing @kbd{M-n}.  The new buffer is
+ a ``cloned'' version of the old one.  (In Info mode, @kbd{M-n} runs
+ the Emacs command @code{clone-buffer}.)  The new buffer starts out
+ visiting the same node as the old one and initially has the same node
+ history list (@pxref{Help-Int, Intermediate Info commands}), but you
+ will be able to move independently between nodes in the two buffers.
+ 
+ @kindex C-u g @r{(Info mode)}
+ @kindex C-u m @r{(Info mode)}
+   In Emacs Info, you can also produce cloned Info buffers by giving a
+ numeric prefix argument to the @kbd{m} and @kbd{g} commands.  @kbd{C-u m}
+ and @kbd{C-u g} go to a new node in exactly the same way that @kbd{m}
+ and @kbd{g} do, but they do so in a new cloned Info buffer which they
+ select in another window.
+ 
  @node Info Search, Add, Advanced, Expert Info
  @comment  node-name,  next,  previous,  up
  @section How to search Info documents for specific subjects
============================================================

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> Date: Sat, 13 Mar 2004 20:32:30 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> What about the following patch to info.texi, documenting M-n, C-u m
> and C-u g?

Fine with me (but see the minor comments below).

> I could install in the Emacs CVS version of info.texi, if desired.

AFAIK, that's the master version of info.texi.

> + @unnumberedsubsec @kbd{M-n} creates a cloned Info buffer in Emacs

Do we really need a new section for this?

> + @kindex M-n @r{(Info mode)}
> + @findex clone-buffer
> + @cindex cloning an Info buffer in Emacs
> +   If you are reading Info in Emacs, you can select a new independent
> + Info buffer in another window by typing @kbd{M-n}.  The new buffer is
> + a ``cloned'' version of the old one.

The info.texi manual is for a novice user, since Info is for reading
the documentation, and a user who needs to use Info is generally not
an Emacs junky.  Even in its ``advanced'' sections, this manual
assumes a user who is not really ``advanced'' by the Emacs standards.
Such a user might not know what buffer cloning means.  Hence, I think
we should explain this term before we use it.

In any case, the first use of "cloned" should be in @dfn (and without
the quotes, as @dfn takes care of that).

We should also have an xref to the section in the Emacs manual that
describes cloned buffers, I think.

> + @kindex C-u g @r{(Info mode)}
> + @kindex C-u m @r{(Info mode)}
> +   In Emacs Info, you can also produce cloned Info buffers by giving a
> + numeric prefix argument to the @kbd{m} and @kbd{g} commands.  @kbd{C-u m}
> + and @kbd{C-u g} go to a new node in exactly the same way that @kbd{m}
> + and @kbd{g} do, but they do so in a new cloned Info buffer which they
> + select in another window.

I think this description should be copied (copied, not moved) into the
part that describes `g' and `m', and then the @kindex entries should
be removed.  To the best of my knowledge, no other place in the Emacs
manuals indexes commands starting with the prefix argument; we always
document the command itself and describe there the effect of the
argument.

Re: Documentation for "Clone Buffers" (corrected version)

[Luc Teirlinck]

Eli Zaretskii wrote:

   > + @unnumberedsubsec @kbd{M-n} creates a cloned Info buffer in Emacs

   Do we really need a new section for this?

and Karl Berry wrote:

   It is wrong to use @unnumberedsubsec in this way, incidentally.
   @subheading is the thing to use, except in this case I doubt any heading
   is necessary.  Especially if m/g get moved.

I believe the M-n stuff belongs in (info)Advanced.  A new section
seems clearly needed because I do not believe that the M-n stuff
belongs in any of the three other sections in that node.  I was not
the one who divided (info)Advanced up into @unnumberedsubsec the way
it is done.  It struck me as very unusual when I noticed it, but
apparently whoever wrote it thought that it looked better than the
alternatives in Info.  I ran texi2dvi on info.texi.  Reading info.texi
in hardcopy just makes no sense and it seems impossible to change
info.texi to make reading it in hardcopy useful.  So I believe the
Info version is what we have to worry about (for this particular
file).  Clearly we could change the structure of (info)Advanced.  In
particular, we could replace @unnumberedsubsec with @subheading.  I do
not know whether that makes any difference _in Info_.  If @subheading
looks better, just let me know and I will replace all four occurrences
of @unnumberedsubsec in (info)Advanced.  (The revised patch below does
not yet do that, just in case the original author had some reason to
use it.)

Eli Zaretskii wrote:

   Even in its ``advanced'' sections, this manual assumes a user who
   is not really ``advanced'' by the Emacs standards.

The material on manually editing .info files looks pretty advanced to me.

   Such a user might not know what buffer cloning means.  Hence, I think
   we should explain this term before we use it.

   In any case, the first use of "cloned" should be in @dfn (and without
   the quotes, as @dfn takes care of that).

   We should also have an xref to the section in the Emacs manual that
   describes cloned buffers, I think.

There is no such section.  That is exactly what started this thread.
Richard believes that it is not important enough to be documented in
the Emacs manual.  It is not documented in the Elisp manual either.
(Maybe it should be?)  The only documentation is the docstring of
`clone-buffer', which right now is very incomplete and does not even
mention the interactive use.  I proposed a patch to simple.el that
would at least provide complete documentation in that docstring, on
Thursday.  I got no reaction.  I do not know whether that means that
it is OK to apply it now.

I just used "cloned" as a jargon word, not as a technical term.  In the
revised patch below, I removed all references to the word.

   I think this description should be copied (copied, not moved) into the
   part that describes `g' and `m', and then the @kindex entries should
   be removed.  To the best of my knowledge, no other place in the Emacs
   manuals indexes commands starting with the prefix argument; we always
   document the command itself and describe there the effect of the
   argument.

`g' is _already_ described in the same node.  I briefly mention `C-u
m' in (info)Help-M in the revised patch below.  I deleted the @kindex
entries for C-u {g,m}.

So what about this revised patch:

===File ~/info.texi-diff====================================
*** info.texi.~1.39.~	Mon Mar  8 18:17:14 2004
--- info.texi	Sun Mar 14 10:58:32 2004
***************
*** 614,619 ****
--- 614,624 ----
  stands for the subtopic of the line you are on.  You can also click
  the middle mouse button directly on the subtopic line to go there.
  
+   As a more advanced feature, if you type @kbd{C-u m}, everything
+ works exactly as if you just typed @kbd{m}, except that the command
+ goes to the node in a new independent Info buffer, which it selects in
+ another window.  The current Info node remains visible in its window.
+ 
  Here is a menu to give you a chance to practice.  This menu gives you
  three ways of going to one place, Help-FOO:
  
***************
*** 1004,1009 ****
--- 1009,1031 ----
  edit the Info file, so typing @kbd{e} there goes to the end of the
  current node.
  
+ @unnumberedsubsec @kbd{M-n} creates a new independent Info buffer in Emacs
+ 
+ @kindex M-n @r{(Info mode)}
+ @findex clone-buffer
+ @cindex creating multiple Info buffers
+   If you are reading Info in Emacs, you can select a new independent
+ Info buffer in another window by typing @kbd{M-n}.  The new buffer
+ starts out as an exact copy of the old one, but you will be able to
+ move independently between nodes in the two buffers.  (In Info mode,
+ @kbd{M-n} runs the Emacs command @code{clone-buffer}.)
+ 
+   In Emacs Info, you can also produce new Info buffers by giving a
+ numeric prefix argument to the @kbd{m} and @kbd{g} commands.  @kbd{C-u
+ m} and @kbd{C-u g} go to a new node in exactly the same way that
+ @kbd{m} and @kbd{g} do, but they do so in a new Info buffer which they
+ select in another window.
+ 
  @node Info Search, Add, Advanced, Expert Info
  @comment  node-name,  next,  previous,  up
  @section How to search Info documents for specific subjects
============================================================

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> Date: Sun, 14 Mar 2004 12:17:05 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> Eli Zaretskii wrote:
> 
>    Even in its ``advanced'' sections, this manual assumes a user who
>    is not really ``advanced'' by the Emacs standards.
> 
> The material on manually editing .info files looks pretty advanced to me.

Why?  Every Unix and GNU user knows about .bashrc, .emacs etc. files.
It's basic Unix usage, IMHO.

>    We should also have an xref to the section in the Emacs manual that
>    describes cloned buffers, I think.
> 
> There is no such section.

I went to the Emacs manual, typed "i clone RET", and was presented
with the node "Indirect Buffers" that describes that.

Re: Documentation for "Clone Buffers" (corrected version)

[Luc Teirlinck]

Eli Zaretskii wrote:

   I went to the Emacs manual, typed "i clone RET", and was presented
   with the node "Indirect Buffers" that describes that.

That is very misleading.  `M-x clone-indirect-buffer' produces an
indirect buffer which is very different from a cloned buffer produced
by `clone-buffer'.  (An indirect buffer always shares the text of its
base buffer and killing the base buffer kills the indirect buffer.  A
cloned buffer created by `clone-buffer', which is what M-n produces,
starts out with the same text, mode, local variables and so on, as the
original buffer, but after that it becomes a completely independent
buffer like any other buffer.)  So it is probably good that my revised
patch no longer talks about "cloned" buffers, since that term is
ambiguous.  There definitely should _not_ be a reference to that
section of the Emacs manual.

Sincerely,

Luc.

Re: Documentation for "Clone Buffers" (corrected version)

[Karl Berry]

    the one who divided (info)Advanced up into @unnumberedsubsec the way

Sorry, I didn't realize the @unnumberedsubsec's were pre-existing.

    apparently whoever wrote it thought that it looked better than the

I think ignorance is a much more likely explanation.

    info.texi to make reading it in hardcopy useful.  So I believe the

Although not all parts of info.texi make sense in print, others do, and
more will in the future (about the Info file format, when I write it).

    particular, we could replace @unnumberedsubsec with @subheading.  I do

Please do.  It's not a matter of looks (it'll look the same).  It's a
matter of good structure and good style.

Actually, making normal @nodes/@subsections of Advanced for those
different topics seems desirable to me, now that I look at it again.  I
don't see any reason why they should all be dumped together in one node
when they are independent.  Each one is about a node's worth on its own.

    would at least provide complete documentation in that docstring, on

It's not my place, but I can't imagine why a more complete docstring
would be objectionable.

    So what about this revised patch:

I think it's fine.

Thanks,
k

Re: Documentation for "Clone Buffers" (corrected version)

[Luc Teirlinck]

Emacs Info now colors the third, sixth and ninth stars in a menu,
instead of the fifth and ninth, so unless there are objections, I plan
to apply the following patch whose only differences with the previous
one are the @unnumberedsubsec vs @subheading change we agreed on and
the *-coloring stuff:

===File ~/info-diff=========================================
*** info.texi.~1.39.~	Mon Mar  8 18:17:14 2004
--- info.texi	Sun Mar 14 18:36:11 2004
***************
*** 614,619 ****
--- 614,624 ----
  stands for the subtopic of the line you are on.  You can also click
  the middle mouse button directly on the subtopic line to go there.
  
+   As a more advanced feature, if you type @kbd{C-u m}, everything
+ works exactly as if you just typed @kbd{m}, except that the command
+ goes to the node in a new independent Info buffer, which it selects in
+ another window.  The current Info node remains visible in its window.
+ 
  Here is a menu to give you a chance to practice.  This menu gives you
  three ways of going to one place, Help-FOO:
  
***************
*** 939,945 ****
  
  Here are some more Info commands that make it easier to move around.
  
! @unnumberedsubsec @kbd{g} goes to a node by name
  
  @kindex g @r{(Info mode)}
  @findex Info-goto-node
--- 944,950 ----
  
  Here are some more Info commands that make it easier to move around.
  
! @subheading @kbd{g} goes to a node by name
  
  @kindex g @r{(Info mode)}
  @findex Info-goto-node
***************
*** 965,971 ****
  all of the current file by typing @kbd{g*@key{RET}} or all of any
  other file with @kbd{g(@var{filename})@key{RET}}.
  
! @unnumberedsubsec @kbd{1} -- @kbd{9} choose a menu subtopic by its number
  
  @kindex 1 @r{through} 9 @r{(Info mode)}
  @findex Info-nth-menu-item
--- 970,976 ----
  all of the current file by typing @kbd{g*@key{RET}} or all of any
  other file with @kbd{g(@var{filename})@key{RET}}.
  
! @subheading @kbd{1} -- @kbd{9} choose a menu subtopic by its number
  
  @kindex 1 @r{through} 9 @r{(Info mode)}
  @findex Info-nth-menu-item
***************
*** 980,995 ****
  the digit keys run the command @code{Info-nth-menu-item}.
  
    If your display supports multiple fonts, and you are using Emacs'
! Info mode to read Info files, the @samp{*} for the fifth menu item
! stands out, either in color or in some other attribute, such as
! underline, and so is the @samp{*} for the ninth item; this makes it
! easy to see at a glance which number to use for an item.
  
    Some terminals don't support colors or underlining.  If you need to
  actually count items, it is better to use @kbd{m} instead, and specify
  the name, or use @key{TAB} to quickly move between menu items.
  
! @unnumberedsubsec @kbd{e} makes Info document editable
  
  @kindex e @r{(Info mode)}
  @findex Info-edit
--- 985,1000 ----
  the digit keys run the command @code{Info-nth-menu-item}.
  
    If your display supports multiple fonts, and you are using Emacs'
! Info mode to read Info files, the third, sixth and ninth menu item
! have a @samp{*} that stands out, either in color or in some other
! attribute, such as underline; this makes it easy to see at a glance
! which number to use for an item.
  
    Some terminals don't support colors or underlining.  If you need to
  actually count items, it is better to use @kbd{m} instead, and specify
  the name, or use @key{TAB} to quickly move between menu items.
  
! @subheading @kbd{e} makes Info document editable
  
  @kindex e @r{(Info mode)}
  @findex Info-edit
***************
*** 1004,1009 ****
--- 1009,1031 ----
  edit the Info file, so typing @kbd{e} there goes to the end of the
  current node.
  
+ @subheading @kbd{M-n} creates a new independent Info buffer in Emacs
+ 
+ @kindex M-n @r{(Info mode)}
+ @findex clone-buffer
+ @cindex creating multiple Info buffers
+   If you are reading Info in Emacs, you can select a new independent
+ Info buffer in another window by typing @kbd{M-n}.  The new buffer
+ starts out as an exact copy of the old one, but you will be able to
+ move independently between nodes in the two buffers.  (In Info mode,
+ @kbd{M-n} runs the Emacs command @code{clone-buffer}.)
+ 
+   In Emacs Info, you can also produce new Info buffers by giving a
+ numeric prefix argument to the @kbd{m} and @kbd{g} commands.  @kbd{C-u
+ m} and @kbd{C-u g} go to a new node in exactly the same way that
+ @kbd{m} and @kbd{g} do, but they do so in a new Info buffer which they
+ select in another window.
+ 
  @node Info Search, Add, Advanced, Expert Info
  @comment  node-name,  next,  previous,  up
  @section How to search Info documents for specific subjects
============================================================

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> Date: Sun, 14 Mar 2004 21:14:40 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: acm@muc.de,eliz@elta.co.il,emacs-devel@gnu.org

[Why was this taken off the Texinfo list?]

>     If your display supports multiple fonts, and you are using Emacs'
> ! Info mode to read Info files, the third, sixth and ninth menu item
> ! have a @samp{*} that stands out, either in color or in some other
> ! attribute, such as underline; this makes it easy to see at a glance
> ! which number to use for an item.

The beginning of this sentence should be changed to something like

   If your display supports multiple fonts, colors, or underlining, ...

>     Some terminals don't support colors or underlining.

And this sentence should also mention multiple fonts.

> + @subheading @kbd{M-n} creates a new independent Info buffer in Emacs
> + 
> + @kindex M-n @r{(Info mode)}
> + @findex clone-buffer
> + @cindex creating multiple Info buffers

I suggest to drop "creating" from the last index entry.  It doesn't
add any useful information, while making the index entry longer.
Also, an index entry that starts with "multiple" stands a better
chance being useful with the `i' command, since a user who looks for
this information is more likely to type "i multiple TAB" than "i
creating TAB".  In general, starting an index entry with a word that
is too general is not a good idea, for this very reason.

Re: Documentation for "Clone Buffers" (corrected version)

[Luc Teirlinck]

So what about the following version which incorporates your latest
suggestions?

===File ~/info-diff=========================================
*** info.texi.~1.39.~	Mon Mar  8 18:17:14 2004
--- info.texi	Mon Mar 15 17:23:24 2004
***************
*** 614,619 ****
--- 614,624 ----
  stands for the subtopic of the line you are on.  You can also click
  the middle mouse button directly on the subtopic line to go there.
  
+   As a more advanced feature, if you type @kbd{C-u m}, everything
+ works exactly as if you just typed @kbd{m}, except that the command
+ goes to the node in a new independent Info buffer, which it selects in
+ another window.  The current Info node remains visible in its window.
+ 
  Here is a menu to give you a chance to practice.  This menu gives you
  three ways of going to one place, Help-FOO:
  
***************
*** 939,945 ****
  
  Here are some more Info commands that make it easier to move around.
  
! @unnumberedsubsec @kbd{g} goes to a node by name
  
  @kindex g @r{(Info mode)}
  @findex Info-goto-node
--- 944,950 ----
  
  Here are some more Info commands that make it easier to move around.
  
! @subheading @kbd{g} goes to a node by name
  
  @kindex g @r{(Info mode)}
  @findex Info-goto-node
***************
*** 965,971 ****
  all of the current file by typing @kbd{g*@key{RET}} or all of any
  other file with @kbd{g(@var{filename})@key{RET}}.
  
! @unnumberedsubsec @kbd{1} -- @kbd{9} choose a menu subtopic by its number
  
  @kindex 1 @r{through} 9 @r{(Info mode)}
  @findex Info-nth-menu-item
--- 970,976 ----
  all of the current file by typing @kbd{g*@key{RET}} or all of any
  other file with @kbd{g(@var{filename})@key{RET}}.
  
! @subheading @kbd{1} -- @kbd{9} choose a menu subtopic by its number
  
  @kindex 1 @r{through} 9 @r{(Info mode)}
  @findex Info-nth-menu-item
***************
*** 979,995 ****
  this is so you need not count how many entries are there.  In Emacs,
  the digit keys run the command @code{Info-nth-menu-item}.
  
!   If your display supports multiple fonts, and you are using Emacs'
! Info mode to read Info files, the @samp{*} for the fifth menu item
! stands out, either in color or in some other attribute, such as
! underline, and so is the @samp{*} for the ninth item; this makes it
! easy to see at a glance which number to use for an item.
! 
!   Some terminals don't support colors or underlining.  If you need to
! actually count items, it is better to use @kbd{m} instead, and specify
! the name, or use @key{TAB} to quickly move between menu items.
  
! @unnumberedsubsec @kbd{e} makes Info document editable
  
  @kindex e @r{(Info mode)}
  @findex Info-edit
--- 984,1001 ----
  this is so you need not count how many entries are there.  In Emacs,
  the digit keys run the command @code{Info-nth-menu-item}.
  
!   If your display supports multiple fonts, colors or underlining, and
! you are using Emacs' Info mode to read Info files, the third, sixth
! and ninth menu items have a @samp{*} that stands out, either in color
! or in some other attribute, such as underline; this makes it easy to
! see at a glance which number to use for an item.
! 
!   Some terminals don't support either multiple fonts, colors or
! underlining.  If you need to actually count items, it is better to use
! @kbd{m} instead, and specify the name, or use @key{TAB} to quickly
! move between menu items.
  
! @subheading @kbd{e} makes Info document editable
  
  @kindex e @r{(Info mode)}
  @findex Info-edit
***************
*** 1004,1009 ****
--- 1010,1032 ----
  edit the Info file, so typing @kbd{e} there goes to the end of the
  current node.
  
+ @subheading @kbd{M-n} creates a new independent Info buffer in Emacs
+ 
+ @kindex M-n @r{(Info mode)}
+ @findex clone-buffer
+ @cindex multiple Info buffers
+   If you are reading Info in Emacs, you can select a new independent
+ Info buffer in another window by typing @kbd{M-n}.  The new buffer
+ starts out as an exact copy of the old one, but you will be able to
+ move independently between nodes in the two buffers.  (In Info mode,
+ @kbd{M-n} runs the Emacs command @code{clone-buffer}.)
+ 
+   In Emacs Info, you can also produce new Info buffers by giving a
+ numeric prefix argument to the @kbd{m} and @kbd{g} commands.  @kbd{C-u
+ m} and @kbd{C-u g} go to a new node in exactly the same way that
+ @kbd{m} and @kbd{g} do, but they do so in a new Info buffer which they
+ select in another window.
+ 
  @node Info Search, Add, Advanced, Expert Info
  @comment  node-name,  next,  previous,  up
  @section How to search Info documents for specific subjects
============================================================

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> Date: Mon, 15 Mar 2004 17:35:06 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> So what about the following version which incorporates your latest
> suggestions?

Fine with me, thanks.

Re: Documentation for "Clone Buffers" (corrected version)

[Luc Teirlinck]

Eli Zaretskii wrote:

   > Date: Sun, 14 Mar 2004 21:14:40 -0600 (CST)
   > From: Luc Teirlinck <teirllm@dms.auburn.edu>
   > CC: acm@muc.de,eliz@elta.co.il,emacs-devel@gnu.org

   [Why was this taken off the Texinfo list?]

It never was on the Texinfo list.  This is a thread on emacs-devel.  I
believe you are confusing with another thread.

Sincerely,

Luc.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    Actually, making normal @nodes/@subsections of Advanced for those
    different topics seems desirable to me, now that I look at it again.  I
    don't see any reason why they should all be dumped together in one node
    when they are independent.  Each one is about a node's worth on its own.

Most of these pseudosections are so small that making them separate
nodes would be inconvenient for the reader.

Re: Documentation for "Clone Buffers" (corrected version)

[Karl Berry]

    What about the following patch to info.texi, documenting M-n, C-u m
    and C-u g?  

I agree with Eli's comments, except I'm not sure about copying the m/g
text instead of moving it and leaving a reference behind.

It is wrong to use @unnumberedsubsec in this way, incidentally.
@subheading is the thing to use, except in this case I doubt any heading
is necessary.  Especially if m/g get moved.

    I could install in the Emacs CVS version of info.texi, if desired.

That's the right place :).  (I sync texinfo's info.texi from there.)

Thanks,
k

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> Date: Sun, 14 Mar 2004 08:39:31 -0500
> From: karl@freefriends.org (Karl Berry)
> 
> I agree with Eli's comments, except I'm not sure about copying the m/g
> text instead of moving it and leaving a reference behind.

I don't mind, but given that this entire subsection is devoted to
cloning Info buffers, perhaps at least part of the text should be
left in it.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    + @unnumberedsubsec @kbd{M-n} creates a cloned Info buffer in Emacs
    + 
    + @kindex M-n @r{(Info mode)}
    + @findex clone-buffer
    + @cindex cloning an Info buffer in Emacs
    +   If you are reading Info in Emacs, you can select a new independent
    + Info buffer in another window by typing @kbd{M-n}.  The new buffer is
    + a ``cloned'' version of the old one.

The term "cloned" is not helpful here--it is a distraction.
These commands create a new Info buffer with different contents.
It would be clearer to say that they create a new Info buffer
to show the requested material, and avoid the word "cloned".

Re: Documentation for "Clone Buffers" (corrected version)

[Luc Teirlinck]

I propose the following changes to the documentation strings of
`Info-mode' and `clone-buffer'.  The change to the Info-mode doc just
adds a line documenting M-n.  I propose to change the doc string of
`clone-buffer' because right now it is incomplete and, in particular,
does not properly document the, in my opinion, important, interactive
use.  If desired, I could install the patches below:

===File ~/info.el-diff======================================
*** info.el.~1.376.~	Mon Dec 29 13:27:09 2003
--- info.el	Thu Mar 11 22:56:38 2004
***************
*** 2495,2500 ****
--- 2495,2501 ----
  
  Advanced commands:
  \\[Info-copy-current-node-name]	Put name of current info node in the kill ring.
+ \\[clone-buffer]	Select a new cloned Info buffer in another window.
  \\[Info-edit]	Edit contents of selected node.
  1	Pick first item in node's menu.
  2, 3, 4, 5   Pick second ... fifth item in node's menu.
============================================================

===File ~/simple.el-diff====================================
*** simple.el.~1.632.~	Thu Mar  4 15:37:21 2004
--- simple.el	Thu Mar 11 22:27:38 2004
***************
*** 4313,4323 ****
  ;; - syntax-table
  ;; - overlays
  (defun clone-buffer (&optional newname display-flag)
!   "Create a twin copy of the current buffer.
! If NEWNAME is nil, it defaults to the current buffer's name;
! NEWNAME is modified by adding or incrementing <N> at the end as necessary.
  
- If DISPLAY-FLAG is non-nil, the new buffer is shown with `pop-to-buffer'.
  This runs the normal hook `clone-buffer-hook' in the new buffer
  after it has been set up properly in other respects."
    (interactive
--- 4313,4334 ----
  ;; - syntax-table
  ;; - overlays
  (defun clone-buffer (&optional newname display-flag)
!   "Create and return a twin copy of the current buffer.
! Unlike an indirect buffer, the new buffer can be edited
! independently of the old one (if it is not read-only).
! NEWNAME is the name of the new buffer.  It may be modified by
! adding or incrementing <N> at the end as necessary to create a
! unique buffer name.  If nil, it defaults to the name of the
! current buffer, with the proper suffix.  If DISPLAY-FLAG is
! non-nil, the new buffer is shown with `pop-to-buffer'.  Trying to
! clone a file-visiting buffer, or a buffer whose major mode symbol
! has a non-nil `no-clone' property, results in an error.
! 
! Interactively, DISPLAY-FLAG is t and NEWNAME is the name of the
! current buffer with appropriate suffix.  However, if a prefix
! argument is given, then the command prompts for NEWNAME in the
! minibuffer.
  
  This runs the normal hook `clone-buffer-hook' in the new buffer
  after it has been set up properly in other respects."
    (interactive
============================================================

Re: Documentation for "Clone Buffers" (corrected version)

[Luc Teirlinck]

David Kastrup wrote:

   Actually, it might be even more useful if the "d" command for going
   to a new directory would also have this FORK functionality, since
   _that_ is the point where one usually wants to start a new info
   path.  And while we are at it, "t" could also make use of a FORK
   prefix.

There was a patch by Juri Linkov discussed in December that added FORK
arguments to several Info functions, as well as added several other
features to Info.  See the thread "Info enhancements" from back in
December.  I believe only one of the several features (_not_ the FORK
stuff) was "controversial", but no part of the patch seems to ever
have been committed.

Alan Mackenzie wrote:

   Maybe having two or more *info* buffers at a time is need peculiar to me,
   but I would've thought it a fairly common requirement.

It happens all the time to me and yes, it would be better if it were
made more convenient.

Sincerely,

Luc.

Re: Documentation for "Clone Buffers" (corrected version)

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> There was a patch by Juri Linkov discussed in December that added
> FORK arguments to several Info functions,

I added FORK argument not to all Info navigation functions.
Now I will add it to all of them.

> as well as added several other features to Info.  See the thread
> "Info enhancements" from back in December.

Since then I improved the info.el further.  I will submit the latest
version soon.

> I believe only one of the several features (_not_ the FORK
> stuff) was "controversial", but no part of the patch seems to ever
> have been committed.

IIRC, the "controversial" feature you refer to was guessing the target
place within an Info node from the reference name.  While I agree that
this is an unreliable feature, it's still better than simply placing
the point at the beginning of a big Info node.  Another alternative is
to use anchors, but it places responsibility on authors of Info
manuals to define correct reference points.  If using anchors is
accepted solution then at least all Emacs manuals should be revised
to find all such references that refer to big Info nodes and to make
anchors for them.

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

Re: Documentation for "Clone Buffers" (corrected version)

[Stefan Monnier]

>> There was a patch by Juri Linkov discussed in December that added
>> FORK arguments to several Info functions,
> I added FORK argument not to all Info navigation functions.
> Now I will add it to all of them.

I think this is the wrong approach.  We want a generic way to do "a fork"
without having to change each and every command where it might make sense.
And I now regret having abuse the C-u prefix for that.  It should be some
other fork-specific prefix instead so the command can still use C-u for
its own purpose.

> Since then I improved the info.el further.  I will submit the latest
> version soon.

Please submit "one feature" at a time, so that if one of them is
controversial it will not prevent others from being applied.

> IIRC, the "controversial" feature you refer to was guessing the target
> place within an Info node from the reference name.  While I agree that
> this is an unreliable feature, it's still better than simply placing
> the point at the beginning of a big Info node.  Another alternative is
> to use anchors, but it places responsibility on authors of Info
> manuals to define correct reference points.  If using anchors is
> accepted solution then at least all Emacs manuals should be revised
> to find all such references that refer to big Info nodes and to make
> anchors for them.

I think your solution is at least as good as the current situation,
and sometimes much better.


        Stefan

Re: Documentation for "Clone Buffers" (corrected version)

[Miles Bader]

On Mon, Mar 15, 2004 at 08:27:31AM -0500, Stefan Monnier wrote:
> It should be some other fork-specific prefix instead so the command can
> still use C-u for its own purpose.

I'm skeptical.

I like C-u because it's really easy to remember, which is important if it's
not used regularly -- and AFAICS, forking fits that pattern: something that
isn't used all _that_ often, but which is very nice when you do need it, and
which cleanly fits into the C-u `slightly modified alternate behavior' mold.

-Miles
-- 
"Though they may have different meanings, the cries of 'Yeeeee-haw!' and
 'Allahu akbar!' are, in spirit, not actually all that different."

Re: Documentation for "Clone Buffers" (corrected version)

[David Kastrup]

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

> >> There was a patch by Juri Linkov discussed in December that added
> >> FORK arguments to several Info functions,
> > I added FORK argument not to all Info navigation functions.
> > Now I will add it to all of them.
> 
> I think this is the wrong approach.  We want a generic way to do "a fork"
> without having to change each and every command where it might make sense.
> And I now regret having abuse the C-u prefix for that.  It should be some
> other fork-specific prefix instead so the command can still use C-u for
> its own purpose.

But that is quite similar to the way that M-x shell and consorts
work.  It is convenient and easily rememberable.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Documentation for "Clone Buffers" (corrected version)

[Juri Linkov]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> I added FORK argument not to all Info navigation functions.
>> Now I will add it to all of them.
>
> I think this is the wrong approach.  We want a generic way to do "a fork"
> without having to change each and every command where it might make sense.
> And I now regret having abuse the C-u prefix for that.  It should be some
> other fork-specific prefix instead so the command can still use C-u for
> its own purpose.

The Emacs Info browser can be compared to Web browsers where links
can be opened in a new window/tab either by the New Window command
(usually bound to C-n) with an initial content of the current page -
this is very similar to Emacs's clone-buffer (M-n), or by pressing
Ctrl key while clicking on a link - this is similar to Emacs's C-u
prefix.  But AFAIK none of Web browsers provide this functionality
(pressing Ctrl key) for other commands (like Back, Forward, Home).
Perhaps, clone-buffer (M-n) should be a primary method for forking
a new Info buffer.  It's as simple as using C-u prefix.

>> IIRC, the "controversial" feature you refer to was guessing the target
>> place within an Info node from the reference name.  While I agree that
>> this is an unreliable feature, it's still better than simply placing
>> the point at the beginning of a big Info node.  Another alternative is
>> to use anchors, but it places responsibility on authors of Info
>> manuals to define correct reference points.  If using anchors is
>> accepted solution then at least all Emacs manuals should be revised
>> to find all such references that refer to big Info nodes and to make
>> anchors for them.
>
> I think your solution is at least as good as the current situation,
> and sometimes much better.

There are some references in Emacs manuals that refer to the middle
of a big Info node but use neither anchors nor reference names.  We
should decide which is the preferred method of reference and change
them for all such cases in Emacs manuals.

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

Re: Documentation for "Clone Buffers" (corrected version)

[Miles Bader]

David Kastrup <dak@gnu.org> writes:
> Is the prefix argument of the following more user-friendly?
> 
> (Info-menu MENU-ITEM &optional FORK)

Wow, I didn't know about that -- that _is_ much better!

I notice that the name of the resulting forked info buffer contains the
name of the target node, which might or might not always be the right
thing, but I suppose it's a reasonable guess.

> Actually, it might be even more useful if the "d" command for going
> to a new directory would also have this FORK functionality, since
> _that_ is the point where one usually wants to start a new info
> path.  And while we are at it, "t" could also make use of a FORK
> prefix.

Yes those also would be handy...

-Miles
-- 
We are all lying in the gutter, but some of us are looking at the stars.
-Oscar Wilde

Re: Documentation for "Clone Buffers" (corrected version)

[Alex Schroeder]

Alan Mackenzie <acm@muc.de> writes:

> I think a(n easy) method of opening a second *info* buffer is a Good
> Thing.  Perhaps M-n `clone-buffer' isn't the most elegant command around,
> but it's got to be better than M-x rename-uniquely etc., from a user's
> point of view.

Heh.  :)  Many have complained about similar functionality in M-x
shell, for example (and written code where M-x shell starts *another*
shell instead of switching to the existing shell buffer).  Inspired by
the M-x shell interface, other code behaves similarly: M-x
sql-something switches to the existing SQL buffer instead of creating
a new one.  M-x ielm does the same.  Etc.

What I'm trying to say is that yes, the interface is not elegant.
But it seems that both variants are equally unpopular, so we just
need to pick one, stick to it, and make a generic solution the
problem for all these instances.  Renaming the buffer before calling
the function again was deemed to be good enough a long while back (I
guess because we were not sure that using a prefix was better or
possible at all).

I'm sure that some users will be glad if you can devise a generic
and elegant solution to this usability problem.  :)

Alex.
-- 
.O.  http://www.emacswiki.org/alex/
..O  Schroeder's fourth law:
OOO  None of your friends and coworkers share your taste in music.

Re: Documentation for "Clone Buffers" (corrected version)

[Kai Grossjohann]

Alex Schroeder <alex@emacswiki.org> writes:

> Heh.  :)  Many have complained about similar functionality in M-x
> shell, for example (and written code where M-x shell starts *another*
> shell instead of switching to the existing shell buffer).

On a tangent, I like fshell.el which has functionality not provided by
M-x shell RET plus clone-buffer:

C-u 42 M-x fshell RET goes to the *shell*<42> buffer, creating it if
it doesn't exist, yet.

For some reason or other, I like this much better than using some
switch-to-buffer interface for selecting the right buffer.

Kai

Re: Documentation for "Clone Buffers" (corrected version)

[Juri Linkov]

Kai Grossjohann <kai@emptydomain.de> writes:
> Alex Schroeder <alex@emacswiki.org> writes:
>> Heh.  :)  Many have complained about similar functionality in M-x
>> shell, for example (and written code where M-x shell starts *another*
>> shell instead of switching to the existing shell buffer).
>
> On a tangent, I like fshell.el which has functionality not provided by
> M-x shell RET plus clone-buffer:
>
> C-u 42 M-x fshell RET goes to the *shell*<42> buffer, creating it if
> it doesn't exist, yet.
>
> For some reason or other, I like this much better than using some
> switch-to-buffer interface for selecting the right buffer.

This is a very good idea!  How about the following implementation?
It works by appending the numeric prefix argument to the *info*
buffer name:

C-u 15 C-h i goes to the *info*<15> buffer, creating it
             with the top-level Info directory if it doesn't exist.

I think that adding this feature will make the FORK argument obsolete
because with the FORK argument a forked Info buffer contains the name
of the target node which is too misleading when the user goes to
another Info node in the same Info buffer.  OTOH, the naming scheme
with the numeric suffix is more convenient: the user has three choices
to create a new Info buffer by adding a number to its name:

1. clone the Info buffer by M-n;
2. rename the Info buffer by rename-uniquely;
3. create a new Info buffer by giving the numeric prefix argument to C-h i

And in all cases jumping to the existing Info buffer is the same:
by giving the numeric prefix argument to C-h i with the number in
the existing buffer name.

Index: lisp/info.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/info.el,v
retrieving revision 1.390
diff -u -r1.390 info.el
--- lisp/info.el	22 Apr 2004 19:49:11 -0000	1.390
+++ lisp/info.el	25 Apr 2004 03:17:16 -0000
@@ -449,28 +450,38 @@
   "Like `info' but show the Info buffer in another window."
   (interactive (if current-prefix-arg
 		   (list (read-file-name "Info file name: " nil nil t))))
-  (let (same-window-buffer-names)
+  (let (same-window-buffer-names same-window-regexps)
     (info file)))
 
-;;;###autoload (add-hook 'same-window-buffer-names "*info*")
+;;;###autoload (add-hook 'same-window-regexps "\\*info\\*\\(\\|<[0-9]+>\\)")
 
 ;;;###autoload
-(defun info (&optional file)
+(defun info (&optional file buffer)
   "Enter Info, the documentation browser.
 Optional argument FILE specifies the file to examine;
 the default is the top-level directory of Info.
 Called from a program, FILE may specify an Info node of the form
 `(FILENAME)NODENAME'.
-
-In interactive use, a prefix argument directs this command
-to read a file name from the minibuffer.
+Optional argument BUFFER specifies the Info buffer name;
+the default buffer name is *info*.  If BUFFER exists,
+just switch to BUFFER.  Otherwise, create a new buffer
+with the top-level Info directory.
+
+In interactive use, a non-numeric prefix argument directs
+this command to read a file name from the minibuffer.
+A numeric prefix argument appends the number to the buffer name.
 
 The search path for Info files is in the variable `Info-directory-list'.
 The top-level Info directory is made by combining all the files named `dir'
 in all the directories in that path."
-  (interactive (if current-prefix-arg
-		   (list (read-file-name "Info file name: " nil nil t))))
-  (pop-to-buffer "*info*")
+  (interactive (list
+                (if (and current-prefix-arg (not (numberp current-prefix-arg)))
+                    (read-file-name "Info file name: " nil nil t))
+                (if (numberp current-prefix-arg)
+                    (format "*info*<%s>" current-prefix-arg))))
+  (pop-to-buffer (or buffer "*info*"))
+  (if (and buffer (not (eq major-mode 'Info-mode)))
+      (Info-mode))
   (if file
       ;; If argument already contains parentheses, don't add another set
       ;; since the argument will then be parsed improperly.  This also

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

Re: Documentation for "Clone Buffers" (corrected version)

[Karl Berry]

    C-u 15 C-h i goes to the *info*<15> buffer, creating it
                 with the top-level Info directory if it doesn't exist.

It sounds good to me.  Thanks.

C-h C-i

[Juri Linkov]

Since the change for using a numeric prefix argument of `info'
by appending its value to the Info buffer name was installed,
it became possible to switch Info buffers easily by the key
sequences like:

C-5 C-h i

But it is much easier to type this key sequence while the control key
is pressed for all its keys:

C-5 C-h C-i

Any objections to adding a new keybinding `C-h C-i' to `info'?

In older Emacs versions it was bound to `info-lookup-symbol', but it
was changed to another keybinding `C-h S', so `C-h C-i' is unbound now.
 
-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: C-h C-i

[Karl Fogel]

Juri Linkov <juri@jurta.org> writes:
> Since the change for using a numeric prefix argument of `info'
> by appending its value to the Info buffer name was installed,
> it became possible to switch Info buffers easily by the key
> sequences like:
> 
> C-5 C-h i
> 
> But it is much easier to type this key sequence while the control key
> is pressed for all its keys:
> 
> C-5 C-h C-i
> 
> Any objections to adding a new keybinding `C-h C-i' to `info'?
> 
> In older Emacs versions it was bound to `info-lookup-symbol', but it
> was changed to another keybinding `C-h S', so `C-h C-i' is unbound now.

I'd prefer not to use up a potential binding for this small
convenience.

`C-h C-i' may be unbound now, but another use might be found for it
later, one better than simply duplicating what `C-h i' does right now.
If we bind it to something common and important like `info', it'd be
hard to change that later.

So there's one objection :-).

-Karl

Re: C-h C-i

[Juri Linkov]

Karl Fogel <kfogel@floss.red-bean.com> writes:
> `C-h C-i' may be unbound now, but another use might be found for it
> later, one better than simply duplicating what `C-h i' does right now.
> If we bind it to something common and important like `info', it'd be
> hard to change that later.

I don't suggest to make `C-h C-i' an official keybinding for `info'
by documenting it everywhere.  What I propose is only to add it
to help.el as a catcher for cases when users mistype `C-h i'
which now is very probable when switching between Info buffer with
key sequences like C-1 C-h i C-2 C-h i C-3 C-h i C-4 C-h i C-5 C-h i.

If we find a better use for `C-h C-i' later, we can freely rebind it,
since we don't advertise it as an official keybinding for `info'.

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

Re: C-h C-i

[Karl Fogel]

Juri Linkov <juri@jurta.org> writes:
> Karl Fogel <kfogel@floss.red-bean.com> writes:
> > `C-h C-i' may be unbound now, but another use might be found for it
> > later, one better than simply duplicating what `C-h i' does right now.
> > If we bind it to something common and important like `info', it'd be
> > hard to change that later.
> 
> I don't suggest to make `C-h C-i' an official keybinding for `info'
> by documenting it everywhere.  What I propose is only to add it
> to help.el as a catcher for cases when users mistype `C-h i'
> which now is very probable when switching between Info buffer with
> key sequences like C-1 C-h i C-2 C-h i C-3 C-h i C-4 C-h i C-5 C-h i.
> 
> If we find a better use for `C-h C-i' later, we can freely rebind it,
> since we don't advertise it as an official keybinding for `info'.

(Has Emacs ever used such an "unofficial keybinding" policy before?)

I really don't think it's worth optimizing for such narrow use cases
by making a special keybinding, especially when the consequence of
mistyping right now is merely that nothing happens.

There are two possible outcomes here, both undesirable IMHO:

   1. That key sequence is not used very often... In which case, the
      benefit of adding this keybinding is correspondingly small.

or

   2. That key sequence is used fairly often... In which case, the new
      binding would be something people *do* grow to depend on,
      whether we document it "officially" or not, and therefore we'd
      effectively lose the ability to bind it to something different
      in the future.

-Karl

Re: C-h C-i

[Juri Linkov]

Karl Fogel <kfogel@floss.red-bean.com> writes:
> (Has Emacs ever used such an "unofficial keybinding" policy before?)
>
> I really don't think it's worth optimizing for such narrow use cases
> by making a special keybinding, especially when the consequence of
> mistyping right now is merely that nothing happens.

There are some duplicated keybindings in help.el already:
both `C-h n' and `C-h C-n' are bound to `view-emacs-news'.
But `C-h i' is used more often than `C-h n' or `C-h C-n'.
Why we have duplicated keybindings for `view-emacs-news',
but can't add a new for `info'?

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

Re: C-h C-i

[Karl Fogel]

Juri Linkov <juri@jurta.org> writes:
> There are some duplicated keybindings in help.el already:
> both `C-h n' and `C-h C-n' are bound to `view-emacs-news'.
> But `C-h i' is used more often than `C-h n' or `C-h C-n'.
> Why we have duplicated keybindings for `view-emacs-news',
> but can't add a new for `info'?

This isn't about whether or not we have a precedent for duplication.
It's about using up keyspace.  Just because we have used up some
keybindings, does not mean it's good to use up more.

You asked if there were any objections -- I objected :-).  If someone
had asked me whether `C-h C-n' was a good idea, given that we already
had `C-h n', I would have objected to that too, for the same reasons.

(Or perhaps they happened in the other order, but that doesn't change
the point.)

-Karl

Re: C-h C-i

[Juri Linkov]

Karl Fogel <kfogel@floss.red-bean.com> writes:
> This isn't about whether or not we have a precedent for duplication.
> It's about using up keyspace.  Just because we have used up some
> keybindings, does not mean it's good to use up more.
>
> You asked if there were any objections -- I objected :-).  If someone
> had asked me whether `C-h C-n' was a good idea, given that we already
> had `C-h n', I would have objected to that too, for the same reasons.

If it really has no way to get into help.el, consider it simply as
a good suggestion to include this keybinding into personal .emacs :-)

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

Re: C-h C-i

[Richard Stallman]

    I don't suggest to make `C-h C-i' an official keybinding for `info'
    by documenting it everywhere.  What I propose is only to add it
    to help.el as a catcher for cases when users mistype `C-h i'

My decision is no.  C-h followed by control characters is only for
commands to display a file.

Lately I have seen people spending a lot of time discussing minor
issues.  This time sink is getting in the way of useful work.
When you see such a discussion develop, please wait a day before
saying anything more.  Then you'll see if I make a decision or not.
If I don't make a decision, you can go back to arguing, if you don't
have anything else to do.

Re: C-h C-i

[Karl Fogel]

Richard Stallman <rms@gnu.org> writes:
> Lately I have seen people spending a lot of time discussing minor
> issues.  This time sink is getting in the way of useful work.
> When you see such a discussion develop, please wait a day before
> saying anything more.  Then you'll see if I make a decision or not.
> If I don't make a decision, you can go back to arguing, if you don't
> have anything else to do.

People spend their time on minor issues largely because there is no
bug tracker and no clear path to "the next goal" -- release,
milestone, whatever.  When you see everyone spinning out into "what
color to paint the bikeshed" discussions, it is a sign that nothing
more compelling has presented itself to occupy them.

If there were more organization, to make it obvious what the useful
work is, people would be doing that instead.  You want lead a
network-based development project, but while avoiding technologies
that require being attached to the network regularly.  This
contradiction is part of the problem.  Minor issues will continue to
dominate, as long as people do not see an organized, trackable
presentation of high-priority issues, maintained in real time.

-Karl

Re: C-h C-i

[Juanma Barranquero]

On 18 Jun 2004 19:19:42 -0500, Karl Fogel <kfogel@floss.red-bean.com> wrote:

> If there were more organization, to make it obvious what the useful
> work is, people would be doing that instead.  You want lead a
> network-based development project, but while avoiding technologies
> that require being attached to the network regularly.  This
> contradiction is part of the problem.  Minor issues will continue to
> dominate, as long as people do not see an organized, trackable
> presentation of high-priority issues, maintained in real time.

I agree to the last dot and comma.

                                                           /L/e/k/t/u

Re: C-h C-i

[Miles Bader]

On Sun, Jun 20, 2004 at 02:42:37AM +0200, Juanma Barranquero wrote:
> > You want lead a
> > network-based development project, but while avoiding technologies
> > that require being attached to the network regularly.  This
> > contradiction is part of the problem.  Minor issues will continue to
> > dominate, as long as people do not see an organized, trackable
> > presentation of high-priority issues, maintained in real time.
> 
> I agree to the last dot and comma.

So let's make a system that uses an organized file in the emacs source tree,
and a simple emacs browser on top of it, plus maybe email state-change
notices.

Simple and effective.

-Miles
-- 
A zen-buddhist walked into a pizza shop and
said, "Make me one with everything."

Re: C-h C-i

[Juanma Barranquero]

On Sat, 19 Jun 2004 21:17:28 -0400, Miles Bader <miles@gnu.org> wrote:

> So let's make a system that uses an organized file in the emacs source tree,
> and a simple emacs browser on top of it, plus maybe email state-change
> notices.

Sure.  Let's make.

Any volunteers?

                                                           /L/e/k/t/u

One possible bug-tracking system.

[Karl Fogel]

Juanma Barranquero <lektu@mi.madritel.es> writes:
> On Sat, 19 Jun 2004 21:17:28 -0400, Miles Bader <miles@gnu.org> wrote:
> > So let's make a system that uses an organized file in the emacs source tree,
> > and a simple emacs browser on top of it, plus maybe email state-change
> > notices.
> 
> Sure.  Let's make.

This may or may not be helpful here, but:

Martyn Pearce, the maintainer of the 'cvs2cl' CVS->ChangeLog script,
has been using a text-file-based bug tracking system for some time.
You can see what it looks like here:

   http://www.red-bean.com/cvs2cl/BUGS.html

Some points:

   1. The bugs are maintained in a single file called BUGS.xml, from
      which BUGS.html and other (more detailed) HTML files are
      generated.

   2. There does not appear to be any email interface :-(.

   3. The browse interface is your web browser, not Emacs (though the
      edit interface is still Emacs, of course).  No net connection is
      required, though -- you're still browsing local files.

   4. Because of (3), it's easy to display bug status to the general
      public, as well as to have it available locally.  For example,
      see http://www.red-bean.com/cvs2cl/BUGS/detail.html#_68.

To inspect this system more closely, just check out the working copy:

   $ cvs -d :pserver:anonymous@cvs.red-bean.com:/usr/local/cvs co cvs2cl

I'm certainly not claiming this is the greatest system ever made, but
it's better than nothing.  I certainly won't push it if anything even
slightly better comes along :-).

One possibility, if we don't consense on something better soon, is to
just start maintaining a BUGS.xml in the Emacs tree, and we'll at
least see how useful it is to how many people.

By the way, I'm not sure it's such a bad idea to simply write a
local-file-based, Emacs-accessible bug tracking system.  Of course,
writing something from scratch is always daunting, and unfortunately I
personally wouldn't have time to contribute much.  But please don't
take my suggestion above as a rejection of the direct approach: decide
what we want, then write it.

-Karl

Re: One possible bug-tracking system.

[Alex Schroeder]

Karl Fogel <kfogel@floss.red-bean.com> writes:

> One possibility, if we don't consense on something better soon, is to
> just start maintaining a BUGS.xml in the Emacs tree, and we'll at
> least see how useful it is to how many people.

Assuming we don't want HTML output and we want simpler input,
wouldn't a file in outline mode be enough?

Alex.
-- 
.O.  http://www.emacswiki.org/alex/
..O  Schroeder's fourth law:
OOO  None of your friends and coworkers share your taste in music.

Re: One possible bug-tracking system.

[Karl Fogel]

Alex Schroeder <alex@emacswiki.org> writes:
> Assuming we don't want HTML output and we want simpler input,
> wouldn't a file in outline mode be enough?

What it lacks is the ability to compose & browse bug summaries
organized by severity, assignee(s), search matches, etc.  That kind of
interface is very important for getting an overview of what's going
on and for prioritizing.

Each bug needs to be a first class object, with specific meta-data and
state associated with it.  That could be achieved using outline mode,
but probably we'll want better browsing than outline mode affords.  I
was thinking of a format that is a series of bug entries, something
like this:

   -*- -*- -*- -*- -*-
   Summary:      find-file-noselect fails when used with bleach
   Id:           #73
   Severity:     LOW | MED | HIGH
   Priority:     LOW | MED | HIGH
   Reporters:    jrandom@example.com
   Type:         DEFECT | ENHANCEMENT | FEATURE | TASK
   Status:       OPEN | STARTED | CLOSED
   Resolution:   (none) | FIXED | INVALID | WONTFIX | DUPLICATE | WORKSFORME
   Accepted by:  some@emacs.developer
   Emacs info:
     In GNU Emacs 21.3.50.1 (i686-pc-linux-gnu)
      of 2004-05-16 on mymachine.example.com
     Important settings:
       value of $LC_ALL: nil
     [... etc, etc ...]
   Description:  
     M-x find-file-noselect errors when invoked with bleach.  But it
     is documented to work -- it's supposed to remove all color from
     the file contents if bleach is non-nil.  I think the problem can
     be traced to this line in files.el: ...

   -*- -*- -*- -*- -*-
   Summary:      blah blah blah
   Id:           #74
   Severity:     LOW | MED | HIGH
   Priority:     LOW | MED | HIGH
   Reporters:    someone-else@example.com
   Type:         DEFECT | ENHANCEMENT | FEATURE | TASK
   Status:       OPEN | STARTED | HAVE_PATCH | CLOSED
   Resolution:   (none) | FIXED | INVALID | WONTFIX | DUPLICATE | WORKSFORME
   Accepted by:  another@emacs.developer
   Emacs info:
     [... etc, etc ...]
   Description:  
     [... etc, etc ...]

The idea is we'd have functions for browsing this file in summary
form:

  M-x bugz-browse-all
  M-x bugz-browse-open
  M-x bugz-browse-goto-bug
  M-x bugz-browse-matching

That last one would take a field name (or "any") and a string to
match, and show all bugs matching the string.  By "show", I mean a
separate buffer with optimized movement commands, showing each bug
that matches the request.  Defects would have a red background on
their Type field, so they are immediately obvious, and so on.

Once you've selected a bug, you can jump to it in the master bugs file
(narrowed) with one keystroke, of course, so that changing a bug's
status is just a matter of jumping (either from summary buffer, or via
`bugz-browse-goto-bug') and editing the master file.

Metadata can also be edited directly in the summary buffer, of course.

There would be a function `bugz-attach-mail' and a variable
`bugz-attach-mail-func'.  The variable's value is a function
appropriate for each mail reader in Emacs.  `bugz-attach-mail' would
prompt for a bug ID number.  While reading an email relevant to some
bug, you invoke `bugz-attach-mail', and it appends that email to an
mbox file in a dedicated subdirectory for that bug, a path which is
known to the master bugs file.  (That's the best I can think of right
now for an email tracking system.  We're rather constrained by the
requirement that all the data be in the working copy.  However, we
could eventually set up a system that listens for emails with special
subjects, and automatically files them in the right place and commits
them.)

Of course, all this is easy to say.  Who's going to code it?  I am too
swamped right now to do it :-(.  But I hope maybe someone else will
agree that this approach has promise and whip something up.  Or maybe
there's a system that does something like this already?

-Karl

Re: One possible bug-tracking system.

[Luc Teirlinck]

Karl Fogel wrote:

   Of course, all this is easy to say.  Who's going to code it?  I am too
   swamped right now to do it :-(.

And I am convinced that any time I can devote to Emacs right now is
better spent updating and checking the Elisp manual, as well as other
documentation, and fixing bugs (rather than tracking them).

We are in a feature freeze right now.  A bug tracker seems to have
nothing to do with getting ready for the next release.  We are not
going to get rid of every single bug before the next release.  Would
be nice, but it is not going to happen.  Maybe there are a few bugs
that are so major that they _need_ to be taken care of before the next
release.  They can be listed in the etc/FOR-RELEASE file that Richard
is going to create.  Can we not have a discussion about the long term
need for a bug tracker and which form that should have _after_ the
release?

Sincerely,

Luc.

Re: One possible bug-tracking system.

[Karl Fogel]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> We are in a feature freeze right now.  A bug tracker seems to have
> nothing to do with getting ready for the next release.  We are not
> going to get rid of every single bug before the next release.  Would
> be nice, but it is not going to happen.  Maybe there are a few bugs
> that are so major that they _need_ to be taken care of before the next
> release.  They can be listed in the etc/FOR-RELEASE file that Richard
> is going to create.  Can we not have a discussion about the long term
> need for a bug tracker and which form that should have _after_ the
> release?

That's right, a bug tracker has nothing to do with getting ready for
the next release.  (I thought we'd already established that those are
unrelated discussions...)

Preparing for the release is not everyone's priority.  Tracking bug
reports is an entirely different thing.  It's not about the upcoming
release.  It's about having a sense of what's wrong in Emacs at any
given time, so people who only have time to do discrete tasks can more
easily prioritize.  I don't believe that overview is possible without
a tracking system.  For some of us, the overview would be very
helpful, and would make us more helpful than we are right now.

I never said anything about getting rid of every single bug before the
next release, so I'm not sure what you're rebutting there :-).

Why does the discussion need to happen after the release?  Do you
think that the discussion is occupying people who would otherwise be
working on the manual, or on other things from Richard's list?  That's
not the case for me; I doubt it's the case for most other participants
either.

-Karl

Re: One possible bug-tracking system.

[Richard Stallman]

It would be ok to use an existing bug tracking system as long as it is
easy to use by email.  Rather than proposing difficult alternatives
such as writing a bug tracker in Emacs, how about looking for one that
is suitable?

Re: One possible bug-tracking system.

[Juanma Barranquero]

On Mon, 21 Jun 2004 05:31:25 -0400
Richard Stallman <rms@gnu.org> wrote:

> It would be ok to use an existing bug tracking system as long as it is
> easy to use by email.  Rather than proposing difficult alternatives
> such as writing a bug tracker in Emacs, how about looking for one that
> is suitable?

There are a few that would probably be suitable.  I've been testing
Mantis (http://www.mantisbt.org/); not the most featureful bug tracker
out there, but *dead* easy to use and setup (even on Windows, though
that's not a requirement per se).

It doesn't do e-mail, but as it is a MySQL backend and a few PHP scripts,
I don't think would be hard to do an Emacs gateway via e-mail (and
perhaps URL).

You can take a look at http://bugs.mantisbt.org/.  The CVSNT project is
using Mantisbt and their bug database can be accessed at
http://www.cvsnt.org/mantis/login_page.php (though registration is
needed on this one).

                                                                Juanma

Re: One possible bug-tracking system.

[Richard Stallman]

    It doesn't do e-mail, but as it is a MySQL backend and a few PHP scripts,
    I don't think would be hard to do an Emacs gateway via e-mail (and
    perhaps URL).

If you want to do this and set it up so people can try it,
then we could judge whether this option is ok.

Re: One possible bug-tracking system.

[Arne Jørgensen]

Richard Stallman <rms@gnu.org> writes:

> It would be ok to use an existing bug tracking system as long as it is
> easy to use by email.  Rather than proposing difficult alternatives
> such as writing a bug tracker in Emacs, how about looking for one that
> is suitable?

What about GNATS?

I have no experience at all with GNATS but when I read the
introduction at <http://www.gnu.org/software/gnats/> it seems to fit
most of the needs and wishes expressed here.

Kind regards,
-- 
Arne Jørgensen
Gammel Kongevej 7, 1. th., DK-1610 Copenhagen V, Denmark
mobile: +45 21 65 01 13
email: arne@arnested.dk, <http://arnested.dk/>

Re: One possible bug-tracking system.

[Richard Stallman]

    What about GNATS?

    I have no experience at all with GNATS but when I read the
    introduction at <http://www.gnu.org/software/gnats/> it seems to fit
    most of the needs and wishes expressed here.

I think it does.  Also, it is a GNU package, which is an argument
in favor.

Another possibility is to use RT, which is what the GNU Project uses
for many other things.  I think it can be used via email.  I don't
know whether RT is suitable for bug tracking, though.

Re: One possible bug-tracking system.

[Karl Fogel]

Richard Stallman <rms@gnu.org> writes:
> It would be ok to use an existing bug tracking system as long as it is
> easy to use by email.  Rather than proposing difficult alternatives
> such as writing a bug tracker in Emacs, how about looking for one that
> is suitable?

I don't know of any that have decent query interfaces by email.  Some
have good email input; good email output is less common, especially
when it comes to database-style querying.

I assumed you needed full functionality via email, but maybe I'm not
understanding your constraints very well.  If you just want to change
bug states via email, but are okay with leaving database-style
querying to others, then it might be okay for that part of the
functionality to be primarily Web-based. (?)

(I agree with you that writing a custom tracker is unrealistic, though
stranger things have happened.)

Re: One possible bug-tracking system.

[Juri Linkov]

Karl Fogel <kfogel@floss.red-bean.com> writes:
> (I agree with you that writing a custom tracker is unrealistic, though
> stranger things have happened.)

Why is it unrealistic?  Is it rocket science?

A very simple solution based on text files and CVS was proposed already.
Why not use it?

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

Re: One possible bug-tracking system.

[Marcelo Toledo]

Debian Bug Tracking System (BTS) is a very intersting one, mail based
and has also a very good web interface, a must-look-at system.

Karl Fogel <kfogel@floss.red-bean.com> writes:

> I don't know of any that have decent query interfaces by email.  Some
> have good email input; good email output is less common, especially
> when it comes to database-style querying.
>
> I assumed you needed full functionality via email, but maybe I'm not
> understanding your constraints very well.  If you just want to change
> bug states via email, but are okay with leaving database-style
> querying to others, then it might be okay for that part of the
> functionality to be primarily Web-based. (?)
>
> (I agree with you that writing a custom tracker is unrealistic, though
> stranger things have happened.)

-- 
Marcelo Toledo
marcelo@marcelotoledo.org
http://www.marcelotoledo.org
Mobile: 55 71 9141-7181

Re: One possible bug-tracking system.

[Richard Stallman]

    I assumed you needed full functionality via email, but maybe I'm not
    understanding your constraints very well.  If you just want to change
    bug states via email, but are okay with leaving database-style
    querying to others, then it might be okay for that part of the
    functionality to be primarily Web-based. (?)

It might be ok.  On the other hand, could you write a mail-receiving demon
that would do queries in response to mail?  It might not be hard to write.

Re: C-h C-i

[Richard Stallman]

      When you see everyone spinning out into "what
    color to paint the bikeshed" discussions, it is a sign that nothing
    more compelling has presented itself to occupy them.

The main area that needs work, for a new release, is to update the
manual.  If you don't know of something else to work on, how about
looking in etc/NEWS for some items not yet updated in the manual, and
updating them?

Another important area for further work is to test the mbox-format
Rmail branch, so that we can install it.  I want that to be installed
before the release.

Does anyone know of any other areas that need work?  We were
discussing how to record this information, but what really matters is
the substance of the information.  I will create a file
etc/FOR-RELEASE, and start it off as below.  Would people please post
other items of work they believe is needed?


** Test the mbox branch of Rmail.

** Install the mbox branch of Rmail.

** Finish updating the Emacs Lisp manual.

** Finish checking the Emacs Lisp manual.

** Update the Emacs Manual.

** Check the Emacs Lisp manual.

Re: C-h C-i

[Luc Teirlinck]

Richard Stallman wrote:
   
   I will create a file etc/FOR-RELEASE, and start it off as below.
   Would people please post other items of work they believe is needed?

   ** Test the mbox branch of Rmail.

   ** Install the mbox branch of Rmail.

   ** Finish updating the Emacs Lisp manual.

   ** Finish checking the Emacs Lisp manual.

   ** Update the Emacs Manual.

   ** Check the Emacs Lisp manual.

I believe that last item is supposed to be:

   ** Check the Emacs manual.

Beyond that, non-trivial changes have recently been made to the Emacs
Info reader.  info.texi does not seem to have been updated for them.
Even though info.texi can be thought of as being mainly a texinfo
file, I believe that it is important that the version that is included
with the Emacs distribution accurately describes the Emacs Info reader
of that distribution.  So I believe that man/info.texi should be
properly updated before the release.  I do not know whether Juri is
planning to take care of that.

Sincerely,

Luc.

Re: C-h C-i

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Beyond that, non-trivial changes have recently been made to the Emacs
> Info reader.  info.texi does not seem to have been updated for them.
> Even though info.texi can be thought of as being mainly a texinfo
> file, I believe that it is important that the version that is included
> with the Emacs distribution accurately describes the Emacs Info reader
> of that distribution.  So I believe that man/info.texi should be
> properly updated before the release.  I do not know whether Juri is
> planning to take care of that.

I haven't updated the Info manual because I plan to make more changes
to the Emacs Info reader: isearch across several Info nodes and a
backward search.  I think these changes should be included into the
next release because the stand-alone Info reader already has these
features and the Emacs Info reader should be as close in functionality
to the stand-alone Info reader as possible.  I hope to finish these
changes in a few days.

Apart from these changes, I documented all installed changes briefly
in etc/NEWS.  So we could start documenting installed changes in the
Info manual and add the newest changes later.  However, I don't know
what is the right procedure for synchronizing the Emacs version of
info.texi with the Texinfo distribution.

If you wish to update the Info manual and know how to sync it with the
Texinfo distribution, please do.  If not, I might take care of that.

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

Re: C-h C-i

[Luc Teirlinck]

Juri Linkov wrote:

   I haven't updated the Info manual because I plan to make more changes
   to the Emacs Info reader: isearch across several Info nodes and a
   backward search.  I think these changes should be included into the
   next release because the stand-alone Info reader already has these
   features and the Emacs Info reader should be as close in functionality
   to the stand-alone Info reader as possible.  I hope to finish these
   changes in a few days.

I believe it is OK if info.texi gets updated before the next release,
which is not going to be tomorrow.

   Apart from these changes, I documented all installed changes briefly
   in etc/NEWS.  So we could start documenting installed changes in the
   Info manual and add the newest changes later.  However, I don't know
   what is the right procedure for synchronizing the Emacs version of
   info.texi with the Texinfo distribution.

   If you wish to update the Info manual and know how to sync it with the
   Texinfo distribution, please do.  If not, I might take care of that.

You just edit man/info.texi.  I believe Karl takes care of the
synchronization.  It is probably best if you do the updating, since
you know your changes best and I am busy checking certain parts of the
Elisp manual.

Sincerely,

Luc.

Re: C-h C-i

[Richard Stallman]

    Apart from these changes, I documented all installed changes briefly
    in etc/NEWS.  So we could start documenting installed changes in the
    Info manual and add the newest changes later.

I will appreciate it if you work on this.

						   However, I don't know
    what is the right procedure for synchronizing the Emacs version of
    info.texi with the Texinfo distribution.

Write to karl@gnu.org.

Re: C-h C-i

[Richard Stallman]

    I believe that last item is supposed to be:

       ** Check the Emacs manual.

Yes, thanks.

Could you please fix that, and add an item to update info.texi?

Re: C-h C-i

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sun, 20 Jun 2004 15:18:20 -0400
> 
> I will create a file etc/FOR-RELEASE, and start it off as below.

Perhaps admin/FOR-RELEASE is a better choice, since the admin
directory is excluded from the tarball in its entirety.

Re: C-h C-i

[Richard Stallman]

    Perhaps admin/FOR-RELEASE is a better choice, since the admin
    directory is excluded from the tarball in its entirety.

You are right.  (The admin directory is new enough that I tend
to forget it exists.)

Would you like to move the file?

Re: C-h C-i

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 21 Jun 2004 22:49:02 -0400
> 
>     Perhaps admin/FOR-RELEASE is a better choice, since the admin
>     directory is excluded from the tarball in its entirety.
> 
> You are right.  (The admin directory is new enough that I tend
> to forget it exists.)
> 
> Would you like to move the file?

Will do.

Re: C-h C-i

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 21 Jun 2004 22:49:02 -0400
> 
>     Perhaps admin/FOR-RELEASE is a better choice, since the admin
>     directory is excluded from the tarball in its entirety.
> 
> You are right.  (The admin directory is new enough that I tend
> to forget it exists.)
> 
> Would you like to move the file?

Done.

Re: C-h C-i

[Luc Teirlinck]

Should we update etc/MORE.STUFF, accessible from the menu-bar under
Help, "Find Extra Packages"?  I tried:

 * Autorevert, CWarn and Follow:
   <URL:http://www.andersl.com/emacs/>

but that site apparently no longer exists.  Should we delete that
entry from etc/MORE.STUFF?

When I started doing some work on autorevert.el, I tried to contact
Anders via the email address in autorevert.el, but got no response.
Should we put:

;; Maintainer: FSF

in autorevert.el?

Sincerely,

Luc.

Re: C-h C-i

[Richard Stallman]

     * Autorevert, CWarn and Follow:
       <URL:http://www.andersl.com/emacs/>

    but that site apparently no longer exists.  Should we delete that
    entry from etc/MORE.STUFF?

Yes, we may as well.

Our other option would be to search for CWarn and Follow somewhere else.
But we have no reason to think they are tremendously important, so we may
as well do the easy thing, which is to delete the item.

Thanks for pointing this out, and please do it.

Re: C-h C-i

[Richard Stallman]

    Any objections to adding a new keybinding `C-h C-i' to `info'?

Control chars after C-h are used for commands that display specific
files.  I would rather maintain that pattern.

How many times per day do you think you would use C-h C-i
if we made that binding?

Re: Documentation for "Clone Buffers" (corrected version)

[Stefan Monnier]

[ For the record: I'm the perpetrator of the FORK argument. ]

> What I'm trying to say is that yes, the interface is not elegant.
> But it seems that both variants are equally unpopular, so we just
> need to pick one, stick to it, and make a generic solution the
> problem for all these instances.  Renaming the buffer before calling
> the function again was deemed to be good enough a long while back (I
> guess because we were not sure that using a prefix was better or
> possible at all).

The question I have is: what alternative is better.
I personally don't like the M-x rename-uniquely option too much because it
forces me to first find the-buffer-that-I-don't-want, then rename it, then
run the command I wanted to run in the first place.

The clone-buffer is a bit better in that I can just run the command and
afterwards just M-x clone-buffer, but it still brings up
the-buffer-that-I-don't-want which I might have to bury.

Maybe another generic solution would be a prefix arg which causes
a subsequent `get-buffer-create' (or somesuch) to not find the buffer it's
looking for.  I.e. after M-x magic-prefix RET calling (get-buffer-create
"*shell*") would look for *shell* and if it exists, it would rename it
uniquely, and then create a new *shell*.


        Stefan

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    Maybe another generic solution would be a prefix arg which causes
    a subsequent `get-buffer-create' (or somesuch) to not find the buffer it's
    looking for.  I.e. after M-x magic-prefix RET calling (get-buffer-create
    "*shell*") would look for *shell* and if it exists, it would rename it
    uniquely, and then create a new *shell*.

Command interfaces of this sort tend to be fragile.  You do some work
to enter the prefix that will modify the real command.  Then if you
find you need to do something else before typing the real command,
or you make a mistake typing the real command, the work of the prefix
has to be redone.

For instance, I find the C-x RET c is troublesome in this way.
It would be good to think of a less fragile interface for this.

Re: Documentation for "Clone Buffers" (corrected version)

[Juri Linkov]

Alex Schroeder <alex@emacswiki.org> writes:
> I'm sure that some users will be glad if you can devise a generic
> and elegant solution to this usability problem.  :)

A generic solution would be good because neither clone-buffer nor
rename-uniquely is perfect: in some cases clone-buffer is more
convenient because it requires only one command to create a new
buffer.  However, in some cases it produces undesirable results.
For instance, calling clone-buffer on *Async Shell Command* buffer
starts a process copy, while the user's intention might be to start
a different program in a separate async buffer.

Anyway, whether a generic solution is possible or not, it makes sense
to add standard key bindings to both of them.  Currently, there are:

M-n             clone-buffer (only in Info)
C-x 4 c         clone-indirect-buffer-other-window

The following global bindings might be added:

C-x c b         clone-buffer
C-x c i         clone-indirect-buffer
C-x c u         rename-uniquely

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

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    The following global bindings might be added:

    C-x c b         clone-buffer
    C-x c i         clone-indirect-buffer
    C-x c u         rename-uniquely

I don't think these commands merit key bindings.
M-x ren un RET is not that hard to type.

Re: Documentation for "Clone Buffers" (corrected version)

[Miles Bader]

Alan Mackenzie <acm@muc.de> writes:
> >The recommended method is to create one, do M-x rename-uniquely, then
> >switch to some other buffer and do M-x info again.  This works for all
> >sorts of special facilities.
>
> I'm rather surprised at the preference for leaving an Emacs command like
> `clone-buffers' _undocumented_.  Does this perhaps signal an intention to
> remove this command from Emacs?  If so, why?

I missed the start of this thread, but what's _wrong_ with documenting
clone-buffer for this case?  It's more convenient than rename-uniquely,
works great, and even already has a convenient keybinding in Info-mode.

-Miles
-- 
`The suburb is an obsolete and contradictory form of human settlement'

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    >The recommended method is to create one, do M-x rename-uniquely, then
    >switch to some other buffer and do M-x info again.  This works for all
    >sorts of special facilities.

    Ah, right!  :-)  That's anything but user-friendly, though.  It's also
    difficult to work out from the documentation.  I couldn't find any hint
    of this procedure in the Info info pages, which is the first place I
    looked, a year or three ago.

It is documented, but perhaps there should be more references to it
in other parts of the manual.

It is almost as easy as clone-buffer.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    I'm rather surprised at the preference for leaving an Emacs command like
    `clone-buffers' _undocumented_.  Does this perhaps signal an intention to
    remove this command from Emacs?  If so, why?

Just because someone added the command does not mean
we have to put it in the Emacs manual.

The Emacs manual does not attempt to document all Emacs features.
Probably half of them are not included.  It would be a bad idea to add
them; that would make the book too expensive.  Please don't think they
are "missing".

Re: Documentation for "Clone Buffers" (corrected version)

[Alan Mackenzie]

On Wed, 10 Mar 2004, Richard Stallman wrote:

>    I'm rather surprised at the preference for leaving an Emacs command
>    like `clone-buffers' _undocumented_.  Does this perhaps signal an
>    intention to remove this command from Emacs?  If so, why?

>Just because someone added the command does not mean we have to put it
>in the Emacs manual.

I find that truly surprising.  The quality of the Emacs documentation is
one of its most attractive features.  Certainly when compared with the
dire gobbledygook which accompanies some proprietary competitors.

>The Emacs manual does not attempt to document all Emacs features.
>Probably half of them are not included.  It would be a bad idea to add
>them; that would make the book too expensive.  Please don't think they
>are "missing".

Ah, right, the book.  I hadn't thought of that, and most people round
emacs-devel probably never use it anyway.  But it's presumably an
important source of income for the FSF.  It would seem there are three
desirable attributes goals for the manual:

1/- It should be complete and accurate.
2/- The printed and online versions should be the same.
3/- The printed version should not be too big.

We can decide upon any two of these, but we can't have all three at the
same time.  :-(

Those undocumented features _are_ missing from the manual.  But it's good
to know that there's a sound reason for this, rather than just
forgetfulness on the part of developers.

Thanks for the elucidation.

-- 
Alan Mackenzie (Munich, Germany)

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> Date: Thu, 11 Mar 2004 14:55:54 +0000 (GMT)
> From: Alan Mackenzie <acm@muc.de>
> 
> >The Emacs manual does not attempt to document all Emacs features.
> >Probably half of them are not included.  It would be a bad idea to add
> >them; that would make the book too expensive.  Please don't think they
> >are "missing".
> 
> Ah, right, the book.  I hadn't thought of that, and most people round
> emacs-devel probably never use it anyway.  But it's presumably an
> important source of income for the FSF.  It would seem there are three
> desirable attributes goals for the manual:
> 
> 1/- It should be complete and accurate.
> 2/- The printed and online versions should be the same.
> 3/- The printed version should not be too big.
> 
> We can decide upon any two of these, but we can't have all three at the
> same time.  :-(

Yes we can: we could make a separate manual that isn't printed as part
of the Emacs manual.  Then users can print it on their own.

We already do that for several major Emacs features.

Any volunteers?

Re: Documentation for "Clone Buffers" (corrected version)

[David Kastrup]

Eli Zaretskii <eliz@elta.co.il> writes:

> > Date: Thu, 11 Mar 2004 14:55:54 +0000 (GMT)
> > From: Alan Mackenzie <acm@muc.de>
> > 
> > 1/- It should be complete and accurate.
> > 2/- The printed and online versions should be the same.
> > 3/- The printed version should not be too big.
> > 
> > We can decide upon any two of these, but we can't have all three
> > at the same time.  :-(
> 
> Yes we can: we could make a separate manual that isn't printed as part
> of the Emacs manual.  Then users can print it on their own.
> 
> We already do that for several major Emacs features.

In the TeXbook by Knuth, we have "dangerous bend" sections marked by
the corresponding traffic sign, and "double dangerous bend" marked by
two such signs.  Those sections are printed in smaller print and
indicate increasingly complicated material that the normal user will
not usually need to bother himself with.

If one would mark up sections in the Emacs manual (or other info
manuals) like that, one could generate a normal user manual and a more
expensive (complete) expert manual where the user manual omits the
more complicated stuff.  The online version would be complete, but
maybe fold the more intricated stuff unless indicated otherwise by
variable settings or unless a search or index search hits there.  With
regard to index searches, one would probably exhaust the "simple"
sections first before going into the "complicated" ones.

Whether this is a good idea is a different question.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: 14 Mar 2004 10:48:41 +0100
> 
> If one would mark up sections in the Emacs manual (or other info
> manuals) like that, one could generate a normal user manual and a more
> expensive (complete) expert manual where the user manual omits the
> more complicated stuff.

Alternatively, we could have appendices with the less important stuff
that are surrounded by @ifnottex..@end ifnottex, which would exclude
them from the printed version.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    > If one would mark up sections in the Emacs manual (or other info
    > manuals) like that, one could generate a normal user manual and a more
    > expensive (complete) expert manual where the user manual omits the
    > more complicated stuff.

    Alternatively, we could have appendices with the less important stuff
    that are surrounded by @ifnottex..@end ifnottex, which would exclude
    them from the printed version.

It is cleaner to put them in separate manuals
as we now do.

Re: Documentation for "Clone Buffers" (corrected version)

[Matthew Mundell]

David Kastrup <dak@gnu.org> writes:

> Eli Zaretskii <eliz@elta.co.il> writes:
>
> > > Date: Thu, 11 Mar 2004 14:55:54 +0000 (GMT)
> > > From: Alan Mackenzie <acm@muc.de>
> > >
> > > 1/- It should be complete and accurate.
> > > 2/- The printed and online versions should be the same.
> > > 3/- The printed version should not be too big.
> > >
> > > We can decide upon any two of these, but we can't have all three
> > > at the same time.  :-(
> >
> > Yes we can: we could make a separate manual that isn't printed as part
> > of the Emacs manual.  Then users can print it on their own.
> >
> > We already do that for several major Emacs features.
>
> In the TeXbook by Knuth, we have "dangerous bend" sections marked by
> the corresponding traffic sign, and "double dangerous bend" marked by
> two such signs.  Those sections are printed in smaller print and
> indicate increasingly complicated material that the normal user will
> not usually need to bother himself with.
>
> If one would mark up sections in the Emacs manual (or other info
> manuals) like that, one could generate a normal user manual and a more
> expensive (complete) expert manual where the user manual omits the
> more complicated stuff.  The online version would be complete, but
> maybe fold the more intricated stuff unless indicated otherwise by
> variable settings or unless a search or index search hits there.  With
> regard to index searches, one would probably exhaust the "simple"
> sections first before going into the "complicated" ones.

This could also be used to exclude platform-specific material and
references to proprietary work.

>
> Whether this is a good idea is a different question.
>
> --
> David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Documentation for "Clone Buffers" (corrected version)

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
> Yes we can: we could make a separate manual that isn't printed as part
> of the Emacs manual.  Then users can print it on their own.
>
> We already do that for several major Emacs features.

Making a separate manual is reasonable only for a big Emacs package
like Ediff, Eshell, Gnus, or other 30 packages currently having a
separate Info manual.  However, placing smaller Emacs features into
a separate manual is very inconvenient for users, because when they
are trying for find a needed Emacs feature by searching the Emacs
manual or by looking its index they might miss them.  Currently,
there is only one Info manual that don't correspond to a separate
Emacs package: it is Autotype.  It describes some small Emacs features,
and even most of its references lead to the Emacs manual, so it really
looks like a part of the Emacs manual.  I think Autotype should be
moved to the Emacs manual.

BTW, is there a reason for not including references to SES and SMTP
manuals into the `emacs/info/dir' file?

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

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Mon, 15 Mar 2004 07:18:08 +0200
> 
> Eli Zaretskii <eliz@elta.co.il> writes:
> > Yes we can: we could make a separate manual that isn't printed as part
> > of the Emacs manual.  Then users can print it on their own.
> >
> > We already do that for several major Emacs features.
> 
> Making a separate manual is reasonable only for a big Emacs package
> like Ediff, Eshell, Gnus, or other 30 packages currently having a
> separate Info manual.  However, placing smaller Emacs features into
> a separate manual is very inconvenient for users, because when they
> are trying for find a needed Emacs feature by searching the Emacs
> manual or by looking its index they might miss them.

We could add a feature that would look in those other manuals as
well.  In fact, it would be a good idea even now, as packages like
Eshell and Gnus are parts of Emacs, so there's no need to force the
user to know how we subdivide the Emacs docs.

We already do something similar for "C-h F", for example.

> Currently,
> there is only one Info manual that don't correspond to a separate
> Emacs package: it is Autotype.  It describes some small Emacs features,
> and even most of its references lead to the Emacs manual, so it really
> looks like a part of the Emacs manual.  I think Autotype should be
> moved to the Emacs manual.

That was already discussed a few years ago, and Richard asked not to
include it in the manual, for the same reasons he explained in this
thread the other day: the sheer volume of the printed manual and its
price.

> BTW, is there a reason for not including references to SES and SMTP
> manuals into the `emacs/info/dir' file?

A simple omission; these manuals are relatively new additions.  (It is
IMHO the job of the person who adds a new manual to update info/dir.)

Feel free to add them.

Re: Documentation for "Clone Buffers" (corrected version)

[Stefan Monnier]

> That was already discussed a few years ago, and Richard asked not to
> include it in the manual, for the same reasons he explained in this
> thread the other day: the sheer volume of the printed manual and its
> price.

We could also move out some package descriptions.  For example, the
VC doc could be moved out of man/files.texi.

>> BTW, is there a reason for not including references to SES and SMTP
>> manuals into the `emacs/info/dir' file?

> A simple omission; these manuals are relatively new additions.  (It is
> IMHO the job of the person who adds a new manual to update info/dir.)

I never even noticed it since I locally removed info/dir a long time ago
and let install-info add things for me.


        Stefan

Re: Documentation for "Clone Buffers" (corrected version)

[Luc Teirlinck]

Stefan Monnier wrote:

   >> BTW, is there a reason for not including references to SES and SMTP
   >> manuals into the `emacs/info/dir' file?

   > A simple omission; these manuals are relatively new additions.  (It is
   > IMHO the job of the person who adds a new manual to update info/dir.)

   I never even noticed it since I locally removed info/dir a long time ago
   and let install-info add things for me.

What is the exact function of emacs/info/dir?  I thought it was some
obsolete file.

Back in September, I noticed that SES was not listed im my (dir)Top
under Emacs.  I tried adding SES to emacs/info/dir.  It had no effect
whatsoever.  I noticed that other recent additions were not listed in
emacs/info/dir.  I then checked how they got added to (dir)Top.  It
was through Makefile.in.  So I made changes to Makefile.in to include
SES in the same way and sent a patch to emacs-devel, asking whether
that was the right way to proceed (since I had never done this before)
with cc to Jonathan Yavner, the author of SES.  It was one of those
prolonged periods that mail to emacs-devel apparently got redirected
to /dev/null and after a while Jonathan asked me why I was not
installing my patch.  My patch definitely worked and I installed it as
revision 1.283 to Makefile.in.  That definitely seemed to work on my
operating system, whereas adding something to emacs/info/dir did not
seem to.

Sincerely,

Luc.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> Date: Mon, 15 Mar 2004 08:35:14 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> What is the exact function of emacs/info/dir?

It is the DIR file for the manuals that come with Emacs.  Info uses it
to generate the "DIR" node, which is a concatenation of all the DIR
files it finds along the Info search path.

> Back in September, I noticed that SES was not listed im my (dir)Top
> under Emacs.  I tried adding SES to emacs/info/dir.  It had no effect
> whatsoever.

What effect you were looking for?  The effect should be visible if
you type `d' inside the *info* buffer.

With the stand-alone Info reader, typing "info SES" should succeed if
SES is in info/dir and would probably fail if it isn't (although
latest versions of the stand-alone reader might find the SES manual
even if it isn't in info/dir).

>  I noticed that other recent additions were not listed in
> emacs/info/dir.  I then checked how they got added to (dir)Top.  It
> was through Makefile.in.

Makefile.in takes care of adding the entries to the system-wide DIR
file when you say "make install".  But until you do say "make
install", the Emacs binary invoked from its source tree uses the DIR
file supplied with the distribution.

Re: Documentation for "Clone Buffers" (corrected version)

[Luc Teirlinck]

Eli Zaretskii wrote:

   > Back in September, I noticed that SES was not listed im my (dir)Top
   > under Emacs.  I tried adding SES to emacs/info/dir.  It had no effect
   > whatsoever.

   What effect you were looking for?  The effect should be visible if
   you type `d' inside the *info* buffer.

If you invoke the Emacs binary from the source tree?  If I remember
well, I tried it with the installed version.

   Makefile.in takes care of adding the entries to the system-wide DIR
   file when you say "make install".  But until you do say "make
   install", the Emacs binary invoked from its source tree uses the DIR
   file supplied with the distribution.

Anyway, the problem seems trivial to fix.  Do I need to do anything
more than the following patch?  I could install that right now, if it
is OK.

===File ~/dir-diff==========================================
*** dir.~1.25.~	Wed Jul  9 13:10:41 2003
--- dir	Mon Mar 15 14:31:56 2004
***************
*** 46,51 ****
--- 46,52 ----
  * MIME: (emacs-mime).   Emacs MIME de/composition library.
  * SC: (sc).		Supercite lets you cite parts of messages you're 
  			  replying to, in flexible ways.
+ * SMTP: (smtpmail).     Emacs library for sending mail via SMTP.
  
  * Autotype: (autotype). Convenient features for text that you enter frequently
                            in Emacs.
***************
*** 55,60 ****
--- 56,62 ----
  * Forms: (forms).	Emacs package for editing data bases
  			  by filling in forms.
  * RefTeX: (reftex).	Emacs support for LaTeX cross-references and citations.
+ * SES: (ses).           Simple Emacs Spreadsheet
  * Tramp: (tramp).	Transparent Remote (file) Access, Multiple Protocol.
                            Edit remote files via a remote shell (rsh,
                            ssh, telnet).
============================================================

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: 15 Mar 2004 08:34:47 -0500
> 
> I never even noticed it since I locally removed info/dir a long time ago
> and let install-info add things for me.

We could modify Makefile's to produce info/dir as part of the
installation, but then the order of the items in the menu will be
different from what it is now.  In particular, "Info" will not be the
first item and "Emacs" will not be the second one.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    We could also move out some package descriptions.  For example, the
    VC doc could be moved out of man/files.texi.

VC is a very important feature, worth documenting in the manual.

Re: Documentation for "Clone Buffers" (corrected version)

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
>> From: Juri Linkov <juri@jurta.org>
>> Date: Mon, 15 Mar 2004 07:18:08 +0200
>> Making a separate manual is reasonable only for a big Emacs package
>> like Ediff, Eshell, Gnus, or other 30 packages currently having a
>> separate Info manual.  However, placing smaller Emacs features into
>> a separate manual is very inconvenient for users, because when they
>> are trying for find a needed Emacs feature by searching the Emacs
>> manual or by looking its index they might miss them.
>
> We could add a feature that would look in those other manuals as
> well.  In fact, it would be a good idea even now, as packages like
> Eshell and Gnus are parts of Emacs, so there's no need to force the
> user to know how we subdivide the Emacs docs.

It would be very good to make a composite index from all Emacs
manuals.  It could be implemented as a separate Info file with
references to nodes of other manuals.

Another good thing that could be implemented in Emacs is the --apropos
feature of the standalone Info browser.

Seems it's what people need very much, because they often place an index
of an Info file into dir buffer.  The worst case I know is the libc.info
which places into dir buffer its own huge index with 1700 entries!
It's very inconvenient for users: it takes too much time to display this
dir buffer and to browse it.  If there was a feature for looking up an
entry in all indices then dir would contain only references to Top nodes
of every Info manual.

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

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Tue, 16 Mar 2004 09:05:54 +0200
> 
> > We could add a feature that would look in those other manuals as
> > well.  In fact, it would be a good idea even now, as packages like
> > Eshell and Gnus are parts of Emacs, so there's no need to force the
> > user to know how we subdivide the Emacs docs.
> 
> It would be very good to make a composite index from all Emacs
> manuals.  It could be implemented as a separate Info file with
> references to nodes of other manuals.

I don't think we need to physically bring all the indices together, we
just need to have Emacs command look into all of these indices as
appropriate.

> Another good thing that could be implemented in Emacs is the --apropos
> feature of the standalone Info browser.

Full agreement.

> Seems it's what people need very much, because they often place an index
> of an Info file into dir buffer.  The worst case I know is the libc.info
> which places into dir buffer its own huge index with 1700 entries!

I think this is a bug in glibc's manual.

Re: Documentation for "Clone Buffers" (corrected version)

[Juri Linkov]

"Eli Zaretskii" <eliz@elta.co.il> writes:
> I don't think we need to physically bring all the indices together, we
> just need to have Emacs command look into all of these indices as
> appropriate.
>
>> Another good thing that could be implemented in Emacs is the --apropos
>> feature of the standalone Info browser.
>
> Full agreement.

I wanted to implement it, but noticed that it is already implemented
by Jesper Harder: http://purl.org/harder/info-apropos.el.
It is essentially only one function which does all the work.
I think this is a useful feature and could be added to info.el.

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

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    > Seems it's what people need very much, because they often place an index
    > of an Info file into dir buffer.

what deoes that mean?

					The worst case I know is the libc.info
    > which places into dir buffer its own huge index with 1700 entries!

    I think this is a bug in glibc's manual.

if so can u wrt to glibc mtnrs?

Re: Documentation for "Clone Buffers" (corrected version)

[Karl Berry]

    which places into dir buffer its own huge index with 1700 entries!

The underlying issue, to my knowledge, is that for info to be as
convenient as man, it needs to have dir entries for every command, every
function, etc.  (This is different than every index entry, although of
course the bulk of the index consists of such names.)  This has been an
unresolved issue with the info system since day 1.

Having a single dir buffer with every possible name is infeasible, as
you say.  It's obviously not useful for the user to have to browse
through a dir node with 1700 entries from glibc.  On the other hand, I
can't exactly call it a "bug" in the glibc manual, it's trying to do the
only thing available.  (I assume it's not literally putting every index
entry into dir, just the function etc. names -- that was true last time
I looked at it.)

The only long-term solution I've been able to think of is to allow
subnodes of (dir) and have the info readers look through the subnodes
when asked for a given top-level name -- but not load or display the
info in all the subnodes when showing the dir node itself.

If anyone has any other bright ideas, just speak up ...

thanks,
k

Re: Documentation for "Clone Buffers" (corrected version)

[Stefan Monnier]

> The only long-term solution I've been able to think of is to allow
> subnodes of (dir) and have the info readers look through the subnodes
> when asked for a given top-level name -- but not load or display the
> info in all the subnodes when showing the dir node itself.

IIRC, Emacs's Info reader already allows the `dir' file to contain several
nodes, just like any other Info package.  Since I've never seen such
a `dir' file, I have no idea whether it works or not.

Another alternative is to have Info do an index search on some of the
entries if nothing was found in the `dir' file.
Which entries should be auto-searched this way could be specified via any
number of ways.

BTW, why does `info FOO BAR' only look for BAR in the menu of FOO instead
of (or additionally to) looking for it in the Index?


        Stefan

Re: Documentation for "Clone Buffers" (corrected version)

[Karl Berry]

    BTW, why does `info FOO BAR' only look for BAR in the menu of FOO instead
    of (or additionally to) looking for it in the Index?

No one has ever suggested it, to my knowledge.
I suppose it wouldn't hurt to look in the index(es) if it can't find a
matching menu entry.

Re: Documentation for "Clone Buffers" (corrected version)

[Stefan Monnier]

>     BTW, why does `info FOO BAR' only look for BAR in the menu of FOO instead
>     of (or additionally to) looking for it in the Index?

> No one has ever suggested it, to my knowledge.

Well, now it's done ;-)


        Stefan "whose `info' script used to do that (using Emacs's `info')"

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    > No one has ever suggested it, to my knowledge.

    Well, now it's done ;-)

Does it handle the case of multiple indices?

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: 18 Mar 2004 13:53:17 -0500
> 
> IIRC, Emacs's Info reader already allows the `dir' file to contain several
> nodes, just like any other Info package.

That would not solve the problem at hand, since the reader looks for
the command-line argument in the DIR _node_, not in DIR the file.

> Another alternative is to have Info do an index search on some of the
> entries if nothing was found in the `dir' file.

We could try that, but I'm not sure it will do what users want to be
done.  Index entries normally include many items that have no relation
to function names; about the only exception to this rule is a library
reference, and even then it's only true for the function index (what
about concept and other indices?).

> BTW, why does `info FOO BAR' only look for BAR in the menu of FOO instead
> of (or additionally to) looking for it in the Index?

The actual feature is more general.  If you say

    	   info PACKAGE FOO BAR BAZ

then the reader looks for FOO in PACKAGE's top-level menu, then for
BAR in the node pointed to by FOO, then for BAZ in the node pointed by
BAR, etc.  In other words, if you know the menu path to the node, you
can get to it like that without knowing the node names.  For a typical
libc, "info libc index strcpy" will show the section taht describes
strcpy (as will probably "info -n strcpy", but for the latter you need
to be sure the node is called "strcpy", not something like "string
functions").

Re: Documentation for "Clone Buffers" (corrected version)

[Stefan Monnier]

>> IIRC, Emacs's Info reader already allows the `dir' file to contain several
>> nodes, just like any other Info package.

> That would not solve the problem at hand, since the reader looks for
> the command-line argument in the DIR _node_, not in DIR the file.

Indeed, I was just pointing out that part of the requirement is already met
and we'd "only" need to extend the search to look at all the nodes in
the file.

>> Another alternative is to have Info do an index search on some of the
>> entries if nothing was found in the `dir' file.

> We could try that, but I'm not sure it will do what users want to be
> done.  Index entries normally include many items that have no relation
> to function names; about the only exception to this rule is a library
> reference, and even then it's only true for the function index (what
> about concept and other indices?).

Well, it could lookup the main menu of those packages instead of their
index, if that's what you prefer.  MY main point is that instead of copying
all those entries into the `dir' file it would be better to have a way to
say "and look at these other nodes as well", so you can update a libc manual
without going through the pain of figuring out which entries are obsolete
(another problem with the way the `dir' file is built right now).

BTW, my experience with my own `info' script is that using indices rather
than main menus works fairly well (i.e. the extraneous entries are not
bothersome).  But it's admittedly a very small experience and it was a few
years ago.

>> BTW, why does `info FOO BAR' only look for BAR in the menu of FOO instead
>> of (or additionally to) looking for it in the Index?

> The actual feature is more general.  If you say
>     	   info PACKAGE FOO BAR BAZ

Sure, but if menu entry BAR does not exist in FOO it may still make sense to
look for it in the index.

> In other words, if you know the menu path to the node, you can get to it
> like that without knowing the node names.  For a typical libc, "info libc
> index strcpy" will show the section taht describes strcpy (as will
> probably "info -n strcpy", but for the latter you need to be sure the node
> is called "strcpy", not something like "string functions").

But using the index, you'd just say `info libc strcpy'.  And if you tell
info to include libc's index by default, you can just say `info strcpy'
(without cluttering the dir file).

My model here is `man' where `man FOO' tries to guess in which section the
thing is placed and `man FOO BAR' looks for BAR in section FOO.
`man' is not perfect, but I find this aspect of man's interface to work
about as well as I can hope: short and precise.  The only problem I've had
with it is in the `man FOO' short form because it looks in all chapters,
but nowadays you can choose the search order of the various chapters.


        Stefan

Re: Documentation for "Clone Buffers" (corrected version)

[Karl Berry]

    info to include libc's index by default, you can just say `info strcpy'

Although automatically looking in libc's index would probably work for
90% of cases in practice, it does not solve the general problem.

    My model here is `man' 

I agree, we need a procedure for this that works as well as man's does,
without having to load thousands of dir entries by default.

Thus my original idea (although I guess I did not fully explain it):
1have one subnode of dir for commands, one for library functions, one for
file formats, etc., analogous to the man sections.  Keep the top level
dir itself for the manuals as a whole.  The subnodes would be other menu
entries as usual:

* Menu:
* Commands::
* Functions::
...
* Emacs (emacs). ...
...

Then  info commands printf
vs. info functions printf
will get the right thing.  That is, from the cmd line.  I don't know
what the best interface would be for Emacs.

As a bonus, we could make
  info 1 printf
also work by letting `1' mean the first menu entry on the cmd line (as
it does interactively)!

The search order for "info printf" could be defined externally, a la man.

Such a Functions node will get very big (there are 6200 entries in my
/usr/share/man/man3) but I don't see another answer.

We would have to change the Texinfo language and the install-info
program to allow for installing entries in such a subnode of dir.
@dircategory/@direntry do not suffice.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> Date: Fri, 19 Mar 2004 12:47:25 -0500
> From: karl@freefriends.org (Karl Berry)
> 
> Although automatically looking in libc's index would probably work for
> 90% of cases in practice, it does not solve the general problem.

I'm not even sure it solves 90% of cases, unless all of the cases
come from libc functions lookup.

>     My model here is `man' 
> 
> I agree, we need a procedure for this that works as well as man's does,
> without having to load thousands of dir entries by default.

But the Info system is _not_ `man', so some problems don't have a
solution that works as ``well'' as `man' does.

> Thus my original idea (although I guess I did not fully explain it):
> 1have one subnode of dir for commands, one for library functions, one for
> file formats, etc., analogous to the man sections.  Keep the top level
> dir itself for the manuals as a whole.

That would work, but do we really have the power to enforce such an
organization of DIR?  Unlike `man', the Info manuals are not written
by the same person/team, so coordinating all of them is much more
difficult.  Even the current guidelines that Karl tries to promote for
quite a few years now are not yet as widespread as we'd like them to
be.

> Then  info commands printf
> vs. info functions printf
> will get the right thing.  That is, from the cmd line.  I don't know
> what the best interface would be for Emacs.
> 
> As a bonus, we could make
>   info 1 printf
> also work by letting `1' mean the first menu entry on the cmd line (as
> it does interactively)!

I'd suggest instead to invest efforts in producing an Info
`apropos'-style database, so that "info printf" could search all of
the Info manuals in reasonable time.  This is localized to the Texinfo
pacakge (assuming Emacs asupports that as well), so its introduction
would be much easier.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    > Thus my original idea (although I guess I did not fully explain it):
    > 1have one subnode of dir for commands, one for library functions, one for
    > file formats, etc., analogous to the man sections.  Keep the top level
    > dir itself for the manuals as a whole.

I agree that we should find a way to collect commands, collect library
functions for C, collect file formats, etc.  However, having a node in
`dir' with a list of commands, and another with a list of library
functions, etc., seems like an inconvenient way to do it.

The feature we want is to have an index of all commands.  We could do
this by creating a node which lists all commands, combining info from
various manuals.  But we could also make the combination virtually.
Manuals could identify themselves as containing relevant entries for
a certain area, and info could search the index of each manual.

So imagine that there is a node in `dir' that has a menu which
contains all the manuals that describe commands.  When you ask to
search for a command `foo', info would find this node, find all the
manuals it points to, then search the index of each manual for `foo'.

Perhaps the existing `@dircategory' command usable for manuals to
insert themselves into these nodes when appropriate.  Karl, will it
work, or does it need some change?

In the Unix Manual, "library function" implicit means "C library
function".  GNU users use many languages; we cannot assume that
"function" means "C function".  So I think that we should have
a "manual section" for each language, which would list library
functions for that language.  You would want to do something like

  info C strcpy

to look up the C function strcpy.  `C' would specify the "section" of
the manual to look in; it would equivalent to `man 2' and `man 3'.



The other issue is precisely how to search each manual.  Searching the
index is useful in some cases, but which index?  The Emacs Manual has
a "Command Index", but searching in that index for `emacs' won't find
it.

This same example also illustrates the common case of a manual
that documentsjust a small number of commands (or whatever).
It would be silly for the Emacs manual to have an index
of shell commands, because it defines only one.

So a manual that adds itself to the node for "commands" needs to 
specify how to search that manual for a command.  There should be
at least two ways to do it:

1. Specify an index to search for a desired command name.

2. Specify specific command names documented in the manual.

We could do this with stylized menu items in the Top node.
A menu item like this

   * `emacs' Shell Command: Entering Emacs.

could specify where to find the specific command `emacs',
and a menu item like this

   * Index of Shell Commands: NODE NAME.

could specify to look for a shell command in index NODE NAME.

Likewise we could have

   * JPEG file format: NODE NAME.

or

   * Index of C Functions: NODE NAME.


    That would work, but do we really have the power to enforce such an
    organization of DIR?

Not to worry.  If we implement this and support it with GNU manuals,
people will find it useful and will adapt their manuals to fit it.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sun, 21 Mar 2004 00:00:27 -0500
> 
> So imagine that there is a node in `dir' that has a menu which
> contains all the manuals that describe commands.  When you ask to
> search for a command `foo', info would find this node, find all the
> manuals it points to, then search the index of each manual for `foo'.

If implemented naively, that could be prohibitively slow, I think.  To
get a feeling how slow, try "info --apropos=SOMETHING" with the
stand-alone Info reader.

The main problem here is, I think, that Info manuals tend to have
very large indices, and the algorithms used to search through the
index do not scale very well.

> Perhaps the existing `@dircategory' command usable for manuals to
> insert themselves into these nodes when appropriate.  Karl, will it
> work, or does it need some change?

I think we need a feature that could create and update a database like
`apropos' from the `man' package does, and then use it for fast
lookups like those suggested.  The resultant database could be written
into the DIR file, if that's what we want, but I'd suggest to keep it
separate, since it generally is not meant for human consumption, while
DIR is.

install-info could be charged with the job of maintaining the
database.

> In the Unix Manual, "library function" implicit means "C library
> function".

Not on some of the systems I work on: Fortran functions are in
section 3F, C library functions are in 3C, and there are other 3x
sections for libraries other than libc.  They all are searched if you
say "man --section=3 FOO" or its equivalent.

> You would want to do something like
> 
>   info C strcpy
> 
> to look up the C function strcpy.  `C' would specify the "section" of
> the manual to look in; it would equivalent to `man 2' and `man 3'.

Earlier in this thread, I suggested that "info libc strcpy" would do
the job (and works with the current Texinfo codebase if the libc
manual lists all the functions in the "Detailed Menu" part of its Top
node), but others say that it's too much of a burden to remember the
word "libc" in this context.

> The other issue is precisely how to search each manual.  Searching the
> index is useful in some cases, but which index?  The Emacs Manual has
> a "Command Index", but searching in that index for `emacs' won't find
> it.

I think we should not rely on automatic index searches: in my
experience, they yield too many false hits.

> So a manual that adds itself to the node for "commands" needs to 
> specify how to search that manual for a command.  There should be
> at least two ways to do it:

If we rely on humans to do any significant part of the job, why not
ask them to do it all the way?  Let's have a new Texinfo command that
will add its argument to a global index used to do searches in all the
manuals.  For example, the following directive

	  @gindex strcpy

will produce something that install-info could copy to the
system-wide database I mentioned above.

(Actually, @gindex is a bad name, since some manual could already use
it for its own private index names.)

>     That would work, but do we really have the power to enforce such an
>     organization of DIR?
> 
> Not to worry.  If we implement this and support it with GNU manuals,
> people will find it useful and will adapt their manuals to fit it.

We have a very different experience with similar issues; Karl knows
all about that, I think.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    > So imagine that there is a node in `dir' that has a menu which
    > contains all the manuals that describe commands.  When you ask to
    > search for a command `foo', info would find this node, find all the
    > manuals it points to, then search the index of each manual for `foo'.

    If implemented naively, that could be prohibitively slow, I think.  To
    get a feeling how slow, try "info --apropos=SOMETHING" with the
    stand-alone Info reader.

They are not comparable.  That searches all manuals.  I am talking about
searching a specified list of manuals.  The fraction of manuals that
register themselves as providing library functions for any given
language would be small.

However, this comparison might be valid in the case of commands,
because many manuals might define at least one command.  So in the
case of commands we might want to put the command names into the
special node of `dir'.

I think it would be a mistake to use a database that does not consist
of straightforward text.  The speed of searching text for a string is
so fast that there is no point in optimizing it.  The only thing that
might make this slow is if it needs to access too many files.  Putting
the necessary info in one fileis all the optimization needed.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 22 Mar 2004 00:24:19 -0500
> 
>     If implemented naively, that could be prohibitively slow, I think.  To
>     get a feeling how slow, try "info --apropos=SOMETHING" with the
>     stand-alone Info reader.
> 
> They are not comparable.  That searches all manuals.  I am talking about
> searching a specified list of manuals.

It was a long time since I did those experiments, but I think I saw
poor performance even when only a few manuals were visible.  I will
try to experiment again.

> However, this comparison might be valid in the case of commands,
> because many manuals might define at least one command.  So in the
> case of commands we might want to put the command names into the
> special node of `dir'.

Doesn't this require changes in install-info, and thus has one of the
2 disadvantages you mentioned in your other mail?  (FWIW, I don't
think that changes in install-info or in the language are such a
significant disadvantage.)

> I think it would be a mistake to use a database that does not consist
> of straightforward text.  The speed of searching text for a string is
> so fast that there is no point in optimizing it.

Perhaps in Emacs it is, but IIRC that's not true for the stand-alone
reader, whose search algorithm is very simple and thus inefficient
for large chunks of text.

But I agree that we should try plain text and see what is the actual
speed before we decide to do something more complex.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    If we rely on humans to do any significant part of the job, why not
    ask them to do it all the way?  Let's have a new Texinfo command that
    will add its argument to a global index used to do searches in all the
    manuals.  For example, the following directive

	      @gindex strcpy

    will produce something that install-info could copy to the
    system-wide database I mentioned above.

This has two major disadvantages.

1. It fails to catagorize the names.  I don't want to have command
   names mixed up with C functions and Perl functions and Lisp
   functions and file formats.

2. It requires changes in texinfo itself.  I am seeking a
   solution that does not require any changes in makeinfo
   or install-info.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> 
> 	      @gindex strcpy
> 
>     will produce something that install-info could copy to the
>     system-wide database I mentioned above.
> 
> This has two major disadvantages.
> 
> 1. It fails to catagorize the names.  I don't want to have command
>    names mixed up with C functions and Perl functions and Lisp
>    functions and file formats.

This one can be easily fixed by adding a category argument to the new
directive.

> 2. It requires changes in texinfo itself.  I am seeking a
>    solution that does not require any changes in makeinfo
>    or install-info.

I think we will need changes at least in install-info, since DIR file
will have to be changed, or else an external database will need to be
created.  If we leave DIR as it is now, and rely on the Info reader to
generate the additional nodes/data structures, the startup time will
become slow, and the `man'-style "info strcpy" feature, which assumes
that the reader is launched anew for each query, will be impossible.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    I think we will need changes at least in install-info, since DIR file
    will have to be changed, or else an external database will need to be
    created.

Let's please first turn our attention to proposals
that do not require changes in install-info.  Only if we cannot
get that to work should we turn our attention to other solutions.

    > However, this comparison might be valid in the case of commands,
    > because many manuals might define at least one command.  So in the
    > case of commands we might want to put the command names into the
    > special node of `dir'.

    Doesn't this require changes in install-info

I don't see why.  I proposed one method which gets the job
done without any changes in install-info.

Re: Documentation for "Clone Buffers" (corrected version)

[Karl Berry]

    Perhaps the existing `@dircategory' command usable for manuals to
    insert themselves into these nodes when appropriate.  Karl, will it
    work, or does it need some change?

In your proposal of messing with Top node menus, I don't see that
@dircategory matters at all.  The Info readers read the top-level dir
file, get the list of Info manuals to look in, then go look at each of
their Top menus to virtually construct the list of whatever the user is
interested in.  Do I have the general idea right?

I know you said that having subnodes seems inconvenient to you, but I
don't understand why.  Putting the information physically into the dir
file via install-info, just as we do now with existing dir entries,
seems a lot simpler to me.  And then the Info readers only have to look
at the dir file, rather than delving into every manual.

Along that line, what comes to my mind is a second optional argument to
@dircategory, specifying the subnode of dir to use (Shell Commands, C
Functions, or whatever).  I think we can then use @direntry as usual.
For example, in the case you mention when there's just a few entries --

@dircategory GNU Emacs, Shell Commands
@direntry
* emacs: (emacs)Entering Emacs.  Extensible, customizable,
                                 self-documenting, real-time display editor.
* emacsclient: (emacs)Invoking emacsclient.  Blah blah.
* etags: (emacs)Create Tags Table.  Blah blah.
@end direntry

No changes would be made in emacs.texi's Top node menu.

Entries similar to this already exist in many manuals.  (So people can
type "info ls", for example, and get the ls documentation.  This is very
useful.)  It will be easy to change them to specify subnodes.

install-info could then insert the given entries into a subnode of dir
named "Shell Commands", in a category "GNU Emacs'.  (Such dir categories
wouldn't be used by the Info readers, but they could help humans
browsing through the nodes, just as categories in the main dir node do now.)

Then, people can say
  info 'Shell Commands' emacsclient

(I'm not sure about "Shell Commands" vs. "Commands", but the exact names
are clearly a secondary issue.)

Also, we could support simply
  info emacsclient
by having the info readers search the subnodes, in some user-definable
order, when no matching entry is in the top-level dir node.


I also agree that it can be useful to be able to point to a whole index,
for example, the glibc function index.  Here is a suggestion for that:

@dircategory libc, C
@direntry
* :(libc)Function and Macro Index.
* :(libc)Type Index.
* :(libc)Variable Index.
@end direntry

The lack of any menu term tells the info readers that it's an indirection.
Or we could put a keyword there, such as "INFOINDEX".  Whatever.


Eli, about --apropos.  If the dir file, with all its subnodes, plus
index indirections, becomes a more complete listing of what is available
on the system, then I think an apropos command could search that instead
of just searching all the indexes of all the manuals.  The new dir file
will have the names, but more importantly the descriptions (where
available).  This would be more analogous to man's apropos, which I find
quite useful on occasion.

Which brings up the point that it would be *ideal* if manual writers
create separate @direntries for each function name, so that descriptions
are available for searching:

@dircategory libc, C
@direntry
* strcmp:(libc)Whatever.  Compare two strings.
@end direntry

Then users could say, hypothetically, "info-apropos compare" and get a
match, just as they can now with man -k.

However, since no existing manuals do that (except for commands, in some
cases), and since documentation time is a precious commodity, falling
back to being able to look at an index seems quite worthwhile.


Anyway, those are my thoughts.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    In your proposal of messing with Top node menus, I don't see that
    @dircategory matters at all.  The Info readers read the top-level dir
    file, get the list of Info manuals to look in, then go look at each of
    their Top menus to virtually construct the list of whatever the user is
    interested in.  Do I have the general idea right?

Partly.  It would not read all of the dir file, just a subnode.  It
would not make the list based on the entire Top node menus as a whole;
rather, it would obey certain special entries in them.

The point of using @dircategory is to put entries for certain manuals
into the subnode of dir.

    Along that line, what comes to my mind is a second optional argument to
    @dircategory, specifying the subnode of dir to use (Shell Commands, C
    Functions, or whatever).

I don't understand why this optional argument is necessary.  Can't
@dircategory already do this job with no change, if we set up the dir
file properly?

If you think this won't work, could you explain the precise problem?

    install-info could then insert the given entries into a subnode of dir
    named "Shell Commands", in a category "GNU Emacs'.

I don't see a need for categories within the menu in the Shell
Commands node.  That node would exist specifically for man-style
lookup.  The order of manuals within that node would not matter.

So it only needs to have one category, which could be called Shell
Commands.  All the manual needs is

  @dircategory Shell Commands

This way, no changes are needed in the specifications of the Texinfo
language.  People could change manuals starting immediately, without
waiting to be able to install a new version of Texinfo.

    Then, people can say
      info 'Shell Commands' emacsclient

They could, but that's awfully clumsy.  We would want to change info
so that something simpler can be used, such as

      info command emacsclient

Users won't get the benefit of that improvement until they install a
new version of Texinfo.  Perhaps that is unavoidable, but at least it
doesn't lengthen the critical path.

    Which brings up the point that it would be *ideal* if manual writers
    create separate @direntries for each function name, so that descriptions
    are available for searching:

    @dircategory libc, C
    @direntry
    * strcmp:(libc)Whatever.  Compare two strings.
    @end direntry

That is what I am trying to avoid!

There is no reason to clutter up the dir file by copying large amounts
of text from a few manuals.  It is much better for info readers to
search those few other manuals when the time comes.

The only case where it is worth copying the information into the dir
file is when it comes from many different manuals.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 22 Mar 2004 00:25:15 -0500
> 
>     In your proposal of messing with Top node menus, I don't see that
>     @dircategory matters at all.  The Info readers read the top-level dir
>     file, get the list of Info manuals to look in, then go look at each of
>     their Top menus to virtually construct the list of whatever the user is
>     interested in.  Do I have the general idea right?
> 
> Partly.  It would not read all of the dir file, just a subnode.

That would require a fundamental change in the Info reader.
Currently, both Emacs and the stand-alone reader cannot read a single
node, they always read the entire file and then create several data
structures from its contents, before they even look at the first node.
An Info file can include tag tables and indirect tables that need to
be processed as part of this.

> The point of using @dircategory is to put entries for certain manuals
> into the subnode of dir.
> 
>     Along that line, what comes to my mind is a second optional argument to
>     @dircategory, specifying the subnode of dir to use (Shell Commands, C
>     Functions, or whatever).
> 
> I don't understand why this optional argument is necessary.  Can't
> @dircategory already do this job with no change, if we set up the dir
> file properly?

I think Karl wants DIR to have both its current top-level, include-all
menu, and the separate nodes, one each for each category.

If we want each category to go into a separate node of DIR, that would
require a relatively simple change to install-info, but it does have
its disadvantages: no single menu with all the manuals listed in it,
and no simple way of updating the DIR file except through
install-info.

But I, too, feel I don't understand your vision sufficiently well.
Could you perhaps describe an approximate sequence of operations to be
used by an Info reader to do what you want, starting with a sample
command line?

>     install-info could then insert the given entries into a subnode of dir
>     named "Shell Commands", in a category "GNU Emacs'.
> 
> I don't see a need for categories within the menu in the Shell
> Commands node.  That node would exist specifically for man-style
> lookup.  The order of manuals within that node would not matter.
> 
> So it only needs to have one category, which could be called Shell
> Commands.  All the manual needs is
> 
>   @dircategory Shell Commands

I don't think it's quite that simple, unfortunately.  Take the GNU
Make manual, for example: it mainly describes the features of Make
itself, not `make' as a shell command.  So its @dircategory and
@direntry currently say

    @dircategory GNU Packages
    @direntry
    * Make: (make).            Remake files automatically.
    @end direntry

AFAIU, you want the manual author to provide 2 categories: one as
above, the other saying something like

    @dircategory Shell Commands
    @direntry
    * Make: (make)Running.     How to invoke GNU Make from the shell.
    @end direntry

and you want install-info to put each one of these menu items into a
different node: one node for "GNU Packages", the other for "Shell
Commands".  Is that true?

The main disadvantage of this, as I see it, is that manuals will now
require quite a few different @dircategory/@direntry directives,
carefully thought out in terms of the resultant DIR organization.
Past experience suggests that it is not easy to force DIR
organization, especially since a coordinated effort of all GNU
maintainers is required.

That is why a more automated way of gleaning the necessary information
from indices and top-level menus might be a better approach, as it
requires less coordination between numerous humans.

(As an aside, the current stand-alone Info reader's solution to
quickly arrive at the node for Make that describes its usage as a
shell command is to say

	info --usage make

That lands you in the Running node without any help from @direntry,
and provides the same functionality as the "man make" command.)

> This way, no changes are needed in the specifications of the Texinfo
> language.  People could change manuals starting immediately, without
> waiting to be able to install a new version of Texinfo.

In practice, they do need to wait for a new Texinfo, since any change
in the organization of DIR requires changes in install-info at least.
The change you propose seems to require changes in the Info readers as
well.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

      The Info readers read the top-level dir
    >     file, get the list of Info manuals to look in, then go look at each of
    >     their Top menus to virtually construct the list of whatever the user is
    >     interested in.  Do I have the general idea right?
    > 
    > Partly.  It would not read all of the dir file, just a subnode.

    That would require a fundamental change in the Info reader.
    Currently, both Emacs and the stand-alone reader cannot read a single
    node,

We are miscommunicating.  You're talking literally about
reading a file into memory.  I was talking about reading text
to find which manuals to look in.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    > I don't understand why this optional argument is necessary.  Can't
    > @dircategory already do this job with no change, if we set up the dir
    > file properly?

    I think Karl wants DIR to have both its current top-level, include-all
    menu, and the separate nodes, one each for each category.

Yes, that's what I was saying too.

    If we want each category to go into a separate node of DIR, that would
    require a relatively simple change to install-info, 

That is not what I suggested.  My suggestion is much simpler:
create a few specific categories and put them in subnodes.

The Make manual now says:

    @dircategory GNU Packages
    @direntry
    * Make: (make).            Remake files automatically.
    @end direntry

My proposal would change that to

    @dircategory GNU Packages
    @dircategory Shell Commands
    @direntry
    * Make: (make).            Remake files automatically.
    @end direntry

I have the feeling that the proposal you're criticizing
is not the one I proposed.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 22 Mar 2004 22:04:10 -0500
> 
>     If we want each category to go into a separate node of DIR, that would
>     require a relatively simple change to install-info, 
> 
> That is not what I suggested.  My suggestion is much simpler:
> create a few specific categories and put them in subnodes.

How is that simpler (or do I again misunderstand you)?  The category
name that appears in the @dircategory directive is arbitrary text;
install-info knows nothing about it, it just copies it verbatim to DIR
and groups together @direntry groups that appear within the same
@dircategory.  The only way for DIR to have only a small number of
categories is to ask the manual authors to exercise self-discipline
and use a small set of standard categories.  (The current list of
recommended categories appears in the node "Installing Dir Entries" in
the Texinfo manual.)

[I'm sure I didn't say anything you didn't know already, but I'm
writing this to make my thoughts explicit, so that you or someone else
could point out what is it that I misunderstand.]

Are you suggesting that install-info treats a few categories, like
"Shell Commands" and "Library Functions", specially?  Or are you
suggesting that the modifications of the @dircategory groups should be
the responsibility of manual maintainers, and that the ``few specific
categories'' would be created because the manual maintainers use them
in such a disciplined manner?

> The Make manual now says:
> 
>     @dircategory GNU Packages
>     @direntry
>     * Make: (make).            Remake files automatically.
>     @end direntry
> 
> My proposal would change that to
> 
>     @dircategory GNU Packages
>     @dircategory Shell Commands
>     @direntry
>     * Make: (make).            Remake files automatically.
>     @end direntry

Okay, but what will this produce in DIR?  Do you want the named
@direntry go to 2 nodes in DIR, one for "GNU Packages", the other for
"Shell Commands"?

Also, the second form above, the one you proposed, does not work with
the current versions of install-info: install-info needs one or more
@direntry's between any two @dircategory's, not the other way around.
In other words, if a manual wants to install menu items in more than
one category, it needs to list those entries several times, one each
for every category.  So to be compatible with the current codebase,
your example above needs to become

    @dircategory GNU Packages
    @direntry
    * Make: (make).            Remake files automatically.
    @end direntry

    @dircategory Shell Commands
    @direntry
    * Make: (make).            Remake files automatically.
    @end direntry

Btw, as I wrote elsewhere in this thread, it might be more
user-friendly for each category to point to a different node in the
manual: in our Make example, people who look for the description of
`make' the shell command are more likely to wish to see the node that
describes how to run Make and what are its command-line switches.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

I am so limited in the work time I can do at present that I cannot
try to explain any further.  I hope that someone else understood
what I proposed.

Sorry.

Re: Documentation for "Clone Buffers" (corrected version)

[Stefan Monnier]

>> Although automatically looking in libc's index would probably work for
>> 90% of cases in practice, it does not solve the general problem.

> I'm not even sure it solves 90% of cases, unless all of the cases
> come from libc functions lookup.

That depends on the list of manuals.  Ideally this list should be
user-specific, so the user can decide to lookup libc and stuff first but if
she never uses C she might prefer to lookup elisp first.


        Stefan

Re: Documentation for "Clone Buffers" (corrected version)

[Stefan Monnier]

>     info to include libc's index by default, you can just say `info strcpy'
> Although automatically looking in libc's index would probably work for
> 90% of cases in practice, it does not solve the general problem.

Without reading the user's mind, there's no way to handle `info strcpy'
100%, and neither does `man' handle it 100% (for the same reason).  So what
you're saying here is not a criticism, unless you mean some specific
problem, but I can't read your mind either.

> Thus my original idea (although I guess I did not fully explain it):
> 1have one subnode of dir for commands, one for library functions, one for
> file formats, etc., analogous to the man sections.  Keep the top level
> dir itself for the manuals as a whole.  The subnodes would be other menu
> entries as usual:

>From a speed point of view, it might be good to put those many items in
subnodes of `dir', but then comes the problem of keeping those entries up to
date when updating manuals.  So unless there's a way to "rebuild `dir' from
scratch" in a completely automatic way (which AFAIK, there is not right
now), it would be much better to not include copies of all those entries but
instead to just add some pointers to big menus in the manuals themselves.
Such pointers could point either to the manual's toplevel menu or to
some index.

> Such a Functions node will get very big (there are 6200 entries in my
> /usr/share/man/man3) but I don't see another answer.

Note that there is no copying invloved with `man' (unless you build the
whatis database), so nothing to keep consistent, whereas in your case you'd
have to make sure the Functions node doesn't hold stale data.

> We would have to change the Texinfo language and the install-info
> program to allow for installing entries in such a subnode of dir.
> @dircategory/@direntry do not suffice.

My suggestion doesn't require any such thing: just add to the `dir' node
(or somesuch) the list of (index or toplevel) subnodes to look up by
default and you're done.


        Stefan

Re: Documentation for "Clone Buffers" (corrected version)

[Kim F. Storm]

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

> >     info to include libc's index by default, you can just say `info strcpy'
> > Although automatically looking in libc's index would probably work for
> > 90% of cases in practice, it does not solve the general problem.
> 
> Without reading the user's mind, there's no way to handle `info strcpy'
> 100%, and neither does `man' handle it 100% (for the same reason).  So what
> you're saying here is not a criticism, unless you mean some specific
> problem, but I can't read your mind either.

Sorry I haven't followed this thread closely, so this may already 
have been said...

I agree that it's difficult to make the right choice in general, but
if I'm currently in a c-mode buffer in emacs, and I do (the equivalent
of) "info strcpy", it's pretty clear from the context what I mean...

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Documentation for "Clone Buffers" (corrected version)

[Stefan Monnier]

> I agree that it's difficult to make the right choice in general, but
> if I'm currently in a c-mode buffer in emacs, and I do (the equivalent
> of) "info strcpy", it's pretty clear from the context what I mean...

This is called info-lookup and it already works.
We're talking about the command-line `info' utility.
It should really be taken off the Emacs list.


        Stefan

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: 22 Mar 2004 21:26:43 -0500
> 
> This is called info-lookup and it already works.

A data structure similar to that used by info-lookup can be easily
added to the stand-alone reader, but I was under the impression that
this discussion tries to find a way of generating or updating its
equivalent at install-info time.  info-lookup leaves that to the
end user (given the low frequency of Emacs releases).

Also, info-lookup doesn't help when someone wants to see the
equivalent of "info --usage make" and its ilk, it only knows about
symbols in certain programming languages/packages.

> We're talking about the command-line `info' utility.
> It should really be taken off the Emacs list.

It is relevant to Emacs if we want to improve what info-lookup does.

But I agree that it's more Texinfo-oriented than Emacs-oriented.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: 19 Mar 2004 12:31:07 -0500
> 
> But using the index, you'd just say `info libc strcpy'.

For that example, sure.  But what about false hits in the concept
index?  Do we really want them to pop up?

> And if you tell info to include libc's index by default, you can
> just say `info strcpy'

Are we going to single-case the libc manual?  If not, what do we do
with "info sit-for" or "info point"?

> My model here is `man' where `man FOO' tries to guess in which section the
> thing is placed and `man FOO BAR' looks for BAR in section FOO.

Well, Info manuals are simply not organized like that, so the `man'
model might not be applicable as easily as we'd like.

Btw, I feel quite frustrated sometimes when "man printf" shows me the
man page of printf(1).  I think that's about the worst guess as one
can get.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    BTW, why does `info FOO BAR' only look for BAR in the menu of FOO instead
    of (or additionally to) looking for it in the Index?

Probably because nobody thought of this feature before.  Thanks for
the suggestion.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> Date: Thu, 18 Mar 2004 13:37:30 -0500
> From: karl@freefriends.org (Karl Berry)
> 
> The underlying issue, to my knowledge, is that for info to be as
> convenient as man, it needs to have dir entries for every command, every
> function, etc.

Why cannot they say

    	   info libc FUNCTION
?

Re: Documentation for "Clone Buffers" (corrected version)

[Karl Berry]

    Why cannot they say
               info libc FUNCTION

1) then users have to know what manual to look in.
2) in practice, manuals don't contain every function in their top-level
   menu, to my knowledge.

However, having a 1700-element entry in the top level of libc does sound
better to me than having a 1700-element dir listing, in terms of the
choices available now.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> Date: Fri, 19 Mar 2004 10:15:44 -0500
> From: karl@freefriends.org (Karl Berry)
> 
>     Why cannot they say
>                info libc FUNCTION
> 
> 1) then users have to know what manual to look in.

Doesn't sound a big problem to me: someone who looks for a library
function can manage to remember that they come from libc.

> 2) in practice, manuals don't contain every function in their top-level
>    menu, to my knowledge.

They usually do so in the Detailed Menu.  If not, they should.

In any case, if we want Info to look up arguments in the indices,
naming a particular manual in whose indices to look makes this job
practical, while looking in _all_ manuals is not, IMHO.

Re: Documentation for "Clone Buffers" (corrected version)

[Karl Berry]

    Doesn't sound a big problem to me: someone who looks for a library
    function can manage to remember that they come from libc.

Not all library functions are in libc.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> Date: Sat, 20 Mar 2004 09:15:23 -0500
> From: karl@freefriends.org (Karl Berry)
> 
>     Doesn't sound a big problem to me: someone who looks for a library
>     function can manage to remember that they come from libc.
> 
> Not all library functions are in libc.

If you refer to additional libraries, I think a programmer has a good
knowledge in what library each function lives.  After all, it's the
same programmer who needs to add a -lFOO switch to the link command
line.

Re: Documentation for "Clone Buffers" (corrected version)

[Miles Bader]

On Sat, Mar 20, 2004 at 05:15:47PM +0200, Eli Zaretskii wrote:
> > Not all library functions are in libc.
> 
> If you refer to additional libraries, I think a programmer has a good
> knowledge in what library each function lives.  After all, it's the
> same programmer who needs to add a -lFOO switch to the link command
> line.

I think you would be surprised... :-)

Another problem is that the name of the manual is often not the name of the
library.

Consider a toolkit that come with 34 different libraries (which normally you
just always link against); it's fairly likely that it comes with just one
info manual covering everything.  This is probably good: the programmer is
more likely to think of the function as being in `that toolkit', than he is
to quickly remember which library it's in (though he can probably figure it
out).

Anyway, the point is that the mapping is often fuzzy, and the man command
arguably is doing the right thing by just ignoring the whole issue -- library
functions usually try to be fairly unique anyway, so why not take advantage
of that and reduce the burden on the programmer when looking up
documentation?

[A similar issue occurs with command packages -- should the user have to
remember that the foo command is in the net-utils or the shell-utils
package?  No, but it's annoying to have the info index filled up with
command names too.]

-Miles
-- 
Somebody has to do something, and it's just incredibly pathetic that it
has to be us.  -- Jerry Garcia

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> Date: Sat, 20 Mar 2004 14:27:09 -0500
> From: Miles Bader <miles@gnu.org>
> 
> Consider a toolkit that come with 34 different libraries (which normally you
> just always link against); it's fairly likely that it comes with just one
> info manual covering everything.  This is probably good: the programmer is
> more likely to think of the function as being in `that toolkit', than he is
> to quickly remember which library it's in (though he can probably figure it
> out).

In that case, "info toolkit FOO" would do the job, and is the right
command for the case when all those libraries are described in a
single manual.

> Anyway, the point is that the mapping is often fuzzy

Are you saying that it's easier to remember the mapping of man
sections?

> why not take advantage of that and reduce the burden on the
> programmer when looking up documentation?

The question is, how to do that without imposing too heavy penalties
on all parties involved (i.e. the end user in terms of run-time
performance, the Texinfo maintainers, and manual authors).

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    > Anyway, the point is that the mapping is often fuzzy

    Are you saying that it's easier to remember the mapping of man
    sections?

That question is not relevant.  Why justify one flaw because
man has some other flaw?

Man sections are an example to learn from, not a model to follow.

I think that the suggestion I made in a recent batch is better than
the man sections, because it eliminates the artificial distinction
between sections 2 and 3.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 22 Mar 2004 00:25:41 -0500
> 
> Man sections are an example to learn from, not a model to follow.

Some people in this thread were saying that it _was_ a model (or at
least an improvement over the current Info system), so I was unsure
whether you thought that as well.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    If you refer to additional libraries, I think a programmer has a good
    knowledge in what library each function lives.  After all, it's the
    same programmer who needs to add a -lFOO switch to the link command
    line.

Not necessarily.  Maybe she didn't write the code.  Maybe she is looking
for the docs for a function because she doesn't know what it does.

If she has to specify the library name to find the function,
she might as well just browse and find that library's manual.
She can do that now.  The point is that this isn't convenient.

The goal of this discussion is to design a more convenient
alternative.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sun, 21 Mar 2004 00:00:31 -0500
> 
>     If you refer to additional libraries, I think a programmer has a good
>     knowledge in what library each function lives.  After all, it's the
>     same programmer who needs to add a -lFOO switch to the link command
>     line.
> 
> Not necessarily.  Maybe she didn't write the code.  Maybe she is looking
> for the docs for a function because she doesn't know what it does.

The same could happen with man pages, and yet several people in this
thread seem to say that man pages should serve as a model for the new
features we are discussing.

> If she has to specify the library name to find the function,
> she might as well just browse and find that library's manual.

Browsing a manual requires to know Info commands, while getting to
the required section directly does not.  So "info libc strcpy" is
more convenient than "info" followed by the commands to descend from
DIR to the libc manual, from there to the Index node, and finally
looking for strcpy.

Compare that with man pages: one could always start with the Intro
page, then follow the references from there.  However, getting to the
right page directly is more convenient.  (In the Info case, browsing
is more complicated because Info manuals have multi-level structure
while man pages have only 2 levels.)

> The goal of this discussion is to design a more convenient
> alternative.

In my experience, many Info users are unaware of Info features that
make their lives significantly easier.  How many users know about the
"--usage" or "--apropos" options?  I'm quite sure that something like
"info libc strcpy" is something many users don't know about.

So to have a fruitful discussion, I think we need to consider
available features, before we decide on the possible improvements.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    The underlying issue, to my knowledge, is that for info to be as
    convenient as man, it needs to have dir entries for every command, every
    function, etc.

I think the command names should be entries in an index, rather than
entries in the info directory.

      It's obviously not useful for the user to have to browse
    through a dir node with 1700 entries from glibc.

I'm not sure what you mean here.  Are you envisioning the idea that
the libc manual could create an entry in the info dir for each library
function?  I see no reason to put them in the info directory; it's
better to put them in an index, which is where they are already.

However I am puzzled that you go on to speak of this as if it were
already fact:

      On the other hand, I
    can't exactly call it a "bug" in the glibc manual, it's trying to do the
    only thing available.

What exactly are you saying is not a bug?  What do you mean by "the
only thing available"?  What is that thing?  Available for what?

    The only long-term solution I've been able to think of is to allow
    subnodes of (dir) and have the info readers look through the subnodes
    when asked for a given top-level name -- but not load or display the
    info in all the subnodes when showing the dir node itself.

I think we need commands that find specific index nodes and look up
names in them.  There would be one for commands, one for library
functions, and so on.  This is the same idea as the structure of
sections of the unix manual, but we need not name them by numbers.

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sat, 20 Mar 2004 13:01:26 -0500
> 
>       It's obviously not useful for the user to have to browse
>     through a dir node with 1700 entries from glibc.
> 
> I'm not sure what you mean here.  Are you envisioning the idea that
> the libc manual could create an entry in the info dir for each library
> function?  I see no reason to put them in the info directory

AFAIU, the glibc manual did just that.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    > I'm not sure what you mean here.  Are you envisioning the idea that
    > the libc manual could create an entry in the info dir for each library
    > function?  I see no reason to put them in the info directory

    AFAIU, the glibc manual did just that.

It does not look that way to me.  Could someone show me a portion of
the text which does this, and tell me the filename and node name?

Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 22 Mar 2004 00:25:28 -0500
> 
>     > I'm not sure what you mean here.  Are you envisioning the idea that
>     > the libc manual could create an entry in the info dir for each library
>     > function?  I see no reason to put them in the info directory
> 
>     AFAIU, the glibc manual did just that.
> 
> It does not look that way to me.  Could someone show me a portion of
> the text which does this, and tell me the filename and node name?

I think you don't see this because your glibc version is not recent
enough.  On a Debian GNU/Linux box that identifies itself as

  Linux pot.isti.cnr.it 2.4.24 #1 Mon Jan 26 15:20:26 CET 2004 i686 GNU/Linux

I found a glibc manual whose preamble says

  This is Edition 0.10, last updated 2001-07-06, of `The GNU C Library
  Reference Manual', for Version 2.3.x of the GNU C Library.

That manual comes with a file `libc-dir-add.info.gz' which contains an
INFO-DIR-ENTRY which looks like below, and it is copied into the DIR
file.  Maybe it's a Debian thing, not something that comes with a
glibc distribution, I don't know (didn't have time to fetch a tarball
and look there).

    INFO-DIR-SECTION GNU C library functions
    START-INFO-DIR-ENTRY
    * ALTWERASE: (libc)Local Modes.
    * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
    * ARG_MAX: (libc)General Limits.
    * BC_BASE_MAX: (libc)Utility Limits.
    * BC_DIM_MAX: (libc)Utility Limits.
    * BC_SCALE_MAX: (libc)Utility Limits.
    * BC_STRING_MAX: (libc)Utility Limits.
    * BRKINT: (libc)Input Modes.
    * BUFSIZ: (libc)Controlling Buffering.
    * CCTS_OFLOW: (libc)Control Modes.
    * CHILD_MAX: (libc)General Limits.
    * CIGNORE: (libc)Control Modes.
    * CLK_TCK: (libc)CPU Time.

    [... lots of entries deleted for brevity ...]

    * wscanf: (libc)Formatted Input Functions.
    * y0: (libc)Special Functions.
    * y0f: (libc)Special Functions.
    * y0l: (libc)Special Functions.
    * y1: (libc)Special Functions.
    * y1f: (libc)Special Functions.
    * y1l: (libc)Special Functions.
    * yn: (libc)Special Functions.
    * ynf: (libc)Special Functions.
    * ynl: (libc)Special Functions.
    * {(*__gconv_end_fct)}: (libc)glibc iconv Implementation.
    * {(*__gconv_fct)}: (libc)glibc iconv Implementation.
    * {(*__gconv_init_fct)}: (libc)glibc iconv Implementation.
    END-INFO-DIR-ENTRY

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

Another reason why some features are not in the Emacs manual is that
adding them would be a lot of work, and it isn't worth doing just for
the sake of completeness.

Re: Documentation for "Clone Buffers" (corrected version)

[Richard Stallman]

    Incidentally, there isn't an entry in the Emacs manual's command index
    for `rename-uniquely'.  Is this deliberate or is it a bug?

It was a bug.

Documentation for "Clone Buffers" (corrected version)

[Alan Mackenzie]

Hi, guys!

[Sorry, forgot to include the patch to emacs.texi.  It's here now.
Please ignore my previous post.]

Currently, `clone-buffer' is not documented in the Emacs manual.  The
following patch fixes this.

I've also tidied up and corrected the "Indirect Buffers" section a bit.
In particular, creating an indirect buffer is _not_ a suitable way to get
two indpendent *info* or *help* buffers.  (At least, it isn't for me on
Emacs 21.3.)

Also "cloned buffer" is a most unfortunate term.  It could refer to the
buffer to which the process of cloning has just been applied (i.e. the
original).  It could equally well refer to the buffer just created by the
process of cloning (i.e. the copy).  I've purged it from buffers.texi.

As a matter of interest, is there any reason why `clone-buffer' has no
binding in the pertinent help keymaps (e.g. the one you get with C-h f
<foo>)?  It seems a bit inconsistent that you can use M-n on an info
page, but not a help text.


2004-02-25  Alan Mackenzie  <acm@muc.de>

	* buffers.texi.  New section "Cloning Buffers".  Tidied up
	section "Indirect Buffers"
	* emacs.texi.  Insert menu entry.


*** buffers-1.26.texi	Tue Feb 24 19:34:49 2004
--- buffers-1.26.acm.texi	Wed Feb 25 09:50:41 2004
***************
*** 55,60 ****
--- 55,61 ----
  * Several Buffers::     How to go through the list of all buffers
  			  and operate variously on several of them.
  * Indirect Buffers::    An indirect buffer shares the text of another buffer.
+ * Cloning Buffers::     Cloning a buffer makes a copy of its text.
  * Buffer Convenience::  Convenience and customization features for
                            buffer handling.
  @end menu
***************
*** 438,445 ****
  @cindex base buffer
  
    An @dfn{indirect buffer} shares the text of some other buffer, which
! is called the @dfn{base buffer} of the indirect buffer.  In some ways it
! is the analogue, for buffers, of a symbolic link between files.
  
  @table @kbd
  @findex make-indirect-buffer
--- 439,448 ----
  @cindex base buffer
  
    An @dfn{indirect buffer} shares the text of some other buffer, which
! is called the @dfn{base buffer} of the indirect buffer.  In some ways
! it is the analogue, for buffers, of a symbolic link between files.  (A
! clone buffer, by contrast, is a @emph{copy} of its original.
! @xref{Cloning Buffers}.)
  
  @table @kbd
  @findex make-indirect-buffer
***************
*** 456,462 ****
  select it in another window (@code{clone-indirect-buffer-other-window}).
  @end table
  
!   The text of the indirect buffer is always identical to the text of its
  base buffer; changes made by editing either one are visible immediately
  in the other.  But in all other respects, the indirect buffer and its
  base buffer are completely separate.  They have different names,
--- 459,465 ----
  select it in another window (@code{clone-indirect-buffer-other-window}).
  @end table
  
!   The text of an indirect buffer is always identical to the text of its
  base buffer; changes made by editing either one are visible immediately
  in the other.  But in all other respects, the indirect buffer and its
  base buffer are completely separate.  They have different names,
***************
*** 471,492 ****
    One way to use indirect buffers is to display multiple views of an
  outline.  @xref{Outline Views}.
  
- @cindex multiple @samp{*info*} and @samp{*Help*} buffers
    A quick and handy way to make an indirect buffer is with the command
  @kbd{M-x clone-indirect-buffer}.  It creates and selects an indirect
  buffer whose base buffer is the current buffer.  With a numeric
  argument, it prompts for the name of the indirect buffer; otherwise it
  defaults to the name of the current buffer, modifying it by adding a
! @samp{<@var{n}>} prefix if required.  @kbd{C-x 4 c}
  (@code{clone-indirect-buffer-other-window}) works like @kbd{M-x
! clone-indirect-buffer}, but it selects the cloned buffer in another
! window.  These commands come in handy if you want to create new
! @samp{*info*} or @samp{*Help*} buffers, for example.
! 
!   The more general way is with the command @kbd{M-x
! make-indirect-buffer}.  It creates an indirect buffer from buffer
! @var{base-buffer}, under the name @var{indirect-name}.  It prompts for
! both @var{base-buffer} and @var{indirect-name} using the minibuffer.
  
  @node Buffer Convenience
  @section Convenience Features and Customization of Buffer Handling
--- 474,527 ----
    One way to use indirect buffers is to display multiple views of an
  outline.  @xref{Outline Views}.
  
    A quick and handy way to make an indirect buffer is with the command
  @kbd{M-x clone-indirect-buffer}.  It creates and selects an indirect
  buffer whose base buffer is the current buffer.  With a numeric
  argument, it prompts for the name of the indirect buffer; otherwise it
  defaults to the name of the current buffer, modifying it by adding a
! @samp{<@var{n}>} suffix if required.  @kbd{C-x 4 c}
  (@code{clone-indirect-buffer-other-window}) works like @kbd{M-x
! clone-indirect-buffer}, but it selects the new buffer in another
! window.  These commands are unsuitable for creating new @samp{*info*}
! or @samp{*Help*} buffers; instead, use @code{clone-buffer} to do this.
! @xref{Cloning Buffers}.
! 
!   The most general way to get an indirect buffer is with the command
! @kbd{M-x make-indirect-buffer}.  It creates an indirect buffer from
! buffer @var{base-buffer}, under the name @var{indirect-name}.  It
! prompts for both @var{base-buffer} and @var{indirect-name} using the
! minibuffer.
! 
! @node Cloning Buffers
! @section Cloning Buffers
! @cindex clone buffer
! 
!   A @dfn{clone buffer} is one whose text is a copy of some other
! buffer's text.  Buffers which are visiting files can't be cloned.
! 
! @table @asis
! @item @kbd{M-n} (Info mode) or M-x clone-buffer @key{RET}
! @kindex M-n (Info mode)
! @findex clone-buffer
! Create a new buffer which is a clone of the current buffer, and select
! it in another window.
! @end table
! 
! @cindex multiple @samp{*info*} and @samp{*Help*} buffers
!   @code{clone-buffer} (@kbd{M-n} in Info Mode) creates a clone buffer,
! a distinct copy of the current buffer, and selects it in another
! window.  If given a numeric argument, it prompts for the name of the
! new buffer.  Otherwise, its name is formed by appending @samp{<1>} to
! the original buffer's name (or incrementing @var{n} if it already ends
! in @samp{<@var{n}>}).
! 
!   This command is the way to create a new @samp{*info*} or
! @samp{*Help*} buffer, so that you can look at two (or more) info pages
! or help texts at once.
! 
!   You cannot clone a buffer which is visiting a file, though you can
! create an indirect buffer which is a copy of it.  @xref{Indirect
! Buffers}.
  
  @node Buffer Convenience
  @section Convenience Features and Customization of Buffer Handling


*** emacs-1.77.texi	Wed Feb 25 09:20:38 2004
--- emacs-1.77.acm.texi	Wed Feb 25 09:23:37 2004
***************
*** 389,394 ****
--- 389,395 ----
  * Several Buffers::     How to go through the list of all buffers
  			  and operate variously on several of them.
  * Indirect Buffers::    An indirect buffer shares the text of another buffer.
+ * Cloning Buffers::     Cloning a buffer makes a copy of its text.
  
  Multiple Windows
  

-- 
Alan Mackenzie (Munich, Germany)