unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Divergence in menu appearance between Emacs Info and standalone Info
@ 2003-06-04  8:54 Richard Stallman
  2003-06-04  9:06 ` Miles Bader
  0 siblings, 1 reply; 82+ messages in thread
From: Richard Stallman @ 2003-06-04  8:54 UTC (permalink / raw)
  Cc: emacs-devel

Emacs Info has a feature that hides some of the text in a menu.  As a
result, the explanation of menus in info.texi is not really accurate
for Emacs any more.  The message below explains the details.  The
question is what to do about this.

One idea is to take out the Emacs feature that hides this text, so the
text becomes visible again.  Another idea is to change the stand-alone
Info to hide this text too, and then change info.texi accordingly.

A third option is to put conditionals into info.texi and have
two versions of it, one for Emacs and one for standalone info.
But I think that divergence is probably a bad idea.

What do you think?

Meanwhile, Emacs already modifies the Info buffer for display, so
instead of making that text invisible, perhaps it should delete the
text and put the information from it into text properties of the menu
item names.


Date: Mon, 2 Jun 2003 23:45:56 -0500 (CDT)
X-Authentication-Warning: eel.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f
From: Luc Teirlinck <teirllm@dms.auburn.edu>
To: rms@gnu.org
CC: emacs-devel@gnu.org
In-reply-to: <E19N34O-0006SH-2L@fencepost.gnu.org> (message from Richard
	Stallman on Tue, 03 Jun 2003 00:06:44 -0400)
Subject: Re: Problems with info (emacs version)
X-Spam-Status: No, hits=-7.1 required=5.0
	tests=EMAIL_ATTRIBUTION,IN_REP_TO,REFERENCES,SPAM_PHRASE_01_02,
	      X_AUTH_WARNING
	version=2.41
X-Spam-Level: 

Richard Stallman wrote:

       1.  Easiest one to fix:

	   (info)Help-M

	   which is used in the tutorial, *only* describes menus as they
	   appear in the standalone info, not as they appear in the emacs
	   version and the two are very different.

   Would you please tell me the specific differences?  I scanned through
   that none and did not notice anything incorrect.

Yes. From (info)Help-M:

       * Foo:  Node about FOO.      This tells about FOO.

     The subtopic name is Foo, and the node describing it is `Node about
  FOO'.  The rest of the line is just for the reader's Information.  [[
  But this line is not a real menu item, simply because there is no line
  above it which starts with `* Menu:'.]]

     When you use a menu to go to another node (in a way that will be
  described soon), what you specify is the subtopic name, the first
  thing
  in the menu line.  Info uses it to find the menu line, extracts the
  node name from it, and goes to that node.  The reason that there is
  both a subtopic name and a node name is that the node name must be
  meaningful to the computer and may therefore have to be ugly looking.
  The subtopic name can be chosen just to be convenient for the user to
  specify.  Often the node name is convenient for the user to specify
  and
  so both it and the subtopic name are the same.  There is an
  abbreviation for this:

       * Foo::   This tells about FOO.

  This means that the subtopic name and node name are the same; they are
  both `Foo'.

My own remarks:

Note that this goes into quite some length explaining why the user
sees both a 

"*Foo:" and a "Node about Foo" and what the difference is,

but the user using Emacs, sees only:

"*Foo".  Nowhere is it told that ":   Node about FOO" is normally
invisible in Emacs.  The user looks for it, can not find it and does
not know what is going on.

       * Foo::   This tells about FOO.

  This means that the subtopic name and node name are the same; they
  are
  both `Foo'.

Again, only:

* Foo is visible in Emacs, not the "::" The Emacs info user has no
  idea what all of this stuff about special meaning of "::" is about.

Of course, the entire discussion *is* correct if you know about the
invisible text.  One would not have to make a lot of changes in the
documentation if one would provide the user with convenient commands
in Info to toggle invisibility, say `v'. All one would have to do
would be to tell the user that in Emacs you first have to type `v' to
see the text being talked about.  I could easily implement such a
visibility toggling feature myself, if you would agree with it.

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 82+ messages in thread
* Re: Divergence in menu appearance between Emacs Info and standalone Info
@ 2003-06-04 14:04 Karl Berry
  2003-06-04 14:26 ` Miles Bader
                   ` (6 more replies)
  0 siblings, 7 replies; 82+ messages in thread
From: Karl Berry @ 2003-06-04 14:04 UTC (permalink / raw)
  Cc: emacs-devel

    One idea is to take out the Emacs feature that hides this text, so the
    text becomes visible again.  

I'm afraid that I have some sympathy for this approach, despite the work
that's gone into it.  I recognize that the node names are, in some
sense, `extra' information and removing them makes for fewer things for
the reader to see.  That much is good.  But the downside is that Texinfo
is completely based on node names, and hiding them seems to me like it
could easily cause more confusion than it solves.

In the example at hand,
* Foo: A Node about Foo: ...
the user will select `Foo', but then end up at `A Node about Foo', with
no real way of making the connection between them.

    Another idea is to change the stand-alone
    Info to hide this text too, and then change info.texi accordingly.

I won't be able to do this myself any time soon.  However, I'll ask the
other Info programmer volunteers if they'd like to work on it.

    A third option is to put conditionals into info.texi and have
    two versions of it, one for Emacs and one for standalone info.
    But I think that divergence is probably a bad idea.

I don't like the divergent conditionals either.  However, I think it
would be ok to simply say in info.texi, `Emacs Info does it this way,
and standalone Info does it that way'.  I think that would be clear to
users of both programs.  Better than (effectively) having two different
manuals with the same name, anyway.

    What do you think?

I gather the default is to hide the node names.  Because of the problems
above, I suggest making the default to show them, i.e., the traditional
behavior.

Also, from previous mail, I think that node names can also now be hidden
in xrefs?  Anywhere else?  The Texinfo manual will also need to mention
this new feature, lest authors be confused when Emacs does not show them
what the manual says to expect.

Thanks,
karl

^ permalink raw reply	[flat|nested] 82+ messages in thread
* Re: Divergence in menu appearance between Emacs Info and standalone Info
@ 2003-06-04 23:12 Karl Berry
  2003-06-05  0:39 ` Luc Teirlinck
  0 siblings, 1 reply; 82+ messages in thread
From: Karl Berry @ 2003-06-04 23:12 UTC (permalink / raw)
  Cc: emacs-devel

    Presenting the user with two different manuals (regardless of how this
    would be implemented internally) would make this nearly impossible to

I agree wholeheartedly.  That's the only thing I feel really strongly
about, that we shouldn't have two manuals (especially not both named
info.texi!) for the two programs.

I believe many users use both standalone Info and Emacs info.el, and
those two interfaces are so very similar (by design, after all) it is
good to just describe the discrepancies where they exist, in a single
manual.  And we should work to minimize any such discrepancies.

By contrast, the other Info readers such as pinfo and tkinfo (besides
not being GNU software, as Eli says), have (I believe) quite different
interfaces.  So they need different manuals.

    "If you use standalone Info or use Emacs Info and set
    Info-hide-note-references to nil..."

There could/should also be a description of the Emacs Info behavior
with the node hiding.  Especially if it's the default.


As for whether the hiding is the default or not, that's your collective
decision.  rms asked my opinion, so I gave it, that's all :).

^ permalink raw reply	[flat|nested] 82+ messages in thread
* Re: Divergence in menu appearance between Emacs Info and standalone Info
@ 2003-06-05 12:59 Karl Berry
  2003-06-05 15:52 ` Luc Teirlinck
  2003-06-05 16:23 ` Luc Teirlinck
  0 siblings, 2 replies; 82+ messages in thread
From: Karl Berry @ 2003-06-05 12:59 UTC (permalink / raw)
  Cc: emacs-devel

    in this case the
    differences are in numerous places in the node.  It may look very ugly
    to describe both alternatives.  Could you try?

It would be better for someone who has actually used or programmed this
feature to write at least the first draft.  I don't know any of the details.

Luc, perhaps you make a first cut at changing info.texi, and then I'll
review it?

Thanks,
karl

^ permalink raw reply	[flat|nested] 82+ messages in thread
* Re: Divergence in menu appearance between Emacs Info and standalone Info
@ 2003-06-05 16:30 Karl Berry
  2003-06-05 16:44 ` Luc Teirlinck
  0 siblings, 1 reply; 82+ messages in thread
From: Karl Berry @ 2003-06-05 16:30 UTC (permalink / raw)
  Cc: emacs-devel

    1.  First decide how the Emacs version is going to look.

I had the impression that the decision had been made, namely to hide
those node names by default.  Are there other issues?

    2.  Decide how the standalone version is going to look.

In principle, I would like it to operate the same as Emacs, as much as
possible.  However, the other programmers haven't responded to my
request, so I don't know when this will happen.

I don't know when the next release of Emacs is likely to happen, but I
bet it will be (long) before any Texinfo release incorporating the
changes.

    3.  Implement 1 and 2.
    4.  Rewrite the documentation accordingly.

I think the documentation may need to be updated after 1 is done and
before 2, because whatever info.texi gets shipped with Emacs should
reflect what's in that Emacs, and yet also still be relevant to
standalone Info.

I wish I could say otherwise, that standalone Info will track Emacs
immediately and we could release at the same time, but I just don't have
the person-hours to make it happen ...

Thanks,
karl

^ permalink raw reply	[flat|nested] 82+ messages in thread
* Re: Divergence in menu appearance between Emacs Info and standalone Info
@ 2003-06-08 13:48 Karl Berry
  2003-06-08 16:02 ` Eli Zaretskii
  2003-06-09 23:00 ` Richard Stallman
  0 siblings, 2 replies; 82+ messages in thread
From: Karl Berry @ 2003-06-08 13:48 UTC (permalink / raw)
  Cc: emacs-devel

        I'd make a much more radical proposal: image support.

Yes, this was added to Texinfo (makeinfo, info.el) a little while ago,
implemented by janneke@gnu.org, and will be in the next release of
Texinfo and Emacs.  As for documentation, I wrote about it in
texinfo.txi.  It didn't seem like any documentation for info readers was
needed -- it just happens.

I guess I missed the context here.  What does this have to do with
hiding node names, anything?

^ permalink raw reply	[flat|nested] 82+ messages in thread
* Re: Divergence in menu appearance between Emacs Info and standalone Info
@ 2003-06-09 23:17 Karl Berry
  2003-06-11  0:24 ` Richard Stallman
  0 siblings, 1 reply; 82+ messages in thread
From: Karl Berry @ 2003-06-09 23:17 UTC (permalink / raw)


        karl>
        Yes, this was added to Texinfo (makeinfo, info.el) a little
        while ago, implemented by janneke@gnu.org, and will be in the
        next release of Texinfo and Emacs.  As for documentation, I
        wrote about it in texinfo.txi.  It didn't seem like any
        documentation for info readers was needed -- it just happens.

    rms>
    We need to document the format in info.texi.

I assume you mean the specific implementation in the .info files
(^H^[image src=...^H^]).  Ok, I can work on that, although in general
info.texi's description of Info format looks quite idiosyncratic to me,
being done in the context of writing an Info file by hand (which no one
does any more), and/or explaining certain Info user interface commands.

So, do you mind if I rewrite it so that there's a clear appendix simply
describing the file format?  If you don't want me to go that far, then I'll
just stick in the image information somewhere.

I see that the anchor implementation is not mentioned in info.texi
either.  I'll document that as well.  (I didn't think of it when I added
the feature since I never thought of info.texi as documenting the file
format before now, just the user interface.)

k

^ permalink raw reply	[flat|nested] 82+ messages in thread

end of thread, other threads:[~2003-06-16 18:45 UTC | newest]

Thread overview: 82+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2003-06-04  8:54 Divergence in menu appearance between Emacs Info and standalone Info Richard Stallman
2003-06-04  9:06 ` Miles Bader
2003-06-04 15:12   ` Andreas Schwab
2003-06-04 21:54     ` David Kastrup
2003-06-12  6:47       ` Karl Eichwalder
2003-06-12 22:13         ` Luc Teirlinck
2003-06-13  3:58           ` Karl Eichwalder
2003-06-13  5:00             ` Luc Teirlinck
2003-06-13  5:10               ` Luc Teirlinck
2003-06-13  6:16                 ` Stefan Monnier
2003-06-05  2:47     ` Kim F. Storm
2003-06-05 13:04       ` Andreas Schwab
2003-06-10  0:03         ` Kim F. Storm
  -- strict thread matches above, loose matches on Subject: below --
2003-06-04 14:04 Karl Berry
2003-06-04 14:26 ` Miles Bader
2003-06-04 15:01 ` Stefan Monnier
2003-06-04 15:24   ` Eli Zaretskii
2003-06-04 15:31     ` Stefan Monnier
2003-06-04 16:55       ` Luc Teirlinck
2003-06-04 17:14         ` Stefan Monnier
2003-06-05  2:38           ` Luc Teirlinck
2003-06-05  3:23             ` Miles Bader
2003-06-05  5:52           ` Eli Zaretskii
2003-06-05 13:35             ` Stefan Monnier
2003-06-06  9:46               ` Eli Zaretskii
2003-06-06 11:28                 ` Andreas Schwab
2003-06-06 15:38                 ` Stefan Monnier
2003-06-05  5:49       ` Eli Zaretskii
2003-06-05 10:58       ` Richard Stallman
2003-06-04 15:25 ` Eli Zaretskii
2003-06-04 15:47 ` Luc Teirlinck
2003-06-05 10:57 ` Richard Stallman
2003-06-05 12:27 ` Robert J. Chassell
2003-06-06  0:11   ` Kim F. Storm
2003-06-05 22:55     ` Miles Bader
2003-06-05 23:11     ` Robert J. Chassell
2003-06-05 23:23       ` Stefan Monnier
2003-06-05 23:56         ` Robert J. Chassell
2003-06-06  2:02           ` Miles Bader
2003-06-06 13:28             ` Robert J. Chassell
2003-06-06  9:50           ` Eli Zaretskii
2003-06-06 13:02             ` David Kastrup
2003-06-08  1:09               ` Richard Stallman
2003-06-08  1:20                 ` Stefan Monnier
2003-06-08  2:30                   ` David Kastrup
2003-06-09  8:53                   ` Richard Stallman
2003-06-06 14:00             ` Robert J. Chassell
2003-06-06 15:51               ` Eli Zaretskii
2003-06-06 16:54                 ` Robert J. Chassell
2003-06-06 17:25               ` Kevin Rodgers
2003-06-08  1:07               ` Richard Stallman
2003-06-15 15:47               ` Karl Eichwalder
2003-06-15 16:08                 ` Stefan Monnier
2003-06-15 22:27                   ` Miles Bader
2003-06-16 12:02                   ` Reiner Steib
2003-06-16 18:45                     ` Robert J. Chassell
2003-06-15 17:46                 ` Robert J. Chassell
2003-06-16  5:46                   ` Karl Eichwalder
2003-06-15 19:00                 ` Kai Großjohann
2003-06-06 17:24       ` Kevin Rodgers
2003-06-07 11:46         ` Kai Großjohann
2003-06-06 17:03   ` Richard Stallman
2003-06-05 16:50 ` Kai Großjohann
2003-06-05 20:50   ` Luc Teirlinck
2003-06-06 16:05     ` Luc Teirlinck
2003-06-06 16:29       ` Luc Teirlinck
2003-06-04 23:12 Karl Berry
2003-06-05  0:39 ` Luc Teirlinck
2003-06-05 12:59 Karl Berry
2003-06-05 15:52 ` Luc Teirlinck
2003-06-05 16:23 ` Luc Teirlinck
2003-06-05 18:19   ` Luc Teirlinck
2003-06-06 17:02   ` Richard Stallman
2003-06-05 16:30 Karl Berry
2003-06-05 16:44 ` Luc Teirlinck
2003-06-05 23:39   ` Kim F. Storm
2003-06-06 17:03     ` Richard Stallman
2003-06-08 13:48 Karl Berry
2003-06-08 16:02 ` Eli Zaretskii
2003-06-09 23:00 ` Richard Stallman
2003-06-09 23:17 Karl Berry
2003-06-11  0:24 ` Richard Stallman

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).