Arc Forumnew | comments | leaders | submitlogin
2 points by evanrmurphy 2616 days ago | link | parent

I can definitely imagine better documentation easing the learning curve for new Arc programmers. Source code can be self-explanatory, but only after you've attained a certain base level of fluency with the language. Just as the axioms have to be defined in Racket [1] before Arc can work, they have to be defined in your head before it can make any sense. So I applaud your effort.

One resource that really helped me learn faster was rntz's help system, available in Anarki [2]. It's very convenient because it gives you access to documentation right at the repl:

  arc> help.acons
  [fn]  (acons x)
   Determines if `x' is a `cons' cell or list.
      Unlike 'alist, this function will return nil if given an empty list
      See also [[atom]] [[alist]] [[dotted]] [[isa]] [[cons]] [[list]] 
  nil
  arc> help.alist
  [fn]  (alist x)
   Return true if argument is a possibly empty list
      Unlike 'acons, this function returns t when given an empty list
      See also [[atom]] [[acons]] [[dotted]] [[isa]] [[cons]] [[list]] 
  nil
  arc> help.afn
  [mac] (afn parms . body)
   Creates a function which calls itself with the name `self'.
      See also [[fn]] [[rfn]] [[aif]] [[awhen]] [[aand]] 
  nil
Had you known about this already?

[1] Or Java (http://github.com/conanite/rainbow, http://jarc.sourceforge.net/), or JavaScript (http://jonathan.tang.name/files/arclite/index.html), or Arc itself (http://arclanguage.org/item?id=11128). ^_^ I think someone did a port to Common Lisp not too long ago as well, but I can't find the link.

[2] http://github.com/nex3/arc/commits/master/help/arc.arc



2 points by fallintothis 2615 days ago | link

Source code can be self-explanatory, but only after you've attained a certain base level of fluency with the language. Just as the axioms have to be defined in Racket before Arc can work, they have to be defined in your head before it can make any sense. So I applaud your effort.

Well put. My thoughts exactly. The suggestion wasn't necessarily to learn Arc by spending a couple days reading the source. I mean, that's what I did, but I was already familiar with Common Lisp. Just that once you reach a certain point (as Preston seems to have), it's not so daunting to say "hey, I wonder what filechars does?" and go read

  (def filechars (name)
    (w/infile s name (allchars s)))

-----

1 point by prestonbriggs 2616 days ago | link

I didn't know of it. Sounds great. Plus, I should be able to write a little program to grovel through his system and gen up a TeX document like mine.

Thanks for the pointer, Preston

-----