Comments on: Small change, better HELP.
Yesterday, I noticed a ticket in CureCode (for R3) that the embedded help system should do a better job helping users. This morning I woke up much too early, and that comment was still on my mind.
IMHO, better help helps all of us -- beginners and experts -- and it does not take much effort.
Since I was obviously awake in the Iceland timezone, I wrote a quick modification to help for something long needed, long wanted: search all embedded help strings and values (not just words).
As you know, help will broaden a search if you use quotes.
Compare:
>> help insert
USAGE:
INSERT series value /part range /only /dup count
DESCRIPTION:
Inserts a value into a series and returns the series after the insert.
INSERT is an action value.
with:
>> help "insert"
Found these words:
insert action! Inserts a value into a series and returns the
It looks for all words that contain "insert". Not much found. What about a function like append the shortcut for insert at tail? It's not listed.
A few lines of REBOL code in R3 made the search a lot better. Now, here's what you see:
>> help "insert"
Found these words:
append action! Inserts a value at tail of series and returns...
collect function! Evaluates a block, storing values via KEEP fu...
compose native! Evaluates a block of expressions, only evalua...
extract function! Extracts a value from a series at regular int...
insert action! Inserts into a series and returns the series ...
reword function! Substitutes values into a template string, re...
That looks a lot better.
Another test:
>> help "remove"
Found these words:
alter function! If a value is not found in a series, append i...
clear action! Removes all values from the current index to ...
input function! Inputs a string from the console. New-line ch...
remove action! Removes value(s) from a series and returns af...
remove-each native! Removes values for each block that returns tr...
take action! Copies and removes from series. (Modifies)
trim action! Removes space from a string or NONE from a bl...
undirize function! Returns a copy of the path with any trailing ...
unhandle-events function! Removes a handler from the view event system.
unique native! Returns the data set with duplicates removed.
So, now we're seeing many more functions that remove from a series.
Functions like clear, take, and trim are good to know.
So, let's try a non-function name:
>> help "series"
(long list of series related functions)
>> help "series!"
(smaller list of the main series functions)
Useful.
Oh, and while I was there I added:
help/doc insert
The /doc refinement means open my web browser to that documentation page. Simple stuff, but a time saver.
Very good. These changes will be included in R3-A39. I hope you find them useful.
Next it would be nice to search by argument datatypes. For example, show me all functions that accept a string argument. If you've got some clean tight code for that, send it to me!
11 Comments Comments:
Paul
25-Mar-2009 16:04:56 |
Great additions, Carl! | Edoc
25-Mar-2009 16:21:34 |
Bravo on these enhancements, especially help/doc | Carl Read
25-Mar-2009 22:07:45 |
What about accepting a block as a way of reducing the list when you get too many results? ie, if there's two strings in the block, both need to be in the hits for a word before it'd be shown. | onetom
26-Mar-2009 11:21:52 |
+1 for the implicit AND operator, BUT we can wait with that to see if we really need it or not..
| Carl Sassenrath
26-Mar-2009 15:54:23 |
A39 just released, so give this HELP change a try.
CR: Block idea is interesting.
Before we'd decide on it, we have to ask: what other purpose could there be in supplying a block to help? [... thinking-cap starts to buzz...]
| EyeAm
26-Mar-2009 20:31:54 |
Carl, are you working with Amiga Inc. on Amiga OS 5.0? Or on an Amiga OS for x86-64 CPUs? | -pekr-
26-Mar-2009 21:57:23 |
Although I mentioned it already on rebdev, I'll put my comment even here:
help/dialect vid button
... or any other refinement name, to allow provide help for custom dialects, modules, etc. | Dave Cope
27-Mar-2009 5:12:43 |
The additions to HELP look really useful. I would like to see something like this;
help/file my-func %my-func.txt
to dump the documentation of my-func to a file so I can go on to produce documentation. Maybe the output could be switched to makedoc format too (or maybe that is the default);
help/file/makedoc my-func %my-func.mdoc
| Ratio
29-Mar-2009 18:58:09 |
In real life a scientist, I spend, since decades, my spare time in logic programming. I like that. I created relational databases on nothing else than assembler level -- and so on.
I am always open for new ideas and helpful functions. Saw, tried and used a lot.
But I mostly felt with these new creations very bad and from year to year even worse.
Found no good ideas at all, only totally absurd complications.
Clear and simple ideas seem to be very difficult and strange for most of us.
To achieve a level of clear thinking is not easy, indeed.
----------------------
What Carl gracefully calls 'complexities' is, in my opinion. just a mess.
I never saw anywhere a system like REBOL doing the same sophitisticated things I am since decades struggling to achieve, in my banking/accounting application.
I can't help it: Carl is a worldwide outstanding man of genius !
Ratio
| adrians
1-Apr-2009 21:38:55 |
The examples in the browser documentation are very helpful in making clear the sometimes terse descriptions given by the specs. It would be pretty nice if there was a centrally stored (wiki?) and possibly user maintained list of function examples, keyed to function names.
An added refinement to the help function could retrieve these and present them nicely formatted in the console. Accessing the examples like this would not add any memory overhead since the examples would be retrieved on-the-fly.
A possible evolution to this could be the retrieval and possible execution of reblets that could demonstrate the use of a function in more detail than a typical one line example would. Another could be to return as examples scripts from the REBOL script library which have been appropriately tagged.
Of course, this kind of functionality is already available in the browser or could be nicely implemented in a GUI app, but it would be good to be able to work from the console and have all of this available (esp. in environments where the console is all you have). | EricB
13-May-2009 15:04:20 |
Anyone interested in continuing any AmigaOS development should be prepared to wade in this legal swamp:
arstechnica.com/old/content/2007/12/under-the-shadow-of-lawsuits-amiga-development-goes-on.ars ;
and
arstechnica.com/software/news/2008/09/amigaos41-ars.ars .
Also: legal briefs filed (some 127, so far!):
dockets.justia.com/docket/court-wawdce/case_no-2:2007cv00631/case_id-143245/
Personally, I have for a long time, dreamed of what it would _REALLY_ take to succeed: nailing a couple big trends in the futures markets; putting up about $20M; buying all these charlatans out; and taking it to x86 silicon.
Those who still yearn to see a viable AmigaOS-based computer must consider well, the necessity of implementing these steps. Anything else is mere nostalgic 'pipe dreams'.
|
Post a Comment:
You can post a comment here. Keep it on-topic.
|
