Help with the docs [was Re: Curious about next version ...]

[Offer Kaye]

On 5/30/07, Joerg Fischer wrote:
>
> IMO an older problem is the whole section about the action routines
> (Help -> Macro/Shell Extensions -> Action Routines). Problems I see
> there are:
>

Okay, in my humble opinion, things aren't that bad :)
I'm glad this is called the "NEdit *discussion* list", as we obviously
have things to discuss. We can make small changes and still make the
text much clearer, or large ones if you really feel the need.

>     - an unclear structure,

As I understand it, the Action Routines (I'll call them ARs for short
from now on, or Actions, as the text does) listed divide into 3 main
parts:
1. Those following the Menu Commands
2. Those relating to screen/display settings
3. Those relating to cursor movement and editing routines

I agree the current section names could be made clearer/more exact,
and I think a little Table of Contents with more introductory text
could help, but the current scheme of separating the ARs into the 3
sections seems to make sense to me, especially as people tend to think
in terms like "I want to run this menu command from my macro" or "I
want to move the cursor so-and-so".
On the other hand, you could make the case to completely change the
current representation. It all depends on how bad you think the
current scheme is and how long you want to wait for a patch from me ;)
For example, you could have all ARs in one large list (maybe in
alphabetical order), with arguments, matching menu-command (if
relevant), return values, and perhaps even a little usage example. You
could still have an initial section which lists the ARs by type (menu,
cursor, editing, etc.). For an example of what I mean, see "perldoc
perlfunc" (online at http://perldoc.perl.org/perlfunc.html).

>       "Actions Representing Menu Commands",

This is actually a good title, I think.

>       then "Menu Action Routine Arguments",

Yeah, bad. I guess the author didn't want to be too verbose, but the
end result is simply not clear. I would prefer verbose: "Arguments of
Actions Representing Menu Commands". Although to be honest, I don't
see a need for another title here. The first category is "Actions
Representing Menu Commands", with the text after the rather nice (in
my opinion) command per menu should be something like:
<blockquote>
An action representing a menu command is usually named the same as its
corresponding menu item except that all punctuation is removed, all
letters are changed to lower case, and spaces are replaced with
underscores. To present a dialog to ask the user for input, use the
actions with the `_dialog` suffix. Actions without the `_dialog`
suffix take the information from the routine's arguments. Arguments
are text strings enclosed in quotes. Below are the "Menu Commands"
Action Routines which take arguments. Optional arguments are enclosed
in [].
</blockquote>
Now you can simply follow with the arguments listing. No need for Yet
Another Heading :)

>       now "--Some notes on argument types above--"

No idea why this was done this way, but easy enough to fix - just move
each description up below the relevant entry in the Arguments list
above.

>       followed by "Window Preferences
>       Actions" pluged in the middle of somewhere and finally
>       "Keyboard-Only Actions".

How about
"Actions Related to Window Preferences"
"Actions Related to Cursor Movement and Editing"
You like?

>       Adding to this is that the actions
>       for copy, cut and paste, while clearly represented in the Edit
>       menu, are listed under the "Keyboard-Only Actions".
>

Again, simple to solve - just add an entry in the "Actions
Representing Menu Commands" section for each of these and point (link)
to the "Actions Related to Cursor Movement and Editing" section entry
for that item.

>     - The introduction says all actions can be called from both
>       macros and translation table entries. This is true, but
>       unfortunately there are some actions (grab_focus() is only one
>       of them) that make only sense when bound to a key or even a
>       mouse event. Calling them in macros doesn't give the possibly
>       expected result.
>

Then I would add this text to the intro text as a caveat.
But I'm not sure I agree. For example, you could use grab_focus() 3
times in a row to get the current line under the mouse, right? I'm not
sure *why* you would want to do this, but at least it is possible now
from a macro, no?

>     - Why are pure mouse actions like secondary_start() listed under
>       the heading "Keyboard-Only Actions"?

You get rid of this problem by changing to the title I suggested,
"Actions Related to Cursor Movement and Editing", as nowhere in the
title do I say *where* the cursor movement originated :)

>
> Hm, btw talking about it, what does "Keyboard-Only Actions" really
> mean, considering that these are *not* actions that can only be
> bound to key(board) events.

I hope my title change fixes this too?

> And "Actions Representing Menu Commands"
> are also bound to shortcuts, aren't they. So what's the difference
> between uppercase() bound to Ctrl+6 but listed under "Actions
> Repr..." and copy_clipboard() represented in the Edit menu as "Copy
> Ctrl+C" but listed under "Keyboard-Only..."?

I assume the original author wanted to list the copy_clipboard() AR
with the other copy* ARs. There's no such direct relationship between
uppercase() and the other entries in the 3rd section.
As I said, easily fixed by adding a pointer (well link in our case,
this isn't C code :)) from the entry under the Edit Menu (which we
would add now I guess) to the "Actions Related to Cursor Movement and
Editing" section entry.

Now if you're really talking about confusing text, how about that
"copy_to_or_end_drag()" description? It's a text only a mother could
love... I'm still scratching my head over what exactly it means ;)

>
> (Are you still volunteering?)
>

Do you still want me to volunteer or are you ready to throw me down a
tall mountain without a parachute? :)

I'd like to hear your feedback before making any sweeping documentation patches.

Cheers,
-- 
Offer Kaye