Comments on: Wanted: Help with HELP
Even as an advanced programmer, I find the help function extremely useful. Most of the time, it gets me exactly what I need.
When I am unsure of a name, I use the search feature, such as:
>> ? "line"
Found these words:
deline native! Converts string terminators to standard forma...
enline native! Converts standard string terminators to curre...
linen tuple! 250.240.230
new-line native! Sets or clears the new-line marker within a b...
new-line? native! Returns the state of the new-line marker with...
newline char! #"^/"
That's quite useful; however, there are a few small things we could do to make help even better. Some of you have made suggestions or made changes over the years... but, I'm not sure where they are posted.
Small improvements that come to mind are:
- help/all - search the specs, including comments for a match. Now I can search for "convert" and find function like the first two shown above. (I think it would be ok for it to search the molded spec for each function. Not that efficient, but this is a developer feature.)
- help/type - search for functions that accept a given datatype. For example, help/type string! to show functions that take string arguments. They could be listed by those that take string as a primary argument (in first arg position) and those that take it as a secondary argument.
It would be great if someone could make these additions and submit them via DevBase so we can get them approved and put into R3.
I'm sure there are other help ideas too... but, let's start with these and go from there depending on what we find the most worthwhile.
17 Comments Comments:
-pekr-
3-Sep-2008 1:26:58 |
I would welcome another kind of help system extension. I really like the fact, that we can use help on objects. But - with DELECT, we are going to see imo more dialects defined, and what is more, DELECT throws errors, I mean, in Gabriele's VID 3, something like "button red" throwed error, instead of ignoring 'red not supported parameter.
So, what I really miss is help system for dialects!
So I thought about possible extension of help system:
help/dialect 'vid button
We could have help/dialect 'effect, 'draw, etc., or even custom dialect. It would work like plugins, and it would be upon author, to define it.
| Graham
3-Sep-2008 1:52:26 |
I would like to see a man type of help as well ... which takes us to a wiki where we can see code examples. | Robert
3-Sep-2008 10:15:30 |
I'm missing if functions alter the input or return a new copy. | Brian Hawley
3-Sep-2008 14:21:37 |
Robert, please explain what you mean and how you intend to use your proposed functions. AltME is a good place for this kind of thing. | Brock
3-Sep-2008 14:46:34 |
I believe Robert's comment is that a function typically alters the input to a function or returns a new (copy) of the value that was passed to it. He'd like to see a section in the help that specifies that directly.
I believe Carl typically indicates that a function is an action word or something to that effect when it modifies the input to the function. | Brian Hawley
3-Sep-2008 14:49:51 |
Obvious in retrospect, thanks :)
I would like it if the term "(modifies)" was added to the doc string of every mezzanine or native that modifies its arguments, perhaps to the doc string of the particular parameter that is modified. That would be an appropriate thing for the community to do in DevBase, and we could start doing so right away. | Brian Hawley
3-Sep-2008 14:50:53 |
Brock, that is not what action! means. | Brian Hawley
3-Sep-2008 16:22:39 |
Carl, I will add your help extension. Please update mezz-help in DevBase with the current source of the mezzanines defined therein - I noticed that recent alpha builds have different code than the source in DevBase. It would improve adoption of DevBase if you would use it more yourself. | Brock
3-Sep-2008 16:59:59 |
Brian H, okay, you got me. My assumption was incorrect. It seems action means it relocates the block index after changing the contents of the block. If I've again misinterpretted this or if you have a better explanation of the term as used in help, post away. :-)
Thanks. | Gregg Irwin
3-Sep-2008 17:38:43 |
Many mezz's already have the "(modifies)" annotation in them, so that's a good thing to continue IMO. | Gregg Irwin
3-Sep-2008 17:40:18 |
Also, Carl, you don't have to say
? "line"
You can just say
? line
:) | Brian Hawley
3-Sep-2008 18:12:44 |
Functions of the action! datatype are natives that are internally looked up in a table associated with the datatype of the first argument. This is REBOL's primary means of polymorphism. Every datatype has a table of actions, though the action slots are only filled in when the action is applicable to that type. The action! functions you see are just an index into those tables that the internal action dispatcher uses. | Peter Wood
3-Sep-2008 20:10:29 |
A standardised method of describing the return value would be a major improvement to help to me.
Something like:
my-func: func ["My function is great" [
returns none "nothing useful [logic!]"
modifies the-input "Input string is emptied"
]
the-input [string!] "Some useless input"
][
the-input: copy ""
return true
]
>> help my-func
USAGE:
MY-FUNC the-input
DESCRIPTION:
My function is great
MY-FUNC is a function value.
ARGUMENTS:
the-input -- Some useless input (Type: string)
RETURNS;
anonymous -- Nothing useful (Type: logic)
MODIFIES:
the-input -- Input string is emptied
| Brian Tiffin
3-Sep-2008 21:52:06 |
Peter; I think we may find Ingo Hohmann's %help-system.r in the rebol.org library a good place to start for those features. His patch modifies [b]func[/b] to allow for the extensions; adds returns, category tagging and author.
But this brings up the whole "what - we have to contribute? Doesn't Carl do everything for us?" thing.
I fear that few of us are in the headspace of being able to influence things yet. Our good Mr Hawley seems to be a rare bird in this area. Uphill battles await. Battles that will be won, but battles nonetheless. | Kaj
5-Sep-2008 13:09:23 |
It's not headspace, it's code availability. | Brian Hawley
5-Sep-2008 13:27:12 |
Kaj, I don't have access to the code Carl is working on. All of what I say is based on what he's posted here or in AltME worlds, and all of the design discussions we have had over the last 2 years in relatively public forums. It's just memory, experience with language implementation, and deduction.
Currently released mezzanine code is a different matter - just use source. | Kaj
6-Sep-2008 17:34:38 |
Brian, I don't mean that your "headspace" is based on access to more code than we have, I mean that many of us are held back in contributing due to lack of source - and binary, for that matter. Well, a known issue. |
Post a Comment:
You can post a comment here. Keep it on-topic.
|
