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