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

[Joerg Fischer]

Offer Kaye wrote:

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

I think improving the docs is a process of small steps. Overall,
NEdit's documentation is quite complete.

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

Yes, but the ARs that change the preferences (#2) where added in
version 5.1 or so, ie much later then #1 and #3 and my guess is that
their documentation was put in between there w/o anything special in
mind.  
I don't really know how the division between Menu Commands and
Keyboard-only came into being, but as it seems such a division can't
really work out, even when renaming them like you propose, because
there are lots of editing routines in the Menu (paste, upper/lowercase, 
replacing).

>On the other hand, you could make the case to completely change the
>current representation. 

Well, my idea so far is that documenting the Menu as such is a good
thing - sort of visually underlining that all tasks or actions nedit
can perform are represented as ARs, so clicking on a menu entry does
nothing but to invoke some AR, as listed there.

Now I'm looking for a sensible way to divide the ARs into groups, as
I don't know if a large alphabetical list is the right way to go.
One group can be the ARs setting preferences (also all starting with
set_... ).  But Menu Commands wouldn't be a group as such, I would
just let the table in.

>For example, you could have all ARs in one large list (maybe in
>alphabetical order), with arguments, matching menu-command (if
>relevant), return values,

ARs can't have return values.  Macro subroutines can have return
values, but they can't be invoked from translation table entries,
only indirectly via the AR macro_menu_command() (which isn't really
documented).

>and perhaps even a little usage example. 

In some cases this is missing.  I don't recall how I learned about
macro_menu_command(), but not from the docs.

>You could still have an initial section which lists the ARs by type
>(menu, cursor, editing, etc.). 

Yes, since 5.3 we can have links in the docs (with certain
limitations.)

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

My guess is this was done because the docs should be as short as
possible.  This could also be the reason for the
Actions-Representing-Menu-Commands thing.  It's kind of
self-documenting, isn't it.  You can find out what the menu command
does by clicking on it, so you know what the action behind the menu
command does, so no need to say more about it, except for ARs that
can also take some arguments...

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

No, not from a macro.  Left click (ie, the X event
~Shift~Alt~Meta~Ctrl<Btn1Down>) is bound to grab_focus() and
clicking 3 times in a row selects a line.  grab_focus() as single
line macro just moves the cursor, but not to the mouse pointer...

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

It uses lots of X terminology, whereby beginners don't even know
about secondary selections.  If one doesn't know about X, one can't
understand the text, that's true.  On the other hand, this is
another example of an AR that can't be used in a macro, can't even
be used for key events but only for the mouse, and one must be much
more than a beginner if one changes NEdit's complex mouse settings.

Cheers,
Jörg