Re: keys and command name info

From: Andreas Burtzlaff <andy13@gmx.net>
To: Carsten Dominik <carsten.dominik@gmail.com>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>
Subject: Re: keys and command name info
Date: Mon, 09 Aug 2010 11:37:28 +0200	[thread overview]
Message-ID: <87fwyom8iv.fsf@gmx.net> (raw)
In-Reply-To: <770A61DC-4063-4A72-95F2-21F4E7DE6E77@gmail.com> (Carsten Dominik's message of "Mon, 9 Aug 2010 08:43:21 +0200")

Carsten Dominik <carsten.dominik@gmail.com> writes:

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

Having the function names in the manual at all makes it look a bit
overloaded and might lose us a couple of newbies, I think. Personally, I
would not have use for it.

If the names are included in the manual I strongly object to them being
at the beginning of the first sentence. The fixed starting column of the
sentences becomes variable and that makes it hard to skim through for
those who don't want to read the function names.

What about having them in the same line as the keybinding but aligned to
the right?

`C-c ['                                         org-agenda-file-to-front
     Add current file to the list of agenda files.  The file is added to
     the front of the list.  If it was already in the list, it is moved
     to the front.  With prefix arg, file is added/moved to the end.

It would make the manual longer, but at least it looks clean.
It is easy to neglect the function names if one wants, and just as easy
to skim through them.

Andreas

>
> Thanks to Andreas for his work so far, and please, let me
> hear more opinions.
>
> - Carsten
>
>
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode