"Arc's documentation describes it under the heading "html generation" (in general.)"
That documentation is for Anarki Stable, the branch meant for users who aren't thrilled with Anarki's changes and just want to use official Arc, but who would rather not have to fix official Arc's known bugs on their own. On that branch, html.arc probably is the only HTML-generation library we can or should document.
Despite not being written as documentation for the Anarki master branch, it's nevertheless some of the most accessible documentation for that purpose. I see that's pretty frustrating. It's good that you're mentioning it or no one would work on it.
Yesterday, since this was on my mind thanks to these threads, I wrote some code for generating a simple HTML page based on Anarki's (help foo) documentation. Once I get this to automatically deploy with each new Anarki commit, it should give us a much more up-to-date documentation resource to link to.
---
"any newcomer is going to see it there and think that's what they should use when they want to generate html"
It pretty much is! Even if it's not as good as you can imagine it being, it's still the go-to HTML generation library for Anarki.
When I implied it wasn't "a self-contained library for public use," what I meant was that it was primarily made to get the webapps to work. It's quite a non-minimalistic approach to HTML generation if you ask me -- I'd rather treat every attribute uniformly rather than having a big table of special cases -- but in other places it does only what it needs to do for the purposes of those applications.
Paul Graham pursued the web server code in order to put pressure on the "core language" in arc.arc, to make sure he was focusing on operators that were actually good for something. He released the language to the public so he could put a wider variety of pressure on arc.arc. The operators in arc.arc were never finished, so html.arc was probably a long way from being finished itself.
---
"If html.arc isn't supposed to be Arc's general purpose library for HTML generation then what do we call it when we make it?"
If someone makes a new library for HTML generation, we can potentially embrace that as the new html.arc. Anarki is unstable enough that this would be pretty normal (although I think people have had a polite tendency not to delete something in case someone else was still attached to it).
---
"[paraphrased] What is /lib for?"
Personally, I'm reluctant to call it a "standard library" without a standards document, but it does "come standard" with Anarki, so...
Of the 14 files in the release of arc0.tar, the libs.arc file contained this:
So essentially half of the files in the first Arc release were essentially lib/ files that just hadn't necessitated their own folder yet.
Looks like there was always a lib/ directory in Anarki, even as far back as the first Git commit. At this point it's the obvious place to put files that some people might be interested to (load ...) and some people wouldn't care about. If someone has a single .arc file to share, dumping it there is easy regardless of what state it's in, and it usually fits right in.
---
"I really like it... but wow am I not capable of even reading that code ._."
Aw, I bet you could! :) Do you want to? Maybe if you've got a specific piece of code that perplexes you, we can help out.
Anyhow, one of the only reasons so many things are still stuck in the "arc2.master" branch is that porting them would be too much work. It could be that whtml.arc's time for porting has arrived. :-p
Right now, the only things ns.arc can import into local scopes are non-macro values. (Or rather, it can import macro values, but it determines what value they have well after the code it's in has been macroexpanded, so you'll just see them as (annotate 'mac ...) values, and calling them will be a function call that fails with an error.)
What you want are local macros (Common Lisp's `macrolet`, Racket's `let-syntax`). Suppose we name Arc's equivalent `w/mac`.
Then (w/html ...) could expand to this:
(w/mac html tag-html
head tag-head
body tag-body
...
...)
To implement `w/mac` requires changes to the macroexpander in ac.rkt. I don't know how much this will make sense to you, but this is the approach for anyone who wants to take it: It requires a change to the way `ac-call` looks up the macro's value (`ac-macro?`) so that it can look it up from the local scope (the `env` parameter). This in turn means the local scope value `env` needs to be refactored so it's a hash table rather than a list, and then `w/mac` can look it up from that table. The `env` parameter isn't passed into macros, so either `w/mac` would need to be implemented as a special form or we'd need to come up with a way that macros can optionally declare that they want to receive an `env` parameter.
This would be something of a breaking change to Anarki because it means Anarki will now allow a local variable to shadow a global macro. That was the problem you encountered with (body) in the first place; some calls to local variables were expanding as macro calls now because the macro lookup ignored local variables altogether.
There might be some code out there of the form
(let foo 1
(bar foo))
where (bar ...) is a macro call that expands to (foo ...) for some global macro `foo`. This code would now fail.
For some time I've thought it would be worth it for the local macro support, but I'm too afraid to make the breaking changes.
Nevertheless, a while back, there was a consensus here that the way things worked already was a bug. See "Global macro names take precedence over local lexical variables" at [1]. I don't remember if this bug was ever fixed in Anarki; it doesn't seem to be fixed now. (Maybe there was another consensus to reverse it? It could happen.) It's the very same bug you encountered with (body) in the first place.
Your comment detailed what the libs.arc file contained.
the code within tem.arc was originally part-in-parcel within those files, but was extracted out into its' own file. So he was just commenting that there is other code that exists in anarki that was originally included and that there may be more examples of such.
