documenting

[1/12] from: jjmmes::yahoo:es at: 30-Aug-2002 3:17

Has anybody modified rebdoc to document the functions in a set of scripts, either in HTML or even better PDF ? Thanks

[2/12] from: al:bri:xtra at: 30-Aug-2002 16:08

jose wrote:

> Has anybody modified rebdoc to document the functions in a set of scripts,

either in HTML or even better PDF? I haven't. But,... If you really need to document your own Rebol functions, then I respectfully suggest that you need to rewrite them to a higher standard. Rebol can easily be self documenting, I believe. Andrew Martin ICQ: 26227169 http://valley.150m.com/

[3/12] from: jjmmes:y:ahoo:es at: 30-Aug-2002 10:41

No need to rewrite for basic documentation, just 2 steps 1. Parsing all the functions in the scripts 2. Applying a modified version of source to each function and generating a document from that --- Andrew Martin <[Al--Bri--xtra--co--nz]> escribi�: > jose wrote:

[4/12] from: jjmmes:ya:hoo:es at: 30-Aug-2002 11:13

Hi Andrew, Do you consider that your Values functions are in to the higher documentation standard ? To me, that is the basic way to document proposed by rebol and more than enough (in fact more than basic, because you include Example in many headers and I recall RT has separate files with more info like examples, etc..). I don't view that as a rewrite. What ideas you have on this ? Going back to your Values lib, I'm sure you have very useful functions but without an automatic summary like the one I propose it's hard for others to adopt (think of learning rebol core but not having a list of the functions, ..) I think when you write a ton of functions you need to have some sort of structure that makes them useful to others because the overall structure is normally only in the head of the developer. With a simple script you can have a basic clasification (+ the help output) like text processing: func1 func2 cgi: func3 func4 list processing: func5 ... dialects: funcX and for each func --USE: --DESCRIPTION: --ARGUMENTS: Does this make sense ? --- Andrew Martin <[Al--Bri--xtra--co--nz]> escribi�: > jose wrote:

[5/12] from: robert:muench:robertmuench at: 30-Aug-2002 12:21

> -----Original Message----- > From: [rebol-bounce--rebol--com] [mailto:[rebol-bounce--rebol--com]]

<<quoted lines omitted: 4>>

> Has anybody modified rebdoc to document the functions > in a set of scripts, either in HTML or even better PDF?

Hi, I haven't thought about this but maybe I can extend make-doc-pro to be used on Rebol scripts as well... Robert

[6/12] from: zokie::libero::it at: 30-Aug-2002 12:41

Hello jose On 30-Ago-02, jose wrote:

> Has anybody modified rebdoc to document the functions > in a set of scripts, either in HTML or even better PDF

I'm working on something similar. http://members.xoom.it/amigazette/rebol/make-autodoc.zip Now it support only HTML output, but I will add PDF output as soon as Gabriele Santilli's PDF-maker will automaticaly split text which is too length for a pdf page. To create documentation for all functions into a file called %popeye.r you must before add, somewhere into %popeye.r, this block definition: popeye: [ my-function-1 my-function-2 .... ] then write into a Rebol Shell: make-autodoc-html [%yourpath/popeye.r] You may specify more than a file at time. In next release will be present rebol script information extracted from script header if present ad beginnning of documentation file. Please Note: 1) To run it you need to download even: http://members.xoom.it/amigazette/rebol/ztools.zip 2) You need to setup relative path to your Rebol Environment. 3) Those script are at experimental stage, they maybe heavly change in future! Regards -- "Where did you get all those facts!?!"

[7/12] from: jjmmes:yah:oo:es at: 30-Aug-2002 16:14

first link make-autodoc.zip seems is broken second is OK thanks --- Francesco De Napoli <[zokie--libero--it]> escribi�: > Hello jose

[8/12] from: greggirwin:mindspring at: 30-Aug-2002 10:12

Hi Jose, << think of learning rebol core but not having a list of the functions >> I think a good starting point for this would be something like ViewRef. Not that HTML or PDF aren't good, but the "active documents" that REBOL is so good at (EasyVID, etc.), are head and shoulders above them IMO. I have some tool ideas along those lines, but haven't had time to pursue them yet. --Gregg

[9/12] from: jjmmes:ya:hoo:es at: 30-Aug-2002 20:26

> I think a good starting point for this would be > something like ViewRef. Not

<<quoted lines omitted: 4>>

> tool ideas along those lines, but haven't had time > to pursue them yet.

ViewRef ? Do you mean Ref-Words ? Different objectives. I've checked Volker's snippet's viewer and it's great. A different need is when you want to have a printed copy describing a bunch of functions. I need the printed copy when there are a ton of functions. After I know the functions I can go and check/improve the snippets.

[10/12] from: greggirwin:mindspring at: 30-Aug-2002 13:11

<< ViewRef ? Do you mean Ref-Words ? >> Yes. Sorry. << Different objectives. I've checked Volker's snippet's viewer and it's great.>> Volker always comes up with cool, useful stuff. --Gregg

[11/12] from: al:bri:xtra at: 31-Aug-2002 9:08

jose wrote:

> Do you consider that your Values functions are in to the higher

documentation standard ? To me, that is the basic way to document proposed by rebol and more than enough (in fact more than basic, because you include Example in many headers and I recall RT has separate files with more info like examples, etc..). I don't view that as a rewrite. What ideas you have on this ? Sorry, I misunderstood your post. I had believed that you needed to document just one function, implying that the author of the function didn't understand the function's purpose well enough to write a good description as Rebol code. Sorry about that. Most of my Values functions include the Example in the header, which is useful when I forget how to use the function! (That's a sign to me that the function probably isn't intuitive enough yet.) I also need to revisit those few that aren't up to scratch and fix them up.

> Going back to your Values lib, I'm sure you have very useful functions but

without an automatic summary like the one I propose it's hard for others to adopt (think of learning rebol core but not having a list of the functions, ..) Yes, this automatic summary would be very good. A dictionary can be generated by loading all the scripts in the Values/ directory (basically running the %Values.r script from %User.r) and simply running the dictionary script from Rebol.com. http://www.rebol.com/view/docs/make-ref.r Which (after fixing a bug in my %Patches.r script), doesn't actually show my Values/ functions? Hmmm... I feel that the dictionary idea is best, once I find out how to get my Values/ to be included. Does anyone know how to do this? I'm almost sure it's probably a simple modification of make-ref.r Andrew Martin ICQ: 26227169 http://valley.150m.com/

[12/12] from: zokie:libero:it at: 31-Aug-2002 9:59

Hello jose On 30-Ago-02, jose wrote:

> first link make-autodoc.zip seems is broken > second is OK

I'm sorry: I wrote the email before upload file :( The rigth link is: http://members.xoom.it/amigazette/rebol/autodoc.zip Regards -- "Where did you get all those facts!?!"

Notes

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