I think the doc in emacs is too simple in someplaces

I think the doc in emacs is too simple in someplaces

[Ronald]

For example:

c-toggle-electric-state

c-toggle-electric-state is an interactive compiled Lisp function in 
`cc-cmds.el'.
It is bound to C-c C-l, <menu-bar> <C> <Toggle...> <Electric mode>.
(c-toggle-electric-state &optional ARG)

Toggle the electric indentation feature.
Optional numeric ARG, if supplied, turns on electric indentation when
positive, turns it off when negative, and just toggles it when zero or
left out.


It doesn't tell what the function does.
And the description about ARG is repeated everywhere,
I supposed it's not good.

Re: I think the doc in emacs is too simple in someplaces

[Robert D. Crawford]

Ronald <followait@163.com> writes:

> For example:
>
> c-toggle-electric-state
>
> c-toggle-electric-state is an interactive compiled Lisp function in
> cc-cmds.el'.
> It is bound to C-c C-l, <menu-bar> <C> <Toggle...> <Electric mode>.
> (c-toggle-electric-state &optional ARG)
>
> Toggle the electric indentation feature.
> Optional numeric ARG, if supplied, turns on electric indentation when
> positive, turns it off when negative, and just toggles it when zero or
> left out.
>
> It doesn't tell what the function does.

Yes it does.  It toggles the electric state.  Computers are very good at
answering the question you ask.  It is up to you to ask the right
question.  In this case, you have asked what a particular command does
and it has told you.  The next step is to ask what the electric state
does.  This information can be found in the info page for emacs.  The
place where you are looking, C-h f, will give you a place to start
looking but will not give you much information.  

Try this:

C-h i 

to get into info, then

m

and ask for emacs, then

s

to search the manual.  search for electric which will take you to a link
to the relevant section of the emacs info manual.

> 
> And the description about ARG is repeated everywhere, I supposed it's
> not good.

Not sure why you would think this.  What it means is that if you invoke
the command like so:

C-u M-x command-to-invoke

you are invoking the command with a 0 argument.  Therefore

C-u 1 M-x command 

is a positive arg and 

C-u -1 M-x command

is a negative arg.

Clearer?

> 

-- 
Robert D. Crawford                                      rdc1x@comcast.net

Linux - Das System fuer schlaue Maedchen ;)
		-- banshee

Re: I think the doc in emacs is too simple in someplaces

[Eli Zaretskii]

> From: Ronald <followait@163.com>
> Date: Mon, 18 Dec 2006 23:02:04 +0800
> 
> For example:
> 
> c-toggle-electric-state
> 
> c-toggle-electric-state is an interactive compiled Lisp function in 
> `cc-cmds.el'.
> It is bound to C-c C-l, <menu-bar> <C> <Toggle...> <Electric mode>.
> (c-toggle-electric-state &optional ARG)
> 
> Toggle the electric indentation feature.
> Optional numeric ARG, if supplied, turns on electric indentation when
> positive, turns it off when negative, and just toggles it when zero or
> left out.
> 
> 
> It doesn't tell what the function does.
> And the description about ARG is repeated everywhere,
> I supposed it's not good.

I agree, but please submit bug reports such as this one to the correct
forum; "M-x report-emacs-bug RET" will do that for you automatically.
Also, please report specifically each case of insufficient
documentation; ``for example'' is not good enough, because Emacs has
thousands of doc strings, and no one can possibly believe that all of
them are bad.

Re: I think the doc in emacs is too simple in someplaces

[Ronald]

Robert D. Crawford wrote:
> Ronald <followait@163.com> writes:
> 
>> For example:
>>
>> c-toggle-electric-state
>>
>> c-toggle-electric-state is an interactive compiled Lisp function in
>> cc-cmds.el'.
>> It is bound to C-c C-l, <menu-bar> <C> <Toggle...> <Electric mode>.
>> (c-toggle-electric-state &optional ARG)
>>
>> Toggle the electric indentation feature.
>> Optional numeric ARG, if supplied, turns on electric indentation when
>> positive, turns it off when negative, and just toggles it when zero or
>> left out.
>>
>> It doesn't tell what the function does.
> 
> Yes it does.  It toggles the electric state.  Computers are very good at
> answering the question you ask.  It is up to you to ask the right
> question.  In this case, you have asked what a particular command does
> and it has told you.  The next step is to ask what the electric state
> does.  This information can be found in the info page for emacs.  The
> place where you are looking, C-h f, will give you a place to start
> looking but will not give you much information.  
> 
> Try this:
> 
> C-h i 
> 
> to get into info, then
> 
> m
> 
> and ask for emacs, then
> 
> s
> 
> to search the manual.  search for electric which will take you to a link
> to the relevant section of the emacs info manual.
> 
Opps, after installing emacs22, C-h i reports : Recursive `require' for 
feature `sb-info'...

>> And the description about ARG is repeated everywhere, I supposed it's
>> not good.
> 
> Not sure why you would think this.  What it means is that if you invoke
> the command like so:
> 
> C-u M-x command-to-invoke
> 
> you are invoking the command with a 0 argument.  Therefore
> 
> C-u 1 M-x command 
> 
> is a positive arg and 
> 
> C-u -1 M-x command
> 
> is a negative arg.
> 
> Clearer?
> 
> 
I mean this can be true implicitly, and it's not good for maintaining. 
So any good reason?

Re: I think the doc in emacs is too simple in someplaces

[Ronald]

Eli Zaretskii wrote:
>> From: Ronald <followait@163.com>
>> Date: Mon, 18 Dec 2006 23:02:04 +0800
>>
>> For example:
>>
>> c-toggle-electric-state
>>
>> c-toggle-electric-state is an interactive compiled Lisp function in 
>> `cc-cmds.el'.
>> It is bound to C-c C-l, <menu-bar> <C> <Toggle...> <Electric mode>.
>> (c-toggle-electric-state &optional ARG)
>>
>> Toggle the electric indentation feature.
>> Optional numeric ARG, if supplied, turns on electric indentation when
>> positive, turns it off when negative, and just toggles it when zero or
>> left out.
>>
>>
>> It doesn't tell what the function does.
>> And the description about ARG is repeated everywhere,
>> I supposed it's not good.
> 
> I agree, but please submit bug reports such as this one to the correct
> forum; "M-x report-emacs-bug RET" will do that for you automatically.
> Also, please report specifically each case of insufficient
> documentation; ``for example'' is not good enough, because Emacs has
> thousands of doc strings, and no one can possibly believe that all of
> them are bad.
> 
> 
Yes, I should try.
I'm a newbie in Linux.
Thanks.

Re: I think the doc in emacs is too simple in someplaces

[Tassilo Horn]

Ronald <followait@163.com> writes:

Hi Ronald,

> Opps, after installing emacs22, C-h i reports : Recursive `require'
> for feature sb-info'...

The solution can be found here: 
 
  http://article.gmane.org/gmane.emacs.cedet/2233

Bye,
Tassilo
-- 
A morning without coffee is like something without something else.

Re: I think the doc in emacs is too simple in someplaces

[Robert D. Crawford]

Ronald <followait@163.com> writes:

> Opps, after installing emacs22, C-h i reports : Recursive `require'
> for feature `sb-info'...

Is this something that you have referenced in your .emacs file with a
'require'?  I am running emacs 22 and am having no such problems.  

If there is a possibility that this is caused by something in your
.emacs file, start emacs with the -q option to see if .emacs is the
culprit.  

>>> And the description about ARG is repeated everywhere, I supposed it's
>>> not good.
>>
>> Not sure why you would think this.  What it means is that if you invoke
>> the command like so:

[snip]

> I mean this can be true implicitly, and it's not good for
> maintaining. So any good reason?

Because this is not the case with every command.  

Maybe I misunderstand what you are trying to say.  Eli Z. seemed to
agree with you that this is a problem that needs to be brought to the
attention of the devel team, and on the basis of his activity in this
group alone he seems to be a much more knowledgeable fellow than I.

rdc
-- 
Robert D. Crawford                                      rdc1x@comcast.net

<taniwha> i'd solve a windows key problem with fdisk :)