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.
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.
I would like to see a man type of help as well ... which takes us to a wiki where we can see code examples.|
I'm missing if functions alter the input or return a new copy.|
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.|
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.
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.
Brock, that is not what action! means.|
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.|
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. :-)
Many mezz's already have the "(modifies)" annotation in them, so that's a good thing to continue IMO.|
Also, Carl, you don't have to say
You can just say
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.|
A standardised method of describing the return value would be a major improvement to help to me.
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 ""
>> help my-func
My function is great
MY-FUNC is a function value.
the-input -- Some useless input (Type: string)
anonymous -- Nothing useful (Type: logic)
the-input -- Input string is emptied
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.
It's not headspace, it's code availability.|
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.
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.