Re: My emacs was upgraded and I am a novice again

[Tim X]

"Dave Pawson" <dave.pawson@gmail.com> writes:

> On 22/09/2007, Eli Zaretskii <eliz@gnu.org> wrote:
>> > Date: Sat, 22 Sep 2007 09:56:06 +0100
>> > From: "Dave Pawson" <dave.pawson@gmail.com>
>> > Cc: help-gnu-emacs@gnu.org
>> >
>> > > Instead of inventing new machinery, how about enhancing the existing
>> > > one?  "C-h P" is supposed to use the index you seem to think about.
>> >
>> > Good example, both counts.
>> > No sign of revert (even if I understood it to mean reload).
>>
>> Sorry, I don't understand what you are talking about: what revert?
>
> The minor mode that resolved the issue at the top of this thread, for Steve?
> auto-revert-mode
>
>>
>> If you are looking for the place to learn Emacs parlance, there's the
>> "Glossary" node in the manual (which does explain "revert").
>>
>> If you are looking for a way to find the command revert-buffer using
>> keywords or phrases pertinent to what it should do, then
>> "apropos-documentation" is your man, and "Info-index" in Info is your
>> friend.  (I'm not saying that these two will necessarily find what you
>> are looking for, but if you name here the words or phrases that you
>> use or would think to use for what revert-buffer does, I can try to
>> make sure that those words/phrases will find the relevant commands in
>> the future releases of Emacs.)
>
> This was a case where two of wanted a feature (that was present in emacs)
> that we failed to find.
>
> Thanks for the pointers to other sources.
>
>
Dave, I think you may have missed what Eli was saying. Essentially, the
index you want already exists. Eli acknowledges that maybe the indexing and
word association isn't good enough and if you provide an example of the
terms that you used to search for the feature, but didn't get anything, he
can have it added so that anyone in the future who has the same problem is
likely to get the right result without also having to know about any index
you may have on a website somewhere. For example, later in this post, you
refer to a mapping from re-load to revert. Searching for re-load reveals
nothing. However, searching through the glossary for reread (which is what
I would search for rather than reload) you get 

* reread a file:                         Reverting.           (line   6)

An entry could be added thus

* re-load a file                         Reverting.

What I believe Eli is trying to get across (apologies Eli if I've got it
wrong) is that it is better to find a solution that fits in with the
existing framework and distributed docs than create yet another chunk of
information which new users will need to find out about and which is likely
not to be maintained as well as the official distro.
>>
>> In short, please spell out what are the use cases you are thinking
>> about, because it looks like we are talking about several different
>> ones here, with possibly different solutions to each one of them.
>
> Quite possibly.
>
> The bottom line is that emacs has features that a large part of the user base
> appears to be unaware of. I'm thinking it may be possible to generate some
> form of documentation that might just put multiple pointers to a mode,
> a variable
> or some part of emacs that provides the feature that we only have an idea of
> in our head. 

I'm afraid I'd have to dispute your basic premise there. I don't believe
its a large part of the user base at all. I also think that many of the
posts asking for pointers on this group are from people who just haven't
read the documentation or tried to find the answer themselves. An
additional index is not going to change this behavior. I do think extending
the current index and glossory would be useful and make things even
better. I'm just not convinced the problem is as bad or widespread as you
indicate. 



My term for this would would most likely be 'auto-reload' or some
> such, i.e. when the file changes on disk, reload it.
> For this instance the mapping is from 'reload' through to revert or
> auto-revert-mode.
>

As mentioned above, we could add a reload -> revert entry to the
glossary. However, would doing that actually have worked in your case? I
mean, if such an entry was in the glossory, would you have used/found it?
(Sorry if it sounds like I'm doubting things too much, I just find that
since even a search for 'file' in the glossory, while returning a lot of
results, would still have pointed you to revert because as soon as you wold
have seen the reread file entry, you would have known).

>>
>> > And I'd never heard of C-h P. As I said, I'd need to know the magic
>> > word 'revert' to find revert. That's the index I think is missing.
>>

Again, this is clearly laid out in the manual under the help section. More
and more, the problem here appears to be a failure to actually RTFM. Now,
some people just don't read manuals and thats fine. My issue is that if
they don't read manuals, why would they read a web/wiki page either? More
documentation doesn't help with this and can possibly make it worse because
it isn't maintained.

Take for example the revert stuff. I can understand that people would not
have thought of that term. However, I wold have expected they would have
looked under the "File Handling" section on the first page of the manual,
where they woul dhave seen, straight after the entry on saving, one for
reverting. Even if you didn't know what that meant, I would have thought
curiosity would have been enough.

>> I thought you were asking for finding packages by keywords
>
>
> I was, you've pointed out 3 or 4 other places to look.
> The main point is that your keywords and mine/Steves or any other uses 
> keywords
> are going to vary depending on background?
>

Which is why I'm skeptical concerning how effective yet another index would
be. Far better to improve the existing one.
>
>> That is why I pointed out that an index of Emacs packages already
>> exists, and it is what "C-h P" consults to do its job.
>>
>> Now I see that I need to add several more indices to the list:
>>
>>  . The index in the Info manual (search it by the `i' command)
>>
>>  . The virtual index produced by "apropos" and "apropos-documentation"
>>
>>  . The "Glossary" node in the Emacs manual
>
>
> If thats believed to be the most appropriate place then fine.
> I'd find it hard to see how you'll collect other peoples understanding of
> the keywords. That's why I suggested a wiki approach or webpage.
>

and that is the one benefit it could possibly have. However, it needs to be
fed back into the main documentation. 


> I find the emacs info pages a pain to navigate compared to searchable,
> indexable html pages derived from indexed xml. That's my bias I guess.
>

I think this might actually be the key here. The problem may be that it
isn't a lack of information available, but rather a dislike/resistance to
using what is available because of its format. 

Maybe you might get better results if you use texi2html and generate html
versions of the manual? However, I would strongly suggest you try to
overcome your bias and actually read the section on info and its
commands. The info system is pretty darn good once you get use to
it. Personally, I find it far easier to navigate than any HTML files I've
ever seen, plus it has excellent integration with emacs which allows you to
search it in numerous ways and with only a couple of keystrokes. 

regards,

Tim


-- 
tcross (at) rapttech dot com dot au