World: r3wp

The new DevBase (3) mostly works now. I posted some suggestions today, 
but it is usable as-is. I'm only using DevBase 2 for historical reference 
now. DevBase 3 doesn't have a reviewer concept, so I'm going to ask 
Carl what the new acceptance policy is - I have the rank to accept, 
but the guidelines need to be updated for the new model. Most of 
my todo list for DevBase 2 is already implemented in DevBase 3, so 
in many ways it is already a vast improvement.

I find I'm using the help function in the console all the time. It 
would be good if the help function could have some refinements for 
searching throughout the function definitions, or limit the search 
to specific parts of the definitions. Would this be a difficult enhancement?

this would be really cool  just like searching the man pages in unix... 
the easiest way to find a shell command when you can't remember it. 
 :-)

BrianH: as for filesharing - can we share also binary files? Is it 
general mechanism, or is RebDev limited to only text files and their 
diffing?

AdrianS: some small helper, but you probably know it. What you can 
do is partial word searches. E.g. try:

help to- ; and it will list every to-* function
help pr ; it will list every function containing "pr"

Yes, I saw the partial word search, but that onl searches within 
the word, not its definition. Also nice would be something like smalltalk's 
ability to find methods by supplying a signature example - i.e. give 
me all functions where the arguments are <integer>, <string>

perhaps as a refinement to HELP, such as help/args integer!

yes, something like that would be good. Should I make this enhancement 
request in CureCode to keep track of it?

Yes, please post that to CureCode.  It's a brilliant idea!

added as http://curecode.org/rebol3/ticket.rsp?id=676

how is that usefull to you? Do you really search for function, which 
accepts some concrete args? Why would you do so? :-) What about searching 
in help string?

well, when learning a language, you need all the help you can get 
- if I know the datatype of the args, I would probably like to know 
all the things I could do with them (append one to the other, multiply, 
union, etc)

oh, I think you mean why in the ticket I didn't have the dataype 
specified with the refinement - I'll change that

typesets should also be considered

what do you mean?

wasn't aware that a set of datatypes was a type itself

it's R3 only.

I have a long time proposition for help on dialects. Imagine e.g. 
VID, where styles do have help strings too. Gabriele proposed:

help/vid button

... whereas I proposed: help/dialect vid button

Not sure, if we can make help system pluggable that way?

Pekr: "can we share also binary files?" - In theory we are supposed 
to be able to. I haven't tried it yet.

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)