World: r3wp

The typeset! type is a new addition in R3, and emulated in R2-Forward. 
TYPES-OF returns the type spec of a function in both.

I like the idea of a refinement to have HELP search, but I think 
all of the options can be collapsed into one /search refinement. 
Search for a datatype could check type specs, for a refinement could 
check for supported refinements, for a string can search doc strings, 
maybe more.


In general we prefer full words for options, particularly for user-level 
functions like HELP, so maybe /args is not the best name for this 
option - that's why I suggested /search. Please don't call the refinement 
/find or /all, because that makes the implementation of HELP incredibly 
awkward.

Believe me about the awkward: I wrote LOAD, and avoiding the use 
of the ALL function because of LOAD/all was annoying :(

BrainH: how would you solve the problem of documenting dialects? 
(having ability to query them for help?) Do you think we can plug 
it in default help? What about loaded modules, will they naturally 
extend help?

Maybe a /dialect 'name option, with installable dialect help? DELECT-style 
dialects like Draw and VID could have autogen docs too.

Module docs could be part of the Exports spec.

I commented the CureCode ticket listed above with the /search option 
variant, and marked it as reviewed.

Brian: the exact naming of any help refinements is not an issue to 
me - what you propose sounds good. How would you specify, using only 
the /search refinement, that you're interested in searching the descriptions 
of refinements? What about specifying the order of the types in the 
spec as opposed to searching without regard for the order?

I just added refinements to the comment, AdrianS. Typesets have no 
order, so the order in the spec is irrelevant.

If the /search option is OK with you, please add a comment to the 
ticket saying so, so that the developers will do that instead.

I just read your comments Brian and I'm not sure what you're suggesting 
allows for the flexibility I was trying to get. It seems to me that 
there are not too many 'components' in a word definition. What I 
see when I get help is USAGE, DESCRIPTION (at the top level and at 
the refinement level), ARGUMENTS (and their type).  What I was after 
was a way to compose the help query to be very specific, but it seems 
to me that what you outlined would follow a certain lookup order. 
Did I misunderstand? With only the components just mentioned, is 
it too much to specify them specifically and in parallel with each 
other?

The sorting order should handle priorities, and the difference between 
word, /word, "word" and word! usage should be enough.

I would probably also add a /limit datatype!/typespec! option to 
refine searches.

For instance, help/limit "blah" number! would only list top-level 
defined numbers with "blah" in their names.

I am serious about you adding an approval comment to the ticket though.

There is no usage field, by the way. That section of HELP is based 
on the function arguments.

AdrianS, I just updated the comment to specifically show how all 
of your proposed options are handled by my counter-proposal.

sorry - stepped out for lunch - just digesting it and what you added

REBOL's function documentation model is completely different from 
Smalltalk's, so I had to do some translation.

so there is no way to specify that you want the order of the arguments 
to be enforced in the search?

the typeset! is specified as a block? [integer! string!] ?

No, it's a set of types. It is emulated as a block of types in R2-Forward, 
but the usage is basically the same.

so no to "it's specified as a block", but what about the order being 
lost?

Typeset! is a new datatype in R3. Function argument type specs are 
converted to typesets at function creation time.

and how would the typeset be specified after the /search refinement?

There is no order in a typeset!, it's a set.

ok, got it - so the order is lost and can't be enforced

if that's the way it is, then I guess we have to live with it

I'll ok the ticket as you have it then - sounds good in other respects

It's the way it is in R2 as well. The order has never mattered. HELP/search 
of a typeset! is covered in the comment - I'm not rewriting it :)

so specifying help/search integer! string! would create a typeset! 
of those datatypes, no? I'm just thick and what I was asking above 
is how do you specify a typeset! - in your comment you only show 
help/search integer! (though you mention that the last value could 
be a datatype or typeset)

HELP/search (to-typeset [integer! string]) so far. HELP/search [integer! 
string!] sounds like a good equivalent - I'll add it to the comment.

REBOL doesn't have variable length args without putting them in blocks, 
remember.

heh, yeah

This should be easy to add to R2-Forward as well.

I'm happy with what's there so I ok'd it

Cool :) To answer your question: Not this week, but it's on my list.

I suspect there is a misunderstanding here. It seems to me Adrian 
wants to search for functions that take two arguments, one integer! 
and the other string!. It seems to me Brian proposes a /search refinement 
that searchs for functions that have one of the arguments accepting 
integer! or string!. These are two very different things.

Gabriele: Brian explained to me that the order of the arguments in 
the spec is not preserved when a word is defined since the spec args 
are kept in a typeset! which doesn't preserve the order. In the last 
part of the comment to the ticket, he describes how you would specify 
a typeset! in the /search refinement (help/search [integer! string!]). 
This would let you search for definitions where at least two of the 
arguments are integer! and string! - in any order. It's not exactly 
what I was asking for, but it's all that can be done with the metadata 
that is retained from the definition.

Adrian, what Brian is proposing will get you most of what you want, 
but what you are asking for seems to be a bit to specific and from 
my perspective doesn't add enough value to be worth the time to implement. 
 With intuitive sorting you'ld get all of the functions that require 
both an Integer! and a String! first followed by those that require 
an Integer! or a String!.  About 80% of the reason that I actually 
use Help is to see the order in which a function expects it's arguments 
to be in.  Searching for [Integer! String!] will list the functions 
that opperate on a string and require an index to that string at 
the top of the list and I think that's what you're really looking 
for.  Some people think in oppisite directions and want to declare 
the index first and others want to declare the string first.  It's 
just a matter of preference and doesn't change what the function 
does.

Adrian, the order of arguments are preserved in the spec, but the 
order of types in the typespec for a particular argument are not. 
That is what I meant. Do you also want to search for functions that 
take multiple arguments, by the types of each of those arguments 
(their names don't matter), in the order specified? If so, why?

I'm having a lot of trouble coming up with a use case for that behavior 
in REBOL.

Or a way to specify it that is simple enough for a function that 
is, by its very nature, primarily used by people who don't know what 
they're doing, if only for a moment. I use HELP often, but only when 
I need help.

as a new user to REBOL, you tend to browse around to discover new 
functionality - least I do. The example I gave before was to answer 
questions like "what can I do with two strings?" or "or "what can 
I do with a block and an integer?". Typically, you tend to have a 
bit of a clue as to the datatypes you're working with, but you often 
can't recall the function names

I mean you typically have a clue to the datatypes for particular 
kinds of operations

from experience in other languages

It's funny, I've found that experience in other languages tends to 
make REBOL more difficult to understand, with some notable exceptions: 
Lisp-family languages, assembler, and Icon :)

I suppose, though, that if the type information is often (most of 
the time?) not there this type of lookup won't get you too much

Any experience in a language with C-like syntax trips you up, for 
instance :)

With the possible exception of Nemerle.