My emacs was upgraded and I am a novice again

My emacs was upgraded and I am a novice again

[Bruce Korb]

The main novice problem is that I cannot get out of novice mode.
It does not seem to matter that I've been using emacs for 20 years.
``appropos novice'' yields nothing.  I suppose I could go hunting
around the file system to find where "novice.el" is hidden, but
I really don't want to do that.  I just want all these nonsense
"novice" confirmation junk turned off and I want it easy to find.
Why is that too much to ask?  :(

OK.  I've vented now.  Would someone please be kind enough to
tell me how to shut down the novice stuff completely?  Thank you.

P.S. This appears to not be everything anymore:


(put 'narrow-to-region 'disabled nil)
(put 'upcase-region 'disabled nil)
(put 'downcase-region 'disabled nil)
(put 'set-goal-column 'disabled nil)
(setq inhibit-startup-message t)
(setq next-line-add-newlines nil)
(setq default-major-mode 'indented-text-mode)
(setq split-window-keep-point nil)
(setq minibuffer-max-depth nil)
(setq vc-mistrust-permissions nil)
(setq line-number-mode 't)
(setq backup-by-copying-when-linked 't)
(setq default-tab-width 8)
(setq hack-local-variables 't)
(setq indent-tabs-mode nil)
(setq-default indent-tabs-mode nil)
(setq line-number-mode 't)
(setq column-number-mode 't)
(setq c-recognize-knr-p nil)
(setq enable-local-variables 't)
(setq vc-cvs-stay-local nil)

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

[David Hansen]

On Thu, 20 Sep 2007 11:22:15 -0700 Bruce Korb wrote:

> OK.  I've vented now.  Would someone please be kind enough to
> tell me how to shut down the novice stuff completely?  Thank you.

Mind to tell us what you mean with "novice stuff"?

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

[Glenn Morris]

Bruce Korb wrote:

> OK.  I've vented now.  Would someone please be kind enough to
> tell me how to shut down the novice stuff completely?  Thank you.

(setq disabled-command-function nil)

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

[Eli Zaretskii]

> Date: Thu, 20 Sep 2007 11:22:15 -0700
> From: Bruce Korb <Bruce.Korb@gmail.com>
> 
> The main novice problem is that I cannot get out of novice mode.
> It does not seem to matter that I've been using emacs for 20 years.
> ``appropos novice'' yields nothing.

How did you come up with the string "novice" as something to look for?
The Emacs manual describes this feature as "disabled command", and
both "M-x apropos disabled" and "i disabled" in the manual find quite
a few hits.

> I just want all these nonsense "novice" confirmation junk turned off
> and I want it easy to find.  Why is that too much to ask?  :(

There was never such a user setting in Emacs.  You always had to
enable each command individually (unless you are an advanced user and
know how to set a function to nil without causing damage).

I can understand why adding such a feature would be a good idea,
though (although I personally never had a need for it in the 20 years
I use Emacs).  Feel free to suggest adding such a feature one the
development list.

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

[Dave Pawson]

On 21/09/2007, Eli Zaretskii <eliz@gnu.org> wrote:

> How did you come up with the string "novice" as something to look for?
> The Emacs manual describes this feature as "disabled command", and
> both "M-x apropos disabled" and "i disabled" in the manual find quite
> a few hits.

For me, that sums up one of the quirks of emacs. Its way of hiding
its light under the proverbial bushel.

Each time I come across one of these features (e.g. auto-revert-mode yesterday)
I note it down and am likely to use it.

Has anyone documented the feature list (without going on to extensions)
that is present in the 'out of the box' emacs?
I swear I could use emacs for 20 years and still find out new things
that I could find useful.

RTFM won't cut it Tim <chuckles/>.

I'm not even sure how such a list might be documented. I'd go looking for
auto-revert-mode under 'refresh' or some such.

Is it worthwhile? Probably not if you're content with emacs.

regards




-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

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

[Joost Kremers]

Dave Pawson wrote:
> I swear I could use emacs for 20 years and still find out new things
> that I could find useful.

yup. i'm not going on 20 yet (it's just about 7 years, i reckon), but i
think emacs is one of those things that you'll never know everything
about...

it's one of the reasons why i read emacs news groups. learn something new
every day! ;-)

-- 
Joost Kremers                                      joostkremers@yahoo.com
Selbst in die Unterwelt dringt durch Spalten Licht
EN:SiS(9)

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

[Stefan Monnier]

> I swear I could use emacs for 20 years and still find out new things
> that I could find useful.

I've been an Emacs maintainer for what... 10 years?
I still occasionally bump into a bundled *package* that I've never heard of.


        Stefan

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

[Tom Tromey]

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

>> I swear I could use emacs for 20 years and still find out new things
>> that I could find useful.

Stefan> I've been an Emacs maintainer for what... 10 years?  I still
Stefan> occasionally bump into a bundled *package* that I've never
Stefan> heard of.

Most long-time Emacs users I talk to have a similar experience.  I
think this is one of the great joys of Emacs.

On the minus side, discoverability remains a problem.  Sometimes I
wish I'd found those features years earlier.

Tom

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

[Dave Pawson]

On 21/09/2007, Tom Tromey <tromey@redhat.com> wrote:

> Most long-time Emacs users I talk to have a similar experience.  I
> think this is one of the great joys of Emacs.
>
> On the minus side, discoverability remains a problem.  Sometimes I
> wish I'd found those features years earlier.

That's the problem I'm trying to address.
If the list members could provide the 'clues' I'm more than willing
to collate them, or perhaps we could use a wiki or some other web site
to collect them?

Ideas for an 'index' please? What form? Its the match of 'idea/usage'
vs package name/variable/mode. Generally once you have the key words,
emacs is sufficiently helpful?

regards



-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

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

[Eli Zaretskii]

> Date: Sat, 22 Sep 2007 06:04:32 +0100
> From: "Dave Pawson" <dave.pawson@gmail.com>
> Cc: help-gnu-emacs@gnu.org, Stefan Monnier <monnier@iro.umontreal.ca>
> 
> > On the minus side, discoverability remains a problem.  Sometimes I
> > wish I'd found those features years earlier.
> 
> That's the problem I'm trying to address.
> If the list members could provide the 'clues' I'm more than willing
> to collate them, or perhaps we could use a wiki or some other web site
> to collect them?
> 
> Ideas for an 'index' please? What form? Its the match of 'idea/usage'
> vs package name/variable/mode. Generally once you have the key words,
> emacs is sufficiently helpful?

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.

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

[Dave Pawson]

On 22/09/2007, Eli Zaretskii <eliz@gnu.org> wrote:

> > Ideas for an 'index' please? What form? Its the match of 'idea/usage'
> > vs package name/variable/mode. Generally once you have the key words,
> > emacs is sufficiently helpful?
>
> 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).
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.

Not enough for me Eli, but another one to add to the list :-)

regards


-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

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

[Eli Zaretskii]

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

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

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.

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

I thought you were asking for finding packages by keywords (and I
thought Tom Tromey was talking about something like that as well):

Dave> > Ideas for an 'index' please? What form? Its the match of 'idea/usage'
Dave> > vs package name/variable/mode. Generally once you have the key words,
Dave> > emacs is sufficiently helpful?

Tom> Stefan> I've been an Emacs maintainer for what... 10 years?  I still
Tom> Stefan> occasionally bump into a bundled *package* that I've never
Tom> Stefan> heard of.
Tom> 
Tom> Most long-time Emacs users I talk to have a similar experience.  I
Tom> think this is one of the great joys of Emacs.
Tom> 
Tom> On the minus side, discoverability remains a problem.  Sometimes I
Tom> wish I'd found those features years earlier.

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

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

[Dave Pawson]

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.


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


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




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

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 was trying to be helpful Eli.

regards


-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

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

[Eli Zaretskii]

> Date: Sat, 22 Sep 2007 14:12:43 +0100
> From: "Dave Pawson" <dave.pawson@gmail.com>
> 
> 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 don't think the problem is with generating the documentation.  Emacs
already has a huge body of documentation, both in the doc strings and
in the manuals that are part of the distribution.

I think the problem is _searching_ the available documentation.  So I
think what is needed is enhancing existing commands related to
documentation, or maybe adding one additional command, that would
efficiently search all the available sources of documentation.
Something like Google, just limited to the Emacs docs.  Such a search
command could then include a data base of synonyms to popular features
that people tend to look for.  (Right now, we are forced to mention
all the synonyms in the indexing directives that are part of the
manual.)

> My term for this would would most likely be 'auto-reload' or some
> such, i.e. when the file changes on disk, reload it.

If ``reload'' is something many people think of when they envision
such a feature, it should be easy enough to add that word to the
existing indexing of the manual and to the relevant doc strings.
However, I find this word surprising in this context.  What other
similar software packages use it?

> I'd find it hard to see how you'll collect other peoples understanding of
> the keywords.

By reading messages where people tell how they tried to search for
something in the docs.  And by applying personal knowledge, of course.

> That's why I suggested a wiki approach or webpage.

I'd instead urge people to tell here (or on emacs-devel) how they
search for things, when the search fails to find what they want.  A
wiki has a disadvantage that it requires the developers to look there
to become aware of users' needs.  That's why we encourage users to
report documentation bugs in such cases: the developers watch the
mailing lists where the bug reports get posted, and will react on them
soon enough.

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

There should be no reason for you to navigate the Info manuals.  Try
using the `i' (Info-index) command instead, it should land you on the
right spot almost instantaneously.  And it supports completion.

> I was trying to be helpful Eli.

I never thought otherwise.  If my responses somehow sounded that I
didn't consider yours helpful, I apologize.

Thanks.

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

[Drew Adams]

> 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 was trying to be helpful Eli.

Nothing wrong with your motivation. And, yes, trying to provide a useful index (in whatever form) usually requires some human effort and judgment - automatic indexing is somewhat limited in practice.

Eli, too, was trying to be helpful - and he was helpful, no? You'll find that usually when Eli learns of another possible path to some term or some section in an Emacs  manual, he adds it to one or more manual indexes. And he typically asks, when someone has difficulty finding information, _how_ they were going about it unsuccessfully, in order to try to improve the search process and indexing. In this case, he will no doubt add some terms to accomodate your quandary. You need only make it clear what you are searching for and how you went about it.

You are right that it can be problematic (and useful!) to collect user input about what should perhaps be new index entries. Only a certain number of users will use help-gnu-emacs@gnu.org and let others know about their frustrated attempts to look something up. But if a user does raise the question here, Eli will usually respond and take the user's quest into consideration. 

You could also create a page on EmacsWiki to collect such keywords: http://www.emacswiki.org/cgi-bin/wiki/SiteMap. Then, either Eli or some other Emacs developer might occasionally check what has been added there, or you or someone else could occasionally post here any new entries that are collected there. Emacs Wiki is an incredible collaborative resource, and it's low-key, dumb-easy to use.

As frequenters of this list and emacs-devel@gnu.org will attest, Eli and I don't always agree ;-), but followup to improve the manual indexes is one area (there are others) where I think he does a terrific job. The point here is that your proposal to collect unsuccessful user search attempts, synonyms and the like can be plugged into the existing mechanisms such as manual indexes, and Eli is quite helpful in this regard.

Wrt difficulty navigating Emacs Info pages: try Icicles - http://www.emacswiki.org/cgi-bin/wiki/Icicles. Command `icicle-Info-index' (`i' in Info) lets you easily navigate index entries, and command `icicle-Info-goto-node' (`g' in Info) lets you easily browse Info nodes. They let you type a substring or other regexp and zip around all index terms or node names that match, in any order. See http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Info_Enhancements.

And (no relation with Icicles) with Emacs 22, you can use incremental search throughout a manual. If something has no index entry, try repeated `C-s'. Then let help-gnu-emacs know if you think what you were looking for should be added to the index.

Wrt "indexable html pages derived from indexed xml": It's not a bad idea, and it has been discussed before by Emacs development contributors. Info is currently not XML or HTML based, and a move in such a direction is not trivial. But all ideas and implementation and design efforts are appreciated - emacs-devel@gnu.org.

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

[Drew Adams]

> > My term for this would would most likely be 'auto-reload' or some
> > such, i.e. when the file changes on disk, reload it.
>
> If ``reload'' is something many people think of when they envision
> such a feature, it should be easy enough to add that word to the
> existing indexing of the manual and to the relevant doc strings.
> However, I find this word surprising in this context.  What other
> similar software packages use it?

I have seen "reload" used with a similar meaning, notably in Web browsers.
Browsers also use "refresh" similarly.

I have also seen "read again" and "re-read" used this way for file editing.

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

[Dave Pawson]

On 22/09/2007, Drew Adams <drew.adams@oracle.com> wrote:

> Nothing wrong with your motivation. And, yes, trying to provide a useful index (in whatever form) usually requires some human effort and judgment - automatic indexing is somewhat limited in practice.

Yes, we all view things differently I guess.

>
> Eli, too, was trying to be helpful - and he was helpful, no?
Yes. I learned from this thread.



>
> You could also create a page on EmacsWiki to collect such keywords: http://www.emacswiki.org/cgi-bin/wiki/SiteMap. Then, either Eli or some other Emacs developer might occasionally check what has been added there, or you or someone else could occasionally post here any new entries that are collected there. Emacs Wiki is an incredible collaborative resource, and it's low-key, dumb-easy to use.

another one. I'd never seen that.
(I'm beginning to feel as Tims RTFM might be more applicabe than usual
for me :-)




>
> As frequenters of this list and emacs-devel@gnu.org will attest, Eli and I don't always agree ;-), but followup to improve the manual indexes is one area (there are others) where I think he does a terrific job. The point here is that your proposal to collect unsuccessful user search attempts, synonyms and the like can be plugged into the existing mechanisms such as manual indexes, and Eli is quite helpful in this regard.

I've no issue with feeding back to Eli or the wiki.
Maybe like Steve, I find XML more flexible when I want to re-index, so
I'm looking
at creating an XML version. Currently fighting the ??? (I think it's
texi, but unsure)
source from http://www.gnu.org/software/emacs/manual/emacs.html to generate
docbook. That's a good start for me.
The html output is SGML, not XHTML, so that's harder, and the --docbook seems
to produce an empty file, using
http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs.sh

Does it work with the downloaded files? emacs emacs[1..8]
It seems to cough and look for a .texi extension?


Any suggestions how that might work?
I'm trying
 $ ./gendocs.sh --docbook -o tmp emacs "Emacs"
on the gunzipped emacs.info.tar.gz from the same page.



>
> Wrt difficulty navigating Emacs Info pages: try Icicles - http://www.emacswiki.org/cgi-bin/wiki/Icicles. Command `icicle-Info-index' (`i' in Info) lets you easily navigate index entries, and command `icicle-Info-goto-node' (`g' in Info) lets you easily browse Info nodes. They let you type a substring or other regexp and zip around all index terms or node names that match, in any order. See http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Info_Enhancements.

<prejudice/> I really don't like | find hard to use, the info style
stuff. I guess I've
been spoiled with searchable, navigable html over the years I've been
using emacs?
I've offered to work on a docbook version with a better index, to Eli, offlist.



>
> And (no relation with Icicles) with Emacs 22, you can use incremental search throughout a manual. If something has no index entry, try repeated `C-s'. Then let help-gnu-emacs know if you think what you were looking for should be added to the index.

There's enough in this thread to start a hunt the thimble thread on the wiki!
help-gnu-emacs, is that a feedback idea? <sigh/> Does that mean a default
emacs Linux installation can get connected without me doing anything?



>
> Wrt "indexable html pages derived from indexed xml": It's not a bad idea, and it has been discussed before by Emacs development contributors. Info is currently not XML or HTML based, and a move in such a direction is not trivial. But all ideas and implementation and design efforts are appreciated - emacs-devel@gnu.org.


Honestly, I'd be far happier working in docbook xml!
Now just need to get the shell script working :-)


regards


-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Sat, 22 Sep 2007 09:23:24 -0700
> 
> And, yes, trying to provide a useful index (in whatever form) usually requires some human effort and judgment - automatic indexing is somewhat limited in practice.

Well, Google (and other search engines) demonstrate that an automatic
indexing can be very useful, too.

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

[Drew Adams]

> > And, yes, trying to provide a useful index (in whatever form) 
> > usually requires some human effort and judgment - automatic 
> > indexing is somewhat limited in practice.
> 
> Well, Google (and other search engines) demonstrate that an automatic
> indexing can be very useful, too.

Yes, full-text search is powerful and useful.

A book index is something else.

http://www.asindexing.org/site/indfaq.shtml

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

[Tim X]

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

> On 21/09/2007, Eli Zaretskii <eliz@gnu.org> wrote:
>
>> How did you come up with the string "novice" as something to look for?
>> The Emacs manual describes this feature as "disabled command", and
>> both "M-x apropos disabled" and "i disabled" in the manual find quite
>> a few hits.
>
> For me, that sums up one of the quirks of emacs. Its way of hiding
> its light under the proverbial bushel.
>
> Each time I come across one of these features (e.g. auto-revert-mode yesterday)
> I note it down and am likely to use it.
>
> Has anyone documented the feature list (without going on to extensions)
> that is present in the 'out of the box' emacs?
> I swear I could use emacs for 20 years and still find out new things
> that I could find useful.
>
> RTFM won't cut it Tim <chuckles/>.
>
> I'm not even sure how such a list might be documented. I'd go looking for
> auto-revert-mode under 'refresh' or some such.
>
> Is it worthwhile? Probably not if you're content with emacs.
>

Hi Dave,

You probably don't want to hear this, but your so called feature list
exists in the manual, its just not called a feature list. Open the emacs
manual and scroll down to the detailed node listing. This in effect is a
summary of emacs features that links to the sections of the manual they are
covered in. 

In the detailed node listing you will find the following section -

File Handling

* File Names::          How to type and edit file-name arguments.
* Visiting::            Visiting a file prepares Emacs to edit the file.
* Saving::              Saving makes your changes permanent.
* Reverting::           Reverting cancels all the changes not saved.
* Autorevert::          Auto Reverting non-file buffers.
* Auto Save::           Auto Save periodically protects against loss of data.
* File Aliases::        Handling multiple names for one file.
* Version Control::     Version control systems (RCS, CVS and SCCS).
* Directories::         Creating, deleting, and listing file directories.
 Comparing Files::     Finding where two files differ.
* Diff Mode::           Editing diff output.
* Misc File Ops::       Other things you can do on files.
* Compressed Files::    Accessing compressed files.
* File Archives::       Operating on tar, zip, jar etc. archive files.
* Remote Files::        Accessing files on other sites.
* Quoted File Names::   Quoting special characters in file names.
* File Name Cache::     Completion against a list of files you often use.
* File Conveniences::   Convenience Features for Finding Files.
* Filesets::            Handling sets of files.

so there it is, a list of features in standard emacs that deals with file
handling, including a menu item for revert and auto-revert. It even defines
what evert means in case your not familiar with the term. I really can't
see how it can be made any clearer.  

Even the answer to the OPs original question appears to be covered on the
first page of the manual entry e.g. 

,----
|    When you edit a file that changes automatically and frequently--for
| example, a log of output from a process that continues to run--it may be
| useful for Emacs to revert the file without querying you, whenever you
| visit the file again with `C-x C-f'.
| 
|    To request this behavior, set the variable `revert-without-query' to
| a list of regular expressions.  When a file name matches one of these
| regular expressions, `find-file' and `revert-buffer' will revert it
| automatically if it has changed--provided the buffer itself is not
| modified.  (If you have edited the text, it would be wrong to discard
| your changes.)
`----

It then goes into more details regarding three different auto-revert
mechanisms that are available. 

To be honest and not trying to be rude, I still feel the "problem" is
people wanting answers without doing the reading/work. In the current
example, I get a very strong feeling the OP encountered a change in
behavior and immediately fired off a question to the NG without checking
the documentation. Not only are things (IMO) clearly laid out in the emacs
manual, therre is even a section in the NEWS-22 file entitled **
Auto-Revert changes 

Whenever anyone observes changes in behavior in a new version of emacs, the
very first place they should look is in the NEWS and PROBLEMS file for the
version they have upgraded to. In fact, when I upgrade to a new version of
emacs, I always check the NEWS file to see what new features have been
added and what may have changed that will impact on how I do things or
possibly break some of my own elisp code. If I run into any problems, the
first place I check is the PROBLEMS file to see if it is a known issue. 

So, I'm afraid the answer is still RTFM. Even if we created another file
called FEATURES or "Emacs-out-of-the-box-features" or whatever, I don't
think it will make any difference - people still won't read them. The real
problem here is what some want is some sort of osmotic knowledge transfer
that requires no additional work for the user - you somehow open the editor
and all required knowledge just transfers itself to the user with no
concious effort on the users behalf. 

So  Dave, guess what, my advice .....RTFM!

regards,

Tim

-- 
tcross (at) rapttech dot com dot au

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

[Tim X]

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

> On 21/09/2007, Tom Tromey <tromey@redhat.com> wrote:
>
>> Most long-time Emacs users I talk to have a similar experience.  I
>> think this is one of the great joys of Emacs.
>>
>> On the minus side, discoverability remains a problem.  Sometimes I
>> wish I'd found those features years earlier.
>
> That's the problem I'm trying to address.
> If the list members could provide the 'clues' I'm more than willing
> to collate them, or perhaps we could use a wiki or some other web site
> to collect them?
>
> Ideas for an 'index' please? What form? Its the match of 'idea/usage'
> vs package name/variable/mode. Generally once you have the key words,
> emacs is sufficiently helpful?
>

As you will see from my other post, I think this already exists in that
most entries in the emacs manual (specifically the detailed node listing)
describe what the item does as part of the description associated with that
menu item.. Of course, there ar problems here in that we are dealing with a
system that is used in many different countries with different
interpretations of various terms (even within all the countries that use
English, you can find confusing variation in the use of words).

This doesn't mean it isn't a good idea to try alternatives that may help
overcome this limitation of spoken language. My recommendation would be to
put a page up on the emacs wiki. This would allow others, possibly from
different backgrounds or for whom english is a second language, to add
additional entries, examples or clarification. I find the emacs wiki a
great resource and often spend a few hours browsing it and learning new
techniques/ideas. Often, this involves using features I was aware of, but
in ways I had not considered. 

The only request I would make is to please include links to the relevant
manual entry rather than re-write or re-do what is in the manual. One of
the biggest areas of confusion that I see with emacs is all the out of date
pages that advise people to do exactly the wrong thing. These pages are
seldom as up-to-date as the emacs manual. So, for example, rather than
explain how to use auto-revert, just define what is meant by revert in
emacs terms and then point to the relevant manual section. 

regards,

Tim







-- 
tcross (at) rapttech dot com dot au

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

[Dave Pawson]

On 23/09/2007, Tim X <timx@nospam.dev.null> wrote:

> So  Dave, guess what, my advice .....RTFM!


No Tim, I'd never found either of those indices. Like Steve, I'm still looking
at the word revert and seeing some form of 'go back' to something.
IMHO, today, it's plain wrong. The CMS example even justified that
interpretation.

Yes, another index, presuming familiarity with the oddities of texinfo.
Eli tells me that it is the official policy of gnu. I find that archaic.

Looking at
http://savannah.gnu.org/search/index.php?type_of_search=soft&words=%%%
there isn't even a general gnu documentation list, seems that texinfo is a given
and not open to a challenge.

Ah well.


regards

-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

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:
>
>> > Ideas for an 'index' please? What form? Its the match of 'idea/usage'
>> > vs package name/variable/mode. Generally once you have the key words,
>> > emacs is sufficiently helpful?
>>
>> 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).
> 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.
>

I'll start by saying I'm really not trying to be difficult here and realy
want to understand why you are finding the emacs features and functions so
difficult to feel comfortable with. The main issue I have trouble
understanding is that you seem to be coming from the position where you
find the help system lacking, yet I find the emacs help system to be the
best I've ever come across in any software package I've used in over 20
years of working with software. The fact you don't seem to be finding it
that good in itself indicates a possible problem, but I don't understand
what the basis of that is. Part of me feels that in some way your working
against the system rather than adapting to it (plus maybe a bit of the lazy
web syndrome :-).

I'll try to briefly outline how I started with emacs. Maybe the differences
in our approaches will clarify matters. 

When I first started emacs, the very first thing I did was do the built-in
tutorial. Have you ever done that?

The second thing I did was read the intro section in the emacs manual. I
then read the help section. 

I spent a bit of time playing around with the commands described in the
help section and got to understand what they all did. This was possibly the
most beneficial effort I put in. Knowing how to search the info manual,
jump to specific sections based on what the point was on within a buffer,
search for keywords etc was extremely useful. 

I then read the more genral sections from the manual covering basic
editing. Over the next few weeks, I would regularly open the manual and
look at the detailed node index. Sometimes I'd notice interesting entries,
such as "* Fixit::	        Commands especially useful for fixing typos."
or "* Abbrevs::	        How to define text abbreviations to reduce
the number of characters you must type." etc. When starting a new
programming or writing task, I'd first check the relevant sections of the
manual to find out what emacs had to offer in support of the particular
activity I was doing (i.e. various programming modes, etc). 

After a few months, I had pretty much completely read the emacs manual from
front to back. I often made use of the glossory and concept index
sections. While it may sound disconcerting that it took me a few months to
cover all this material, it is important to remember that I was productive
with emacs from the first day and that it is a large feature rich
package. Nobody is going to get across all it has to offer in a few hours
or even a few days. As reported by others and experienced first hand, emacs
is a package which will continue to reveal new features or ways of using
known existing features for a long time - possibly indefinitely. In fact,
it has so much, I doublt theer is anyone who is across all of it. In fact,
after over 10 years of use, there is considerable functionality that I have
forgotten about and only remember it when I see a post or an item on the
wiki that reminds me. 

I think its very size and number of features means it is unlikely anyone
will every be successful in finding a solution that makes it almost
automatic or intuitive or even straight-forward to find the precise feature
that meets their requirement. For one thing, it will be impossible to index
things in a way that is intuitive to everyone - people just vary too much
in how they think, the terms and language they use and their
backgrounds. We should certainly try to make this as easy as possible, but
I persoonally find that it does a really good job of that already and can't
see anything obvious that will improve the situation. Of course, I freely
admit I could be totally wrong, which is why I suggest an emacs wiki
page. If I am wrong, I would expect lots of people will have things to
add. If this turns out to be the situation, then there may be a case for
adding that content to the manual or as an aditional file in the
distribution. 

regards,

Tim

-- 
tcross (at) rapttech dot com dot au

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

[Dave Pawson]

On 23/09/2007, Tim X <timx@nospam.dev.null> wrote:

> This doesn't mean it isn't a good idea to try alternatives that may help
> overcome this limitation of spoken language. My recommendation would be to
> put a page up on the emacs wiki. This would allow others, possibly from
> different backgrounds or for whom english is a second language, to add
> additional entries, examples or clarification. I find the emacs wiki a
> great resource and often spend a few hours browsing it and learning new
> techniques/ideas. Often, this involves using features I was aware of, but
> in ways I had not considered.

OK. good a place as any Tim. Thanks.



>
> The only request I would make is to please include links to the relevant
> manual entry rather than re-write or re-do what is in the manual.

That's my problem Tim. I don't know whats in the manual, simply because
I find it hard to use.


One of
> the biggest areas of confusion that I see with emacs is all the out of date
> pages that advise people to do exactly the wrong thing. These pages are
> seldom as up-to-date as the emacs manual.

I'm suggesting that the manual be available fully in navigable html,
derived from an XML master. The info files could be similarly derived.
There's a lot more experience of I18N use in XML than in texinfo I'd guess.

Eli pointed out that the actual elisp files contain bits which are
used in the manual.
My proposal there was, as the lisp is being packaged for delivery, the
'bits' needed
in the elisp be 'included', by some sort of pre-processing step
(what's the elisp
for #include?) such that *all* documentation is single sourced for translation
and use in all formats.

regards




-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

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

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

[David Kastrup]

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

> On 23/09/2007, Tim X <timx@nospam.dev.null> wrote:
>
>> So  Dave, guess what, my advice .....RTFM!
>
>
> No Tim, I'd never found either of those indices.

Then perhaps it would be time to get acquainted with the documentation
system of Emacs.  Use the menu Help/Search Documentation/Look up
Subject in User Manual and type "revert" into it.  Or use Help/Search
Documentation/Emacs Terminology and type "revert".

If you have not found the information, it is because you did not even
think of asking Emacs for it.  The "Help" menu is there for a purpose.

> Yes, another index, presuming familiarity with the oddities of
> texinfo.  Eli tells me that it is the official policy of gnu. I find
> that archaic.

A working fast and efficient tool that is easy to use is not lightly
replaced.  Hammers might be archaic tools, but they still do the job
of driving nails.

> http://savannah.gnu.org/search/index.php?type_of_search=soft&words=%%%
> there isn't even a general gnu documentation list, seems that
> texinfo is a given and not open to a challenge.

There is no working challenge around.  HTML does not contain useful
indexing and structuring information.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

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

[Dave Pawson]

On 23/09/2007, Tim X <timx@nospam.dev.null> wrote:

> I'll start by saying I'm really not trying to be difficult here and realy
> want to understand why you are finding the emacs features and functions so
> difficult to feel comfortable with. The main issue I have trouble
> understanding is that you seem to be coming from the position where you
> find the help system lacking, yet I find the emacs help system to be the
> best I've ever come across in any software package I've used in over 20
> years of working with software. The fact you don't seem to be finding it
> that good in itself indicates a possible problem, but I don't understand
> what the basis of that is. Part of me feels that in some way your working
> against the system rather than adapting to it (plus maybe a bit of the lazy
> web syndrome :-).

Quite possibly right on both counts Tim.
I'll emphasise your phrasing. 'Rather than adapting to it'.
I'd rather adapt technology to what I want in preference to learning
how a system
works and adapting my way of working to the tool.


>
> I'll try to briefly outline how I started with emacs. Maybe the differences
> in our approaches will clarify matters.
>
> When I first started emacs, the very first thing I did was do the built-in
> tutorial. Have you ever done that?

No. Why? Because the baseline info system I found klunky and horrible.
I'll guess its because I came from a hyperlinked world view.


>
> The second thing I did was read the intro section in the emacs manual. I
> then read the help section.

<guilty>If all else fails, RTFM</guilty>
But I guess you know that by now.


>
> I spent a bit of time playing around with the commands described in the
> help section and got to understand what they all did. This was possibly the
> most beneficial effort I put in. Knowing how to search the info manual,
> jump to specific sections based on what the point was on within a buffer,
> search for keywords etc was extremely useful.

Noting that I was trying to learn SGML, DSSSL, Scheme at the time,
emacs was the only editor I found that could tackle them. Hence I viewed
emacs as a tool on the way to doing a job, not an end in its own right?
I *think* this was before I bought my first Learning emacs book too.



<snip/>

>
> After a few months, I had pretty much completely read the emacs manual from
> front to back. I often made use of the glossory and concept index
> sections.

Aside. I'm currently converting basic.texi, and noted that it has a
number of indices,
something that docbook processing currently doesn't support. +1 to texinfo...
until it's added to the docbook processing.

While it may sound disconcerting that it took me a few months to
> cover all this material, it is important to remember that I was productive
> with emacs from the first day and that it is a large feature rich
> package. Nobody is going to get across all it has to offer in a few hours
> or even a few days. As reported by others and experienced first hand, emacs
> is a package which will continue to reveal new features or ways of using
> known existing features for a long time - possibly indefinitely. In fact,
> it has so much, I doublt theer is anyone who is across all of it. In fact,
> after over 10 years of use, there is considerable functionality that I have
> forgotten about and only remember it when I see a post or an item on the
> wiki that reminds me.

I doubt many will argue with that Tim. Marvelous bit of kit.
I'm beginning to appreciate that the documentation for emacs actually
matches its capability. What I don't agree is that it is presented in
an approachable manner.


>
> I think its very size and number of features means it is unlikely anyone
> will every be successful in finding a solution that makes it almost
> automatic or intuitive or even straight-forward to find the precise feature
> that meets their requirement. For one thing, it will be impossible to index
> things in a way that is intuitive to everyone - people just vary too much
> in how they think, the terms and language they use and their
> backgrounds. We should certainly try to make this as easy as possible, but
> I personally find that it does a really good job of that already and can't
> see anything obvious that will improve the situation. Of course, I freely
> admit I could be totally wrong, which is why I suggest an emacs wiki
> page. If I am wrong, I would expect lots of people will have things to
> add. If this turns out to be the situation, then there may be a case for
> adding that content to the manual or as an aditional file in the
> distribution.

Whats the saying? Different strokes for different folks.
I'm fully sympathetic to the view that we'll never get an index to suite
everyone.
  I do think presentation and cross-referencing
can be improved though. That's my starting point.

regards



-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

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

[Dave Pawson]

On 23/09/2007, David Kastrup <dak@gnu.org> wrote:

> Then perhaps it would be time to get acquainted with the documentation
> system of Emacs.

I agree David. I am. From the .texi files as my starting point.


> If you have not found the information, it is because you did not even
> think of asking Emacs for it.  The "Help" menu is there for a purpose.

I think I'm beginning to see that. And just how complete it is, from Tim
and other peoples input.
btw, Eli has agreed to add the reload term to the docs as another way into
'revert'.


>
> > Yes, another index, presuming familiarity with the oddities of
> > texinfo.  Eli tells me that it is the official policy of gnu. I find
> > that archaic.
>
> A working fast and efficient tool that is easy to use is not lightly
> replaced.  Hammers might be archaic tools, but they still do the job
> of driving nails.

Not sure of the analogy, but I'd suggest the comparator might be
a branch of a tree rather than a modern hammer.
The only part I find objectionable is having to bend the way I work
to an archaic tool.


>
> > http://savannah.gnu.org/search/index.php?type_of_search=soft&words=%%%
> > there isn't even a general gnu documentation list, seems that
> > texinfo is a given and not open to a challenge.
>
> There is no working challenge around.  HTML does not contain useful
> indexing and structuring information.

I believe there is. XML, not html. utf-8/16 encoding. Semantic markup way
beyond what .texi can do, structured, encoding, fully supported by transforms
etc. Eli points out the low likelihood of gnu adopting XML as a documentation
system, which I can see.

http://docbook2x.sourceforge.net/ even provides the transform so that Tim
and others can continue to use the texi system. What you'd do with the
Euro (&#x20AC;)
I'm less sure, but perhaps there aren't any non-English speaking emacs users?

regards


-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

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

[David Kastrup]

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

> On 23/09/2007, David Kastrup <dak@gnu.org> wrote:
>
>> Then perhaps it would be time to get acquainted with the
>> documentation system of Emacs.
>
> I agree David. I am. From the .texi files as my starting point.

One does not get acquainted with Emacs' editing by reading its C and
Lisp source code either.  The documentation system of Emacs is _info_
as far as online access is concerned.  The .texi files are not
intended for reading, but for writing.  It is source code.

So I really repeat the recommendation to get acquanted with the info
reader in Emacs.  It puts the information at your fingertip, and the
.texi files don't do that.

>> A working fast and efficient tool that is easy to use is not
>> lightly replaced.  Hammers might be archaic tools, but they still
>> do the job of driving nails.
>
> Not sure of the analogy, but I'd suggest the comparator might be a
> branch of a tree rather than a modern hammer.  The only part I find
> objectionable is having to bend the way I work to an archaic tool.

Again, you are confusing format and reader.  The Texinfo format is
archaic (but nevertheless quite alive).  The reader is what Emacs
offers you.  Nobody has ever proposed a user interface that would be
more efficient or convenient than Emacs' current info reader.  So the
source of contention is the source file format (and the compiled
_fast_ info format), but that is nothing that would affect the _usage_
of the files: changing the format would probably achieve no
user-visible change inside of Emacs apart from slowing it down.  At
the current point of time, info access is near instantaneous.

>> > http://savannah.gnu.org/search/index.php?type_of_search=soft&words=%%%
>> > there isn't even a general gnu documentation list, seems that
>> > texinfo is a given and not open to a challenge.
>>
>> There is no working challenge around.  HTML does not contain useful
>> indexing and structuring information.
>
> I believe there is. XML, not html.

XML is not an end user format.

> utf-8/16 encoding. Semantic markup way beyond what .texi can do,
> structured, encoding, fully supported by transforms etc. Eli points
> out the low likelihood of gnu adopting XML as a documentation
> system, which I can see.
>
> http://docbook2x.sourceforge.net/ even provides the transform so
> that Tim and others can continue to use the texi system.

docbook2x is undocumented software.  I used it to provide a user
manual in info format for git.  It was reasonably easy to do this,
except that it was near impossible to put the respective directory
entries at the top.  After working on this a few days, I punted and
used a Perl script for post-processing the Texinfo file.  It seems
from the few uses one sees on the Web that nobody else fared better.

I also tried getting the manual pages of git into an appendix in the
user manual and failed abysmally.

The combined largely under- or undocumented and inscrutable layerism
of XML, Docbook, Ascii2doc and Docbook2x makes it impossible to
achieve a particular effect at the end of the toolchain without weeks
of previous study.

While the toolchain may be in better shape (I found it to produce
pretty much perfect Texinfo from the get-go while Texinfo's Docbook
output was ill-formed), it is just not usable without months of study
and fishing for information in distributed places.

Coming back to the manual page problem: in Texinfo, this could be
solved easily using @include and @raisesections, consulting just a
single manual about a single format, a well-structured and indexed
manual that can be browsed efficiently in Emacs even on slow machines.

In contrast, the information for the XML toolchains is scattered all
over the place and rarely in a format that can be readily browsed by
humans without starting to convert and manipulate stuff first.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

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

[Bastien]

Tim X <timx@nospam.dev.null> writes:

> In fact, after over 10 years of use, there is considerable
> functionality that I have forgotten about and only remember it when I
> see a post or an item on the wiki that reminds me.

I think this is the whole point of the "personal help manager" I'm
mentionning in my previous post.

-- 
Bastien

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

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

Tom> On the minus side, discoverability remains a problem.  Sometimes I
Tom> wish I'd found those features years earlier.

>> Ideas for an 'index' please? What form? Its the match of 'idea/usage'
>> vs package name/variable/mode. Generally once you have the key words,
>> emacs is sufficiently helpful?

Eli> Instead of inventing new machinery, how about enhancing the existing
Eli> one?  "C-h P" is supposed to use the index you seem to think about.

FWIW I think Emacs has excellent documentation.

The fundamental discoverability problem with Emacs isn't that the
documentation is missing -- it never is.  The problem is, if you want
to find something by keyword, first you must guess the keyword that
the original author used.

I don't know a good way to solve this problem.  Usually if I'm
motivated to look for something I end up doing many searches --
apropos, multiple keyword searches through various info documents, the
Emacs Wiki, and Google.  Even then I sometimes won't find something.

This is hard enough that my need has to be pretty severe -- or have
triggered my curiosity -- to bother.  Otherwise it is usually simpler
to muddling through with whatever (usually less efficient) approach
I've been using.

Tom

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

[David Kastrup]

Tom Tromey <tromey@redhat.com> writes:

> The fundamental discoverability problem with Emacs isn't that the
> documentation is missing -- it never is.  The problem is, if you want
> to find something by keyword, first you must guess the keyword that
> the original author used.

Help/Search Documentation/Emacs Terminology

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

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

[Tom Tromey]

>>>>> "David" == David Kastrup <dak@gnu.org> writes:

David> Tom Tromey <tromey@redhat.com> writes:
>> The fundamental discoverability problem with Emacs isn't that the
>> documentation is missing -- it never is.  The problem is, if you want
>> to find something by keyword, first you must guess the keyword that
>> the original author used.

David> Help/Search Documentation/Emacs Terminology

That's a nice page, but I don't think it is a real solution to the
general discoverability problem.  It helps a bit, but only a bit.

FWIW, I don't think this problem is a major thing.  It does mean that
many of Emacs' features probably go under-used.  Even with this hand
tied behind its back, it is still better than other editors :-)

Anyway, my experience is that when looking for something, I wind up
looking for it under some set of key words I choose.  Usually these
are similar enough to what the feature's author chose;less frequently,
I just miss completely.

Adding more key words to the docs helps this, of course.  But this
requires someone to find the feature, remember their wrong guesses,
report them, and then convince the maintainers to add some text.  So,
no wonder if it doesn't happen much.

Tom

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

[Joost Kremers]

Tom Tromey wrote:
> FWIW, I don't think this problem is a major thing.  It does mean that
> many of Emacs' features probably go under-used.  Even with this hand
> tied behind its back, it is still better than other editors :-)

i don't think emacs is any different in that respect than other large
software programs. or do you think that every openoffice.org user knows all
the features that suite has to offer? ;-)


-- 
Joost Kremers                                      joostkremers@yahoo.com
Selbst in die Unterwelt dringt durch Spalten Licht
EN:SiS(9)

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

[Eli Zaretskii]

> From: Tom Tromey <tromey@redhat.com>
> Date: Sun, 23 Sep 2007 10:14:04 -0600
> 
> The fundamental discoverability problem with Emacs isn't that the
> documentation is missing -- it never is.  The problem is, if you want
> to find something by keyword, first you must guess the keyword that
> the original author used.
> 
> I don't know a good way to solve this problem.

Well, we could add a feature whereby documentation search commands
will suggest to look for alternative keywords.  This feature could use
a database of synonyms for computer-related terminology, as well as
popular alternatives for certain Emacs parlance (such as "yank" etc.).

This way, if you didn't find what you wanted, you'd be presented with
a list of additional words or phrases to search for.

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

[Eli Zaretskii]

> Date: Sun, 23 Sep 2007 09:56:08 +0100
> From: "Dave Pawson" <dave.pawson@gmail.com>
> 
> http://docbook2x.sourceforge.net/ even provides the transform so that Tim
> and others can continue to use the texi system. What you'd do with the
> Euro (&#x20AC;) I'm less sure

Texinfo supports non-ASCII text for a few years, so I don't think this
is a problem.

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

[Tom Horsley]

On Thu, 20 Sep 2007 11:22:15 -0700, Bruce Korb wrote:

> OK.  I've vented now.  Would someone please be kind enough to tell me
> how to shut down the novice stuff completely?  Thank you.

I have similar problems every emacs release. I can see an argument
for making spiffy new features the default (else no one will notice
them), but when one user finds a new helpful feature to be annoying
rather than helpful, it would sure be nice if there were a standard
way to get back the old behavior.

I've always wished each emacs release would come with a doc file
mentioning each new feature and giving the lisp code to add to
your .emacs file to put it back the way it was in the previous
release. (Of course even that might not help much if the new
behavior is merely some annoying visual, you may not know the
correct jargon to search for in the file to figure out how to
turn it off, but you could always try each snippet of lisp
till you find the one that does the trick :-).

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

[David Kastrup]

Tom Horsley <tomhorsley@comcast.net> writes:

> On Thu, 20 Sep 2007 11:22:15 -0700, Bruce Korb wrote:
>
>> OK.  I've vented now.  Would someone please be kind enough to tell me
>> how to shut down the novice stuff completely?  Thank you.
>
> I have similar problems every emacs release. I can see an argument
> for making spiffy new features the default (else no one will notice
> them), but when one user finds a new helpful feature to be annoying
> rather than helpful, it would sure be nice if there were a standard
> way to get back the old behavior.
>
> I've always wished each emacs release would come with a doc file
> mentioning each new feature and giving the lisp code to add to
> your .emacs file to put it back the way it was in the previous
> release.

f1 C-n

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

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

[Sean Sieger]

   To be honest and not trying to be rude

   [...]

   guess what, my advice .....RTFM!

The `F' part is rude.

Rudeness aside, there is a certain opacity to the GNU Emacs Manual that,
for me is only subverted by reading---or maybe scanning---every message
posted to this list and stumbling on useful functions and variables
while looking for something else (which I don't usually find) in the
manual.

I have learned more about Emacs reading threads on this list with
subject lines of seemingly no interest to me than anywhere else.

You *are* right about `The Detailed Node Listing', it and the practice
of doing `C-h m' have been the most informative along with the chanceful
methods above.

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

[Johan Bockgård]

Eli Zaretskii <eliz@gnu.org> writes:

> Well, we could add a feature whereby documentation search commands
> will suggest to look for alternative keywords.  This feature could use
> a database of synonyms for computer-related terminology, as well as
> popular alternatives for certain Emacs parlance (such as "yank" etc.).

This seems somewhat apropos...

,----[ C-h v apropos-synonyms RET ]
| apropos-synonyms is a variable defined in `apropos.el'.
| Its value is 
| (("find" "open" "edit")
|  ("kill" "cut")
|  ("yank" "paste")
|  ("region" "selection"))
| 
| Documentation:
| List of synonyms known by apropos.
| Each element is a list of words where the first word is the standard Emacs
| term, and the rest of the words are alternative terms.
`----

-- 
Johan Bockgård

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

[Stefan Monnier]

> Yes, another index, presuming familiarity with the oddities of texinfo.
> Eli tells me that it is the official policy of gnu.  I find that archaic.

Maybe it's archaic to you, but I still haven't found any system available to
me that comes even close in terms of indexing.  Admittedly I haven't looked
hard, but everything I see in actual use is HTML accessed from
a web-browser, so there's no shorthand for doing an "index search" or
a "full body regexp search", ... it doesn't even have key bindings to "go
the next page" or "go back to the previous page" ("previous" as in "the page
before this one in the book, not in my browse-history").

Texinfo is pretty far from perfect, but it does have its advantages.
And its markup is usually a lot more readable than the godawful XML markup.


        Stefan

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

[Eli Zaretskii]

> From: bojohan+news@dd.chalmers.se (Johan =?utf-8?Q?Bockg=C3=A5rd?=)
> Date: Mon, 24 Sep 2007 02:38:59 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Well, we could add a feature whereby documentation search commands
> > will suggest to look for alternative keywords.  This feature could use
> > a database of synonyms for computer-related terminology, as well as
> > popular alternatives for certain Emacs parlance (such as "yank" etc.).
> 
> This seems somewhat apropos...
> 
> ,----[ C-h v apropos-synonyms RET ]

Sure, but the data base is too small, and it is only used internally
and silently, and only with `apropos-command'.

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

[Tim X]

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

> On 23/09/2007, Tim X <timx@nospam.dev.null> wrote:
>
>> So  Dave, guess what, my advice .....RTFM!
>
>
> No Tim, I'd never found either of those indices. Like Steve, I'm still looking
> at the word revert and seeing some form of 'go back' to something.
> IMHO, today, it's plain wrong. The CMS example even justified that
> interpretation.
>

This is the bit I obviously just don't understand - how could you not have
found the indexes and glossory? They are listed on the very first page of
the manual (at least they should be unless something is broken in your
version). 

With respect to revert - I don't agree it is just plain wrong. It only
seems wrong in one context - the one in which you are updating from a file
which is constantly changing. In the more general case, where you just want
the buffer to go back to where it was at before you started making changes,
i.e. re-read (or even re-load) the file, it is reverting. I'd agree that in
hindsight, reread (or maybe re-load) may have been better, but ....

I won't ask you what you think of apropos :-)

Tim



-- 
tcross (at) rapttech dot com dot au

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

[David Hansen]

On Mon, 24 Sep 2007 00:09:01 -0400 Stefan Monnier wrote:

> it doesn't even have key bindings to "go the next page" or "go back to
> the previous page" ("previous" as in "the page before this one in the
> book, not in my browse-history").

Emacs-w3m honors the `rel="(next|prev)"' attribute and has the ability to
add special rules for single sites.  SPC or DEL at the end/beginning of
a page just follows these links.

David

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

[Tom Horsley]

On Sun, 23 Sep 2007 22:31:25 +0200, David Kastrup wrote:

>> I've always wished each emacs release would come with a doc file
>> mentioning each new feature and giving the lisp code to add to your
>> .emacs file to put it back the way it was in the previous release.
> 
> f1 C-n

Yea, I been there. It can be helpful, but doesn't often go
into detail on how to disable the new features, it mostly
just mentions what they are. Going through the ones I have
found, I see comint-scroll-show-maximum-output isn't mentioned
in NEWS, yet I had to set it to make shell mode buffers behave
sanely again. It does mention mouse-highlight, but doesn't
mention that comint mode enables it it various annoying ways,
so getting it turned off was a bit of a hassle requiring a
new comint-mode-hook. It mentions grep highlighting, but
turning it off was another challenge involving not only
highlight settings, but diddling the arguments it passes
to grep. I've been able to win the death struggle eventually
most of the time, but it sometimes seems like playing
a computer game :-).

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

[Sean Sieger]

   With respect to revert - I don't agree it is just plain wrong. It only
   seems wrong in one context - the one in which you are updating from a file
   which is constantly changing. In the more general case, where you just want
   the buffer to go back to where it was at before you started making changes,
   i.e. re-read (or even re-load) the file, it is reverting. I'd agree that in
   hindsight, reread (or maybe re-load) may have been better, but ....

When I visited a new file and typed `-*- outline -*-' at the top of it
and saved it, I formulated that I was looking for something like
`refresh' or `reread' (yes, instead of simply, `M-x outline-mode').

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

[Eli Zaretskii]

> From: Tom Horsley <tomhorsley@comcast.net>
> Date: Mon, 24 Sep 2007 05:51:21 -0500
> 
> > f1 C-n
> 
> Yea, I been there. It can be helpful, but doesn't often go
> into detail on how to disable the new features, it mostly
> just mentions what they are. Going through the ones I have
> found, I see comint-scroll-show-maximum-output isn't mentioned
> in NEWS, yet I had to set it to make shell mode buffers behave
> sanely again. It does mention mouse-highlight, but doesn't
> mention that comint mode enables it it various annoying ways,
> so getting it turned off was a bit of a hassle requiring a
> new comint-mode-hook. It mentions grep highlighting, but
> turning it off was another challenge involving not only
> highlight settings, but diddling the arguments it passes
> to grep.

Obviously, entries added to NEWS need more attention and QA to make
sure each change in the defaults is accompanied by some info how to
revert to the old behavior.  Volunteers are welcome to step forward
and take upon themselves to do that job.

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Mon, 24 Sep 2007 00:09:01 -0400
> 
> > Yes, another index, presuming familiarity with the oddities of texinfo.
> > Eli tells me that it is the official policy of gnu.  I find that archaic.
> 
> Maybe it's archaic to you, but I still haven't found any system available to
> me that comes even close in terms of indexing.

And on top of that, I really fail to understand what is it with people
who need the new-and-shining latest-and-greatest, even if the oldies
are doing their job well.  Maybe I'm archaic myself...

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

[Emre Sahin]

Just another note about documentation:

Yesterday I convinced myself that removing the "Mail" notification in
the mode line will help for less distraction. I started by checking
the documentation with C-h d, C-h a, C-h v and C-h P with words like
"mail", "display", "notification" etc. My intention was to find some
variable that says Emacs "don't show this mail thing."

I couldn't find anything exactly I wanted, but I thought I found some
way. Changing (poorly documented)
mail-source-report-new-mail-interval and mail-source-idle-time-delay
variables should to the trick. 

But they didn't, and I quit searching for a solution. 

Then, today, when I was changing the face for mode line from
*Customize Group: Mode Line Faces*, I saw something like "Display Time
Mail Face" which is reported to change the display of
"display-time-mail-string" variable. I C-h v'd it, and voila!

Maybe I missed it, maybe Emacs, but somehow I wasn't able to figure
out how to change this by searching documentation. (BTW, I learned
quite a bit by searching, for example I was not aware of a "typing
break mode" for Emacs.) However, I don't think there is a silver
bullet solution, like changing the format or adding a "search all
documentation" function for this problem. I didn't think that mail
notification has something to do with time display and there will
always be cases like this in every software package IMHO. (And Emacs
documentation is the most comprehensive and usable one I've ever
used.)

Best, 

E.

-- 

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

[Bastien]

Emre Sahin <iesahin@bilkent.edu.tr> writes:

> Then, today, when I was changing the face for mode line from *Customize
> Group: Mode Line Faces*, I saw something like "Display Time Mail Face"
> which is reported to change the display of "display-time-mail-string"
> variable. I C-h v'd it, and voila!

I've been (unsuccessfully) looking for this yesterday -- thanks :)

-- 
Bastien

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

[Eli Zaretskii]

> From: Emre Sahin <iesahin@bilkent.edu.tr>
> Date: Tue, 25 Sep 2007 01:41:04 +0300
> 
> Yesterday I convinced myself that removing the "Mail" notification in
> the mode line will help for less distraction. I started by checking
> the documentation with C-h d, C-h a, C-h v and C-h P with words like
> "mail", "display", "notification" etc. My intention was to find some
> variable that says Emacs "don't show this mail thing."

It looks like your keywords should have picked the variable, because
its name contains both "mail" and "display".  Can you try to elaborate
why you didn't find it, and what commands did you use to search?

> However, I don't think there is a silver bullet solution, like
> changing the format or adding a "search all documentation" function
> for this problem.

Sometimes there are variables or functions whose name includes common
words, and therefore searching for them brings up a lot of false hits,
and you need a certain degree of persistence to not give up too early.

In any case, personally, if a few search commands don't give me what I
want, I simply look in the sources of the relevant package.  I find
this very efficient, since some variables/functions are simply too
obscure to be in the docs.

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

[David Kastrup]

Bastien <bzg@altern.org> writes:

> Emre Sahin <iesahin@bilkent.edu.tr> writes:
>
>> Then, today, when I was changing the face for mode line from *Customize
>> Group: Mode Line Faces*, I saw something like "Display Time Mail Face"
>> which is reported to change the display of "display-time-mail-string"
>> variable. I C-h v'd it, and voila!
>
> I've been (unsuccessfully) looking for this yesterday -- thanks :)

I am always surprised by people who apparently copy random junk from
some third party source into their Emacs startup file, then complain
that they find themselves unable to get rid of its effects.

Ask the person which you got the stuff from, if all else fails.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

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

[Bastien]

David Kastrup <dak@gnu.org> writes:

> Bastien <bzg@altern.org> writes:
>
>> Emre Sahin <iesahin@bilkent.edu.tr> writes:
>>
>>> Then, today, when I was changing the face for mode line from *Customize
>>> Group: Mode Line Faces*, I saw something like "Display Time Mail Face"
>>> which is reported to change the display of "display-time-mail-string"
>>> variable. I C-h v'd it, and voila!
>>
>> I've been (unsuccessfully) looking for this yesterday -- thanks :)
>
> I am always surprised by people who apparently copy random junk from
> some third party source into their Emacs startup file, then complain
> that they find themselves unable to get rid of its effects.

I guess your not targetting this at Emre/me?  I was just telling Emre
that the very name of the variable `display-time-mail-string' was what
I was looking for.

> Ask the person which you got the stuff from, if all else fails.

Very true. Add a source (if possible the e-mail address of the person
who pointed to the code) and some kind of rationale for every piece of
code you insert in your startup file. Wise advice.

Regards,

-- 
Bastien

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

[Tim X]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Tom Tromey <tromey@redhat.com>
>> Date: Sun, 23 Sep 2007 10:14:04 -0600
>> 
>> The fundamental discoverability problem with Emacs isn't that the
>> documentation is missing -- it never is.  The problem is, if you want
>> to find something by keyword, first you must guess the keyword that
>> the original author used.
>> 
>> I don't know a good way to solve this problem.
>
> Well, we could add a feature whereby documentation search commands
> will suggest to look for alternative keywords.  This feature could use
> a database of synonyms for computer-related terminology, as well as
> popular alternatives for certain Emacs parlance (such as "yank" etc.).
>
> This way, if you didn't find what you wanted, you'd be presented with
> a list of additional words or phrases to search for.
>

I think this is a good idea. What strikes me about all of this is that most
of the terminology people find difficult is actually due to the evolving
nature of language. For example, cut and paste are the common terms and
many find 'yank' odd. However, back when I started, 'yank' was more common.

Tim


-- 
tcross (at) rapttech dot com dot au

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

[Tim X]

Tom Horsley <tomhorsley@comcast.net> writes:

> On Thu, 20 Sep 2007 11:22:15 -0700, Bruce Korb wrote:
>
>> OK.  I've vented now.  Would someone please be kind enough to tell me
>> how to shut down the novice stuff completely?  Thank you.
>
> I have similar problems every emacs release. I can see an argument
> for making spiffy new features the default (else no one will notice
> them), but when one user finds a new helpful feature to be annoying
> rather than helpful, it would sure be nice if there were a standard
> way to get back the old behavior.
>
> I've always wished each emacs release would come with a doc file
> mentioning each new feature and giving the lisp code to add to
> your .emacs file to put it back the way it was in the previous
> release. (Of course even that might not help much if the new
> behavior is merely some annoying visual, you may not know the
> correct jargon to search for in the file to figure out how to
> turn it off, but you could always try each snippet of lisp
> till you find the one that does the trick :-).

I've found this is normally what is in the NEWS file that comes with each
new release. It tells you about user visible changes and elisp
changes. Generally, it also tells you how to get previous behavior back.

Tim

-- 
tcross (at) rapttech dot com dot au

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

[Emre Sahin]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:


    Eli> It looks like your keywords should have picked the variable,
    Eli> because its name contains both "mail" and "display".  Can you
    Eli> try to elaborate why you didn't find it, and what commands
    Eli> did you use to search?

C-h d of "display" gives about 10000 lines of text and this doesn't
report "display-time-mail-string" as a variable. C-h d of "mail" is
about 2700 lines of text and this doesn't contain it either. I used
"mode-line" to search also and I didn't understand anything from
mode-line-format variable's value, for example. (There is a format
description with signs like %a, %B, but there is no such thing in the
value, just a set of cryptic functions without any reference to mail.)

    >> However, I don't think there is a silver bullet solution, like
    >> changing the format or adding a "search all documentation"
    >> function for this problem.

    Eli> Sometimes there are variables or functions whose name
    Eli> includes common words, and therefore searching for them
    Eli> brings up a lot of false hits, and you need a certain degree
    Eli> of persistence to not give up too early.

Maybe I gave up early without checking Google, but I used apropos,
apropos-documentation and describe-variable for the keywords I can
think of. As you say, there may be too many hits and I might miss (and
I agree that I'm not a perfect user of documentation), but what I say
is that this problem is not about documentation format and such
technicalities; I think it's a result of "information explosion" and
no perfect communication between user and documentation should be
expected (as no perfect communication between people exists.) One can
only provide better tools but this won't solve the problem perfectly. 

    Eli> In any case, personally, if a few search commands don't give
    Eli> me what I want, I simply look in the sources of the relevant
    Eli> package.  I find this very efficient, since some
    Eli> variables/functions are simply too obscure to be in the docs.

You are right here, but time.el package was not a candidate for
reading in the first sight, I don't expect mail notification in my
mode line has anything to do with time. Once I learned it's about
time documentation was helpful, but without any hint I couldn't think
on my own. 

Thanks,

E.

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

[Drew Adams]

> > Then, today, when I was changing the face for mode line from *Customize
> > Group: Mode Line Faces*, I saw something like "Display Time Mail Face"
> > which is reported to change the display of "display-time-mail-string"
> > variable. I C-h v'd it, and voila!
>
> I've been (unsuccessfully) looking for this yesterday -- thanks :)
...
> C-h d of "display" gives about 10000 lines of text and this doesn't
> report "display-time-mail-string" as a variable. C-h d of "mail" is
> about 2700 lines of text and this doesn't contain it either. I used
> "mode-line" to search also and I didn't understand anything from
> mode-line-format variable's value, for example. (There is a format
> description with signs like %a, %B, but there is no such thing in the
> value, just a set of cryptic functions without any reference to mail.)
>
> Maybe I gave up early without checking Google, but I used apropos,
> apropos-documentation and describe-variable for the keywords I can
> think of. As you say, there may be too many hits and I might miss (and
> I agree that I'm not a perfect user of documentation), but what I say
> is that this problem is not about documentation format and such
> technicalities; I think it's a result of "information explosion" and
> no perfect communication between user and documentation should be
> expected (as no perfect communication between people exists.) One can
> only provide better tools but this won't solve the problem perfectly.

What you say is true. However, sometimes the information explosion can be
sufficiently tamed that you can find what you need. Tools do sometimes make
a difference.

Icicles command `icicle-doc' lets you search all doc strings (functions,
variables, faces) for matches to one or more doc strings. That's a *lot* of
doc, believe me. For example:

 M-x icicle-doc RET mail S-SPC mode line

shows all doc strings that match both `mail' and `mode line', in any order,
as completion candidates.

Choose a matching candidate to see its full description in buffer *Help*
(with the function signature or variable name and value etc.). You can also
visit each of several (or all) candidates on the fly, using `C-next' (visit
each in turn) or `C-mouse-2' (visit the ones you click).

It is fairly quick this way to find what you were looking for. In spite of
the large volume of doc searched, there are only three matches in vanilla
emacs (-Q): only three functions, variables, or faces whose doc strings
mention both `mail' and `mode line': `display-time', `display-time-mode',
and `rmail-mode'.

Why no `display-time-mail-string'? Because its doc string does not mention
`mail'. That shows the weakness of such an approach: it depends on having
doc that mentions what you're looking for. Nevertheless, using this
approach, you would have very quickly found `display-time' and
`display-time-mode', and from their doc strings you could have gotten to the
appropriate Customize group and found what you needed. It would probably
have taken you less than 5 minutes altogether to find what you were after,
and almost all of that time would have been spent looking over the Customize
group's variables to find that `display-time-mail-string' was pertinent.

No, this is not a panacea. There are several user options in Customize group
`display-time' that involve mail indication in the mode line, and none of
their doc strings mention "mode line" (too bad). The group's doc string does
mention it, but the individual options in the group do not. When this is the
case, `icicle-doc' will not get you where you want to go directly, but it
can still help get you close.

There are also three similar commands, `icicle-fundoc', `icicle-vardoc', and
`icicle-plist', for only functions, only variables, and only property lists,
respectively. They let you match against either or both the
function/variable name and its doc string or the symbol name and its
property list keys and values. This is important because sometimes the name
itself carries information that the doc string does not. In particular, a
function, variable, or symbol name often indicates the operation or type of
object acted upon, and that can cut down considerably on what doc is
searched.

http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Multi-Completions

There are also Icicles versions of the standard `apropos' commands, which
let you access the list of matches as completion candidates:

http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Help_on_Candidates#OtherApro
posCommands

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

[Eli Zaretskii]

> From: Emre Sahin <iesahin@bilkent.edu.tr>
> Date: Tue, 25 Sep 2007 14:06:19 +0300
> 
> >>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:
> 
> 
>     Eli> It looks like your keywords should have picked the variable,
>     Eli> because its name contains both "mail" and "display".  Can you
>     Eli> try to elaborate why you didn't find it, and what commands
>     Eli> did you use to search?
> 
> C-h d of "display" gives about 10000 lines of text and this doesn't
> report "display-time-mail-string" as a variable. C-h d of "mail" is
> about 2700 lines of text and this doesn't contain it either.

I just tried "M-x apropos RET mail display notification RET" (all 3
words were cited by you in your original message) and got 140 lines
with display-time-mail-string quite close to the beginning.  Perhaps
you should use "M-x apropos" with a list of pertinent words more
frequently?

>     Eli> In any case, personally, if a few search commands don't give
>     Eli> me what I want, I simply look in the sources of the relevant
>     Eli> package.  I find this very efficient, since some
>     Eli> variables/functions are simply too obscure to be in the docs.
> 
> You are right here, but time.el package was not a candidate for
> reading in the first sight, I don't expect mail notification in my
> mode line has anything to do with time.

??? You mean, you didn't know that both time and the mail notification
are produced by "M-x display-time RET"?  That is, you turned on this
feature in your .emacs without knowing what you are doing?  How did
that happen?

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 25 Sep 2007 08:47:58 -0700
> Cc: help-gnu-emacs@gnu.org
> 
>  M-x icicle-doc RET mail S-SPC mode line
> 
> shows all doc strings that match both `mail' and `mode line', in any order,
> as completion candidates.

So does "M-x apropos", which is part of Emacs.

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

[Drew Adams]

> >  M-x icicle-doc RET mail S-SPC mode line
> >
> > shows all doc strings that match both `mail' and `mode line',
> > in any order, as completion candidates.
>
> So does "M-x apropos", which is part of Emacs.

Not at all the same (`apropos' does not even use completion, of any kind).
Likewise all the other vanilla Emacs `apropos-*' commands. Read the rest of
the behavior I described (no need to repeat it). If you still don't
understand the difference, read the doc I pointed to. There is no relation
here to what you get in vanilla Emacs.

Had vanilla Emacs been able to do what I described (or equivalent, with
equivalent ease), I would have pointed to vanilla Emacs.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 25 Sep 2007 14:46:49 -0700
> 
> > >  M-x icicle-doc RET mail S-SPC mode line
> > >
> > > shows all doc strings that match both `mail' and `mode line',
> > > in any order, as completion candidates.
> >
> > So does "M-x apropos", which is part of Emacs.
> 
> Not at all the same (`apropos' does not even use completion, of any kind).
> Likewise all the other vanilla Emacs `apropos-*' commands. Read the rest of
> the behavior I described (no need to repeat it). If you still don't
> understand the difference, read the doc I pointed to. There is no relation
> here to what you get in vanilla Emacs.

I thought we were talking about searching the doc, not about
completion.  If completion makes a big difference, how about adding
this feature to Emacs?

> Had vanilla Emacs been able to do what I described (or equivalent, with
> equivalent ease), I would have pointed to vanilla Emacs.

IMO, we ridicule ourselves if we send users to unbundled packages for
documentation commands, especially when the user, like the OP, wants
to locate a feature that is part of the official package.  Emacs is a
self-documenting program, so every useful feature related to
documentation should be an integral part of it.

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

[Drew Adams]

> > > >  M-x icicle-doc RET mail S-SPC mode line
> > > >
> > > > shows all doc strings that match both `mail' and `mode line',
> > > > in any order, as completion candidates.
> > >
> > > So does "M-x apropos", which is part of Emacs.
> >
> > Not at all the same (`apropos' does not even use completion, of
> > any kind). Likewise all the other vanilla Emacs `apropos-*'
> > commands. Read the rest of the behavior I described (no need to
> > repeat it). If you still don't understand the difference, read
> > the doc I pointed to. There is no relation here to what you get
> > in vanilla Emacs.
>
> I thought we were talking about searching the doc, not about
> completion.

My statement that you replied to talked about completion. Even if you forget
about completion, `apropos' will _not_ show you all doc strings that match
both `mail' and `mode line', in any order. Neither will
`apropos-documentation' nor any other Emacs `apropos-*' command.

I mentioned a particular search interface that uses matching of doc strings
as completion candidates and lets you access the doc of any number of
candidates on the fly. You said that `apropros' does the same thing. It does
not, starting with the completion. But even disregarding completion, it does
not do the same thing; it simply does not give you the same
result/power/behavior.

> If completion makes a big difference, how about adding
> this feature to Emacs?

I tried, as you might remember.

It's not just "completion" as it is known in vanilla Emacs; it's a set of
features related to completion. Icicles exploits input completion, using it
as a way to dynamically define and manipulate sets (that match your input).
Emacs does that in a limited way; Icicles pushes the limits in this regard.

> > Had vanilla Emacs been able to do what I described (or equivalent, with
> > equivalent ease), I would have pointed to vanilla Emacs.
>
> IMO, we ridicule ourselves if we send users to unbundled packages for
> documentation commands, especially when the user, like the OP, wants
> to locate a feature that is part of the official package.  Emacs is a
> self-documenting program, so every useful feature related to
> documentation should be an integral part of it.

I didn't ridicule anyone, including myself. I'm pretty sure that Icicles
users regard the features that Icicles offers to easily
examine/search/explore vanilla Emacs help as some of the Icicles features
they use the most. There is no contradiction. Icicles helps you use Emacs -
including using Emacs help. No need for anyone to feel ridiculous. Enjoy.

Vanilla Emacs help is very good; no question about it. That does not mean
that it is always easy to find everything, or that improvements cannot be
made. Icicles helps you use Emacs help. I gave one example; many more are
described in the doc. Here is an overview:
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Nutshell_View.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Wed, 26 Sep 2007 07:47:01 -0700
> 
> Vanilla Emacs help is very good; no question about it. That does not mean
> that it is always easy to find everything, or that improvements cannot be
> made.

It is my firm belief that any significant improvements to Emacs help
system should be part of Emacs.  If you don't think so, we will have
to agree to disagree.

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

[Drew Adams]

> > Vanilla Emacs help is very good; no question about it. That
> > does not mean that it is always easy to find everything, or
> > that improvements cannot be made.
> 
> It is my firm belief that any significant improvements to Emacs help
> system should be part of Emacs.  If you don't think so, we will have
> to agree to disagree.

I agree, they should.

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

[Bruce Korb]

This addition:  (setq disabled-command-function nil)
seemed reasonable.  It isn't quite a complete cover tho:

> The local variables list in configure.in
> contains values that may not be safe (*).
> 
> Do you want to apply it?  You can type
> y  -- to apply the local variables list.
> n  -- to ignore the local variables list.
> !  -- to apply the local variables list, and permanently mark these
>       values (*) as safe (in the future, they will be set automatically.)
>
>     mode : autoconf-mode
>     indent-tabs-mode : nil
>     sh-indentation : 2

OK, so I've made it permanent so ``sh-indentation 2''
will no longer be treated with suspicion.  The *NEXT*
suspicious thing will interrupt me again, however.
I think that this:

 '(safe-local-variable-values (quote ((sh-indentation . 2))))

should be *ENTIRELY* disabled, not just the one "sh-indentation"
entry.  I don't exactly know who thinks I need protection from
nefarious things like two-space indentation, but the reason I
had that assignment is because I wanted that assignment in there.

> There was never such a user setting in Emacs.  You always had to  
> enable each command individually (unless you are an advanced user and  
> know how to set a function to nil without causing damage). 

The problem, of course, are the newly added protections with
less-than-obvious ways of telling emacs, "Please stop protecting
me."  In the case above, it is not a disabled command issue.
It is some collection of variable values that someone thought
would be "dangerous".  So, I guess, in the end, I'm asking for
an enhancement:

 (custom-set-variables
    '(protective-mode nil))

and from that day forth, never worry about emacs protecting me
from myself ever again.  :-}  Thank you!  Cheers - Bruce

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

[Tim X]

Bruce Korb <Bruce.Korb@gmail.com> writes:

> This addition:  (setq disabled-command-function nil)
> seemed reasonable.  It isn't quite a complete cover tho:
>
>> The local variables list in configure.in
>> contains values that may not be safe (*).
>> 
>> Do you want to apply it?  You can type
>> y  -- to apply the local variables list.
>> n  -- to ignore the local variables list.
>> !  -- to apply the local variables list, and permanently mark these
>>       values (*) as safe (in the future, they will be set automatically.)
>>
>>     mode : autoconf-mode
>>     indent-tabs-mode : nil
>>     sh-indentation : 2
>
> OK, so I've made it permanent so ``sh-indentation 2''
> will no longer be treated with suspicion.  The *NEXT*
> suspicious thing will interrupt me again, however.
> I think that this:
>
>  '(safe-local-variable-values (quote ((sh-indentation . 2))))
>
> should be *ENTIRELY* disabled, not just the one "sh-indentation"
> entry.  I don't exactly know who thinks I need protection from
> nefarious things like two-space indentation, but the reason I
> had that assignment is because I wanted that assignment in there.
>
>> There was never such a user setting in Emacs.  You always had to  
>> enable each command individually (unless you are an advanced user and  
>> know how to set a function to nil without causing damage). 
>
> The problem, of course, are the newly added protections with
> less-than-obvious ways of telling emacs, "Please stop protecting
> me."  In the case above, it is not a disabled command issue.
> It is some collection of variable values that someone thought
> would be "dangerous".  So, I guess, in the end, I'm asking for
> an enhancement:
>
>  (custom-set-variables
>     '(protective-mode nil))
>
> and from that day forth, never worry about emacs protecting me
> from myself ever again.  :-}  Thank you!  Cheers - Bruce
>
>

I think it is resonable to request such a feature and recommend you send
such a request to the emacs-devel list. 

However, it should be explicitly noted that -

1. This is not a new feature. This protection was included in emacs 21 and
I think emacs 20. 

2. The reason isn't so much to protect you from yourself, but protect you
from the malicious aims of others. Theoretically, someone could put a very
malicious (even virus/trojan like) bit of code in the local variables
section of a file. Opening that file in your emacs would cause this to be
executed and could have some nasty or unexpected consequences. 

However, I think as long as the user has to actively disable
checking/verification, it is reasonable to allow such an option. I don't
like software that tries to be too much of a Nanny - if I want to do
something stupid, I should be allowed to!

Tim

-- 
tcross (at) rapttech dot com dot au

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

[Stefan Monnier]

> It is some collection of variable values that someone thought
> would be "dangerous".

Nobody thought it would be dangerous: instead, nobody thought about stating
that it is *not* dangerous.  In the absence of any info either way, Emacs
says "since it may be safe but it may also be dangerous, let's not take any
risk and ask the user".

> So, I guess, in the end, I'm asking for an enhancement:

Check `enable-local-variables'.  And since you're of the optimistic kind,
check `enable-local-eval' as well.


        Stefan

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

[David Combs]

In article <853ax5nx23.fsf@lola.goethe.zz>, David Kastrup  <dak@gnu.org> wrote:
>Tom Tromey <tromey@redhat.com> writes:
>
>> The fundamental discoverability problem with Emacs isn't that the
>> documentation is missing -- it never is.  The problem is, if you want
>> to find something by keyword, first you must guess the keyword that
>> the original author used.
>
>Help/Search Documentation/Emacs Terminology

what's the url for that, assuming it's a web page (as seems
to the post following yours (now after this one?).

Thanks!

David


>
>-- 
>David Kastrup, Kriemhildstr. 15, 44793 Bochum

AH HA! it's a MENU item! Re: My emacs was upgraded and I am a novice again

[David Combs]

In article <85myvdre11.fsf@lola.goethe.zz>, David Kastrup  <dak@gnu.org> wrote:
>"Dave Pawson" <dave.pawson@gmail.com> writes:
>
>> On 23/09/2007, Tim X <timx@nospam.dev.null> wrote:
>>
>>> So  Dave, guess what, my advice .....RTFM!
>>
>>
>> No Tim, I'd never found either of those indices.
>
>Then perhaps it would be time to get acquainted with the documentation
>system of Emacs.  Use the menu Help/Search Documentation/Look up
>Subject in User Manual and type "revert" into it.  Or use Help/Search
>Documentation/Emacs Terminology and type "revert".
>
>If you have not found the information, it is because you did not even
>think of asking Emacs for it.  The "Help" menu is there for a purpose.
>
>> Yes, another index, presuming familiarity with the oddities of
>> texinfo.  Eli tells me that it is the official policy of gnu. I find
>> that archaic.
>
>A working fast and efficient tool that is easy to use is not lightly
>replaced.  Hammers might be archaic tools, but they still do the job
>of driving nails.
>
>> http://savannah.gnu.org/search/index.php?type_of_search=soft&words=%%%
>> there isn't even a general gnu documentation list, seems that
>> texinfo is a given and not open to a challenge.
>
>There is no working challenge around.  HTML does not contain useful
>indexing and structuring information.
>
>-- 
>David Kastrup, Kriemhildstr. 15, 44793 Bochum