Mailing List Archive: 49091 messages
  • Home
  • Script library
  • AltME Archive
  • Mailing list
  • Articles Index
  • Site search
 

RFC: Examples in the auto-documentation

 [1/11] from: ammon:addept:ws at: 24-Dec-2002 3:01


Hi, If you have used REBOL for very long you have probably discovered the power of the HELP or ? function. I have noticed, however, that it just barely falls short of a true HELP system. There are no examples given. I would love it if there was a way to make this happen. Maybe by having the first string in the function declaration block be the example. For example: ;-) my-func: func[ "prints the value of a word" 'word [any-word!] ][ {my-word: "My word!" my-func my-word ;would return ;my-word is a word with a value of: "My word!"} print rejoin [word " is a word with a value of: " mold get word] ] This is what you would currently get:
>> ? my-func
USAGE: MY-FUNC 'word DESCRIPTION: prints the value of a word MY-FUNC is a function value. ARGUMENTS: word -- (Type: any-word) I propose that we get:
>> ? my-func
USAGE: MY-FUNC 'word DESCRIPTION: prints the value of a word MY-FUNC is a function value. ARGUMENTS: word -- (Type: any-word) EXAMPLE: my-word: "My word!" my-func my-word ;would return ;my-word is a word with a value of: "My word! By doing it this way it would enhance the system without breaking anything, or causing any backwards compatibility issues. Any thoughts or comments? Thanks!! Ammon Johnson CIO of Addept ---------- (www.addept.ws) 435.616.2322 ---------- (ammon AT addept.ws)

 [2/11] from: micael:gullmes:telenor:se at: 24-Dec-2002 12:48


Hi Ammon, Example's in the helptext is a good idea. I believe that using an optional {} to get everyone to add example's in their func's will not make everyone do so. You can get the same result using the current syntax, see the modified example below. I have also added a modified func version which gives this capability more 'nativley'. Brgds /Micael ;----simple change to my-func which gives an example text------------------- my-func: func[ {prints the value of a word EXAMPLE: my-word: "My word!" my-func my-word ;would return ;my-word is a word with a value of: "My word!"} ][ {my-word: "My word!" my-func my-word ;would return ;my-word is a word with a value of: "My word!"} print rejoin [word " is a word with a value of: " mold get word] ] ;---------------------------------------------------------------------------- If you really want to change the behavior of func to handle an example refinement: Something like this (it needs prettier print method though) ;----changes to Rebol's "func" which gives an example text------------------- func: func [ "Defines a user function with given spec and body." [catch] spec [block!] {Help string (opt) followed by arg words (and opt type and string)} body [block!] "The body block of the function" /example example_text [string!] "Example string (opt)" ][ if example [ if not string? first spec [ insert spec "" ] append first spec rejoin [newline "EXAMPLE:" newline example_text] ] probe spec throw-on-error [make function! spec body] ] ;----example how to use changes to Rebol's "func" which gives an example text------------------- my-func: func/example [ "prints the value of a word" 'word [any-word!] ][ print rejoin [word " is a word with a value of: " mold get word] ] { my-word: "My word!" my-func my-word ;would return ;my-word is a word with a value of: "My word! } ;---------------------------------------------------------------------------------------------- Brgds /Micael -----Ursprungligt meddelande----- Fr=E5n: Ammon Johnson [mailto:[ammon--addept--ws]] Skickat: den 24 december 2002 11:02 Till: [rebol-list--rebol--com] =C4mne: [REBOL] RFC: Examples in the auto-documentation Hi, If you have used REBOL for very long you have probably discovered the power of the HELP or ? function. I have noticed, however, that it just barely falls short of a true HELP system. There are no examples given. I would love it if there was a way to make this happen. Maybe by having the first string in the function declaration block be the example. For example: ;-) my-func: func[ "prints the value of a word" 'word [any-word!] ][ {my-word: "My word!" my-func my-word ;would return ;my-word is a word with a value of: "My word!"} print rejoin [word " is a word with a value of: " mold get word] ] This is what you would currently get:
>> ? my-func
USAGE: MY-FUNC 'word DESCRIPTION: prints the value of a word MY-FUNC is a function value. ARGUMENTS: word -- (Type: any-word) I propose that we get:
>> ? my-func
USAGE: MY-FUNC 'word DESCRIPTION: prints the value of a word MY-FUNC is a function value. ARGUMENTS: word -- (Type: any-word) EXAMPLE: my-word: "My word!" my-func my-word ;would return ;my-word is a word with a value of: "My word! By doing it this way it would enhance the system without breaking anything, or causing any backwards compatibility issues. Any thoughts or comments? Thanks!! Ammon Johnson CIO of Addept ---------- (www.addept.ws) 435.616.2322 ---------- (ammon AT addept.ws)

 [3/11] from: nitsch-lists:netcologne at: 24-Dec-2002 18:22


Ammon Johnson wrote:
>Hi, > If you have used REBOL for very long you have probably discovered the power of the HELP or ? function. I have noticed, however, that it just barely falls short of a true HELP system. There are no examples given. I would love it if there was a way to make this happen. Maybe by having the first string in the function declaration block be the example. For example: ;-)
<<quoted lines omitted: 34>>
> ;my-word is a word with a value of: "My word! > By doing it this way it would enhance the system without breaking anything, or causing any backwards compatibility issues. Any thoughts or comments?
to save space, we could have a #example in prebol, which appends its argument to a text-file. then help could search through the text-files. rebol can download the documentation on demand. like #example{ my-word: "My word!" my-func my-word ;would return ;my-word is a word with a value of: "My word!" } my-func: func[ "prints the value of a word" 'word [any-word!] ][ {my-word: "My word!" my-func my-word ;would return ;my-word is a word with a value of: "My word!"} print rejoin [word " is a word with a value of: " mold get word] ]

 [4/11] from: greggirwin:mindspring at: 24-Dec-2002 10:59


Hi Ammon, AJ> If you have used REBOL for very long you have probably discovered the AJ> power of the HELP or ? function. I have noticed, however, that it just AJ> barely falls short of a true HELP system. There are no examples given. AJ> I would love it if there was a way to make this happen. AJ> Maybe by having the first string in the function declaration block be AJ> the example. For example: ;-) I'm not sure how well this would work in practice. For some simple things it might be OK, but then simple things don't need as much explaining. :) Once you get into things that require more setup information, contain refinments, or need their output probed to see the results, the embedded example will overshadow everything else in the code. It's good stuff to have, don't get me wrong, I just don't think it belongs *in* the code as it is currently formatted and spec'd. I can certainly see where a literate programming model for REBOL could be very successful, but that's a different story. :) -- Gregg

 [5/11] from: ammon:addept:ws at: 24-Dec-2002 11:59


Hi, I based my desire for this functionality on the fact that I can sit at the console and write my entire program without touching a text book or any other source for information, just the console. And that is because of the auto-documented nature of REBOL. If there was some examples placed in with it then my productivity would literally double in most situations. Anyone else with similar experiences? Enjoy!! Ammon Johnson CIO of Addept ---------- (www.addept.ws) 435.616.2322 ---------- (ammon AT addept.ws)

 [6/11] from: greggirwin:mindspring at: 24-Dec-2002 12:37


Hi Ammon, AJ> I based my desire for this functionality on the fact that I can sit at AJ> the console and write my entire program without touching a text book or any AJ> other source for information, just the console. And that is because of the AJ> auto-documented nature of REBOL. If there was some examples placed in with AJ> it then my productivity would literally double in most situations. Anyone AJ> else with similar experiences? OK, how about this as a five-minute workaround: Put the ref-data.r file, used by view-ref.r, somewhere handy - maybe the same dir as REBOL. Load it, maybe in user.r ref: load %ref-data.r Write a func to do what you want (also added to user.r?) eg: func ['word] [help :word print last select ref word] Call it as needed
>> eg <
USAGE: value1 < value2 DESCRIPTION: Returns TRUE if the first value is less than the second value. < is an op value. ARGUMENTS: value1 -- (Type: any) value2 -- (Type: any) Returns FALSE for all other values. An error will occur if the values are not of the same datatype. For string-based datatypes, the sorting order is used for comparison with character casing ignored (uppercase lowercase). print "abc" < "abcd" print 15-June-1999 < 14-June-1999 print 1.2.3.4 < 4.3.2.1 print 1:30 < 2:00 -- Gregg

 [7/11] from: ammon:addept:ws at: 24-Dec-2002 13:22


Hi, Uh, I was thinking more on getting examples put into the REBOL Interpreter, not adding my own particularly. hehe. ;-) That would mean more work on RT's part though. In the meantime I will be putting together what information I find and documenting the language. ;-) Enjoy!! Ammon Johnson CIO of Addept ---------- (www.addept.ws) 435.616.2322 ---------- (ammon AT addept.ws)

 [8/11] from: gerardcote:sympatico:ca at: 24-Dec-2002 15:18


Hi Ammon,
> I based my desire for this functionality on the fact that I can sit at > the console and write my entire program without touching a text book or any > other source for information, just the console. And that is because of the > auto-documented nature of REBOL. If there was some examples placed in with > it then my productivity would literally double in most situations. Anyone > else with similar experiences? >
That's precisely the reason why I agree with you and for which I should like RT add some sort of useful add-on HELP system. In my case, until I had mastered the many facets of REBOL and most of the /refinements by seeing code for them all, I absolutely have to look at some online or written docs - that are accessible only from the outside of REBOL - for too many tasks I have to accomplish. In the beginning I thought this was OK but could be enhanced in some way from the inside of REBOL. May be I dream too much but simply look at the Dr. Scheme and this is where I would like REBOL to go for teaching and help beginners to develop with it. But I also know of the really big task this is involving and the somewhat limited resources RT has in this context. So for me a simpler and more easily manageable add-on HELP SYSTEM would be sufficient for the goal you expressed and that I share with you. Already the proposed online Dictionary and many guides (Core, etc...) are really good stuff. Only some missing examples are missing and I think that their new FAQ is really going to fulfill this role towards the original settled goal. Gerard

 [9/11] from: gerardcote:sympatico:ca at: 24-Dec-2002 15:19


Hi Ammon,
> If you have used REBOL for very long you have probably discovered the power of the HELP or ? function. I have noticed,
however, that it just barely falls short of a true HELP system. There are no examples given. I would love it if there was a way to make this happen. Maybe by having the first string in the function declaration block be the example. For example: ;-)
[...]
> I propose that we get: > >> ? my-func
<<quoted lines omitted: 11>>
> ;my-word is a word with a value of: "My word! > By doing it this way it would enhance the system without breaking anything, or causing any backwards compatibility issues.
Any thoughts or comments?
I also thought about this - and this would be a fine addition. However I think that this would be to much overcharge for the Actual Footprint of REBOL. In fact I would prefer an external add-on Help system that could be called automatically by the main REBOL engine if he is finding such external reference in the user.r or pref.r. This could so be added only by the ppl. that really need this kind of HELP without bothering thos that don't need it and this could be changed locally if anybody wants it to do so. to suit the language and personal additions - But then there should also be some way to submit any new additions to a central database repositary that the RT or some delegate could maintain for them under approval ... For the data formats, I didn't think about them but you already got an overview for the possible final results from the official REBOL dictionary. However I don't really know how this can be handled internally by REBOL and I leave this exercise to others. Regards, Gerard

 [10/11] from: gerardcote::sympatico::ca at: 24-Dec-2002 15:40


Hi Gregg,
> OK, how about this as a five-minute workaround: > Put the ref-data.r file, used by view-ref.r, somewhere handy - maybe
<<quoted lines omitted: 7>>
> USAGE: > value1 < value2
... Nice idea, I think we are approaching of a "dreamed of" solution without adding too much cost. The way you suggest could also be very extensible if someone desires it to be so. Simply add other examples-data.r module and almost everything is done. At least about the general specs... even Carl used it to add the ref-cmts.r to the original dict-file: refdata.r he is refering in his own /View documentation system. Another useful add-on could be to put all of this in the easy-vid format for a simple scripts browse and exec mechanism. This suggestion alone is really becoming my dreamed of gift for the Christmas and New Year. Why did we not think about this before ??? Take care everybody and continue to dream about ... what could be done with REBOL! This is really keeping FUN in my heart, more than many things on this earth. Regards, Gerard

 [11/11] from: ammon:addept:ws at: 24-Dec-2002 14:22


Hm... Now that I stop and analyse your proposal a little closer Gregg, I am sure we can come up with something. ;-) Thanks!! Ammon Johnson CIO of Addept ---------- (www.addept.ws) 435.616.2322 ---------- (ammon AT addept.ws)

Notes
  • Quoted lines have been omitted from some messages.
    View the message alone to see the lines that have been omitted