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

[Tim Hubberstey]

On or about 2007-05-31 12:58, Offer Kaye is reputed to have said:
> 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:

[massive snip]

I have 3 big problems with the documentation.

1. The sections seem somewhat haphazard.
2. There is no index. Search capability is better than nothing but a 
proper index is far superior.
3. There is no quick reference table to allow the experienced user to 
get a "refresh" on what arguments a particular function takes.

<Warning! Strong opinions follow, activate "jerk-tolerance filter">

Further on (1):
o why are "Action Routines" and "Macro Subroutines" in separate, and 
widely separated, sections?
  - They should all be part of the same section, with sub-headings if 
needed.

o Why is "Auto/Smart Indent" under "Features for Programming" while 
"Highlighting Patterns" and "Smart Indent Macros" are under "Customizing"?
  -"Auto/Smart Indent", "Highlighting Patterns" and "Smart Indent 
Macros" should all be grouped under "Features for Programming" while 
"Customizing" should be renamed "GUI Customizing".

Further on (3):
Almost every Programmers' Reference I've seen has a section where all 
built-in functions are listed, usually one to a line, along with their 
arguments and data types. A very short description is sometimes included.

I have personally spent hours mucking about in the help sections trying 
to find things. The documentation has improved quite a bit since I 
started using NEdit in 1995 but it still has a ways to go.

One additional feature I'd like to see is a tool (either built-in or 
external) to output the help structure as an HTML file for use with an 
external browser. The help browser currently does most of what a simple 
HTML file would need so I suspect it shouldn't be a big effort. But hey, 
I'm not that kind of programmer so I may not know what I'm talking about. :)

In any case, even with all its flaws, NEdit is still the best all-round 
editor I've found. Believe me when I say this because I go through 
significant pain to get and maintain *nix under Windows just so I can 
run NEdit. One of these days I may try Micro$haft's Services For Unix 
instead of Cygwin.

If someone were to point me at a description of the data format of the 
help section, I just might find time to implement that Help to HTML utility.

Later,
Tim
-- 
Tim Hubberstey, P.Eng. . . . . . Hardware/Software Consulting Engineer
Marmot Engineering . . . . . . .  VHDL, ASICs, FPGAs, embedded systems
Vancouver, BC, Canada  . . . . . . . . . . . http://www.marmot-eng.com