Re: Re: keys and command name info

[Carsten Dominik <carsten.dominik@gmail.com>]

On Aug 9, 2010, at 12:26 AM, Gregor Zattler wrote:

> Hi Carsten, org-mode developers,
> * Carsten Dominik <carsten.dominik@gmail.com> [02. Aug. 2010]:
>> I am not sure I would like such a change because I think it
>> makes the manual harder and less fluid to read and considerably  
>> longer.
>
> It makes the manual longer as in bytes/bandwidth but not as in
> lines which IMHO corresponds with the amount of time one needs to
> read the manual.
>
> If it's consistent within the manual it's IMHO not confusing or
> harder to read because it's easy to skip.
>
> To me actually this hints look like headings.  They would support
> me in skimming a section of commands in order to find the right
> one.  Those paragraphs with key sequences at the beginning are
> hard to skim because all the info which stands out is not
> relevant if one searches for a specific action.
>
> Seeing how the command is named in the context of usage
> information might help lisp novices in getting an idea why some
> solutions work the way they do.

Hi Gregor, thanks for chiming in and summarizing your arguments.
And that you say it makes it easier to find the right command
may be a good argument to insert the command names.

Some of the  original arguments, that these names would stick
more easily and that it would make it easy for a hacker to
find the command name for rebinding, these do not fly, I think.
I don't think anyone calls Org commands with M-x, and if a
hacker needs to find a command name, `C-h b' and in particular
`C-h k' are the perfect ways to get to the names.

I have put a version of the manual as modified by Andreas here:

    http://orgmode.org/org-manual-with-command-names.pdf

Not all the command names are in there, but quite a few are.
I'd like to hear from more people

- if they would like to have the names there (i.e. if it would
   help them finding a command)
- if the position (first thing in the command description)
   is right, or if it would be better to have it
      - last thing in the description
      - or after the first sentence, this is how the GNUS manual
        does it.

Thanks to Andreas for his work so far, and please, let me
hear more opinions.

- Carsten