Arc Forumnew | comments | leaders | submitlogin
Host arcfn-docs on arclanguage.github.io?
4 points by dram 1116 days ago | 38 comments
As docs on arcfn[1] is not up to date, and kens said that he do not have time.

I think we can host those docs on Github Page, and add new stuff came with arc3 and 3.1.

kens had kindly submitted doc sources and related scripts to Anarki[2], so the work needed to be done will not be much.

Besides that, contents of Arc Lang Wiki[3] can also be incoperated, so that we can have a centralized site, and I think it will make newcomers easiler.

Any thoughts?

[1] http://arcfn.com/doc/

[2] http://arclanguage.org/item?id=14542

[3] https://sites.google.com/site/arclanguagewiki/



3 points by dram 1113 days ago | link

I have push some initial commits to arclanguage.github.io.

I'm not a designer, so currently I just use bootstrap. I wish there are some experts here, so that our site can have a shiny and unique look and feel.

Next I need to look into arcfn's code, it will take some time. If you have any ideas, just edit and commit. :)

-----

2 points by akkartik 1113 days ago | link

Thanks! The first step is always the hardest, so thanks for undertaking it for us all.

I made a couple of tweaks to the menus. I think we should make anarki the default; 3.1 has some bugs and gotchas. Even if the docs will only support arc 3.1 for starters, there's still value in combining them with anarki, I think.

I love the favicon :)

I pointed at external resources where they're still useful. No reason to copy the default tutorial, for example, and everyone should know about http://tryarc.org.

Does anybody use anarki's arc.sh script? I just tried it from a different directory and it failed on me. If others can confirm the problem I'll try to fix it.

How do you test the layout locally? I trying installing jekyll, but didn't see the same styling..

-----

1 point by rocketnia 1113 days ago | link

"I think we should make anarki the default; 3.1 has some bugs and gotchas. Even if the docs will only support arc 3.1 for starters, there's still value in combining them with anarki, I think."

Seems like you and I disagree about this at the moment. :)

---

"I love the favicon :)"

Eh? Isn't that the favicon that comes bundled with Arc? (Hmm, I see the "ref" pages have no favicon at all. O.o )

As opposed to the Arc 3.1 favicon, I prefer the version currently used here on arclanguage.org. Its colors seem to have been tweaked to address the blue-and-black contrast issue identified on the original logo thread: http://arclanguage.org/item?id=9438

-----

1 point by akkartik 1113 days ago | link

"Seems like you and I disagree about this at the moment. :)"

That's cool :) Could you react to http://arclanguage.org/item?id=17794?

-----

2 points by rocketnia 1113 days ago | link

"Could you react to http://arclanguage.org/item?id=17794? "

I was thinking of asking you to react to http://arclanguage.org/item?id=17782, but that post works. :-p

---

"There's no value in being strictly compatible with an old, buggy release that never guaranteed compatibility in the first place. We should instead focus on a live version that's getting fixes over time, whether it's anarki or arc-nu or rainbow-js or something else."

If we agree it's a fix, then we can document it the correct way and just take note of which bugs exist in which implementations. Arc 3.1 is just one implementation for these purposes.

If someone wants a real reference implementation to test against, they can use a version of Arc that has relatively few bugs, such as Anarki's stable branch or your curated Arc repo.

Like you, I believe the Arc language should be free to change in ways that break existing code. However, I think some of the Arc community's most large-scale projects have been the multiple implementations of Arc, and I think that's worth representing on the website, even if the community evolves to have some other focus later on.

---

Speaking of choosing a canonical, main-documentation-worthy variant of Arc, I've always been reluctant to develop upon any existing implementation of Arc, due to licensing.

Now that I take yet another look at the Artistic License 2.0, I think it isn't nearly as complicated as I've interpreted it in the past. It's still odd, though: I think technically anyone can make closed-source products out of Arc, Anarki, Arc/Nu, Rainbow, Rainbow.js, Jarc, etc. as long as they give their source code to Paul Graham and Robert Morris in private (per section (4)(a)).

I'd prefer to use a more generic permissive license, something that obviously permits distribution of closed-source binaries, rather than being quasi-permissive depending on the participation of pg and rtm.

-----

1 point by akkartik 1113 days ago | link

Interesting, I hadn't paid attention to the licensing terms. I thought anybody could do anything with the code, period.

---

"If we agree it's a fix, then we can document it the correct way and just take note of which bugs exist in which implementations."

Sounds like you and dram are saying the same thing: http://arclanguage.org/item?id=17816. I think I now understand what y'all are suggesting :)

---

"Like you, I believe the Arc language should be free to change in ways that break existing code. However, I think some of the Arc community's most large-scale projects have been the multiple implementations of Arc, and I think that's worth representing on the website, even if the community evolves to have some other focus later on."

I'm not sure how to interpret this :) Were you suggesting that we should highlight things like arc-nu and arcueid? I'm totally supportive of that. It didn't occur to me to want incompatible variants to steal all the thunder from compatible variants -- especially since I would like to be utterly oblivious to compatibility :) Or did you mean something else?

(At the risk of unnecessarily repeating myself,) I am only opposed to linking flatly to http://ycombinator.com/arc/arc3.1.tar (die! die! :) without any provisos or qualifications. We already have a frontpage for arc3.1.tar; we don't need another.

-----

2 points by rocketnia 1113 days ago | link

"Were you suggesting that we should highlight things like arc-nu and arcueid?"

Well, I'm suggesting that they share documentation for their common features. If that sharing gives them more or less prominence on the site, I don't mind either way.

I think author intent matters here. If a new so-called "Arc implementation" comes along, sometimes it'll sacrifice improvements for the sake of compatibility (arcueid), and sometimes it'll sacrifice compatibility for the sake of improvements (Semi-Arc). I think this will correlate with our ability to share documentation between projects.

Jarc is an interesting case. It shows how subjective I am: Jarc changes the treatment of unbound variables to make it easier to call Java methods, but this doesn't affect most working Arc programs. Jarc doesn't support continuations, but it would if it could. I consider Jarc to be on the side of compatibility, but maybe only because I've found it easy to write Arc programs that work on Jarc despite these differences. Maybe I would have judged Semi-Arc the same way, if only my programs didn't rely on quite so much hygiene violation and ssyntax manipulation.

---

"I would like to be utterly oblivious to compatibility :) "

Yeah. Even though I recommend sharing documentation, I don't look forward to splitting hairs in what amounts to a standardization process.

-----

1 point by akkartik 1112 days ago | link

These are good points; I hadn't considered them at all.

Dang, this is gonna be a lot of work :/

-----

2 points by rocketnia 1112 days ago | link

I see it as work too. Maybe we should reject this rational thinking and focus on something we like.

Personally, I like the idea of jumping ship to Arc/Nu (or merging!). Then we can port the Arc/Nu compiler to Arc/Nu and extend it to compile itself to every platform; who needs other implementations? :-p As I understand it, Arc/Nu has a fully reorganized codebase and very few entrenched users, so it's reasonable to refactor it again and again.

Arc/Nu has a "3.1" folder and a "nu" folder, so the website could introduce the Arc 3.1 documentation as though it's really just documentation for a compatibility mode. ;) Meanwhile, anyone who has a passion for consistency can work on documenting this mode in the same way I described above. :-p

Come to think of it, I might just be outlining more and more work. If Arc/Nu somehow becomes a vibrant community project, it's design by committee, right? I'm going to get some sleep.

-----

2 points by rocketnia 1113 days ago | link

"Interesting, I hadn't paid attention to the licensing terms. I thought anybody could do anything with the code, period."

Whoops, you just reminded me it isn't that bad. :) Per (4)(b), a closed-source project (or a project under a different license) is just fine as long as it doesn't interfere with a separate Arc installation and it doesn't call itself "Arc."

Playing out some scenarios...

Theoretically, I could invoke (4)(b) to continue development of Rainbow.js under the MIT license plus a few restrictions. In particular, any forks of Rainbow.js could not be named "Arc" or interfere with Arc, but they could be named (and/or interfere with) "Rainbow" or "Rainbow.js."

Interestingly, the Artistic License 2.0 grants an explicit patent license for the Copyright Holder's patents, but not for the Contributors' patents. Not that this is necessarily a problem; I like the MIT license, but it doesn't specifically mention patents at all.

It seems like I'm now okay with AL2.0. Effectively the only thing it prohibits is using the name "Arc" without respecting the original creators. That condition would pretty much be ensured by trademark law anyway, if Arc were a product being sold.

P.S.: I'm not a lawyer. As if that weren't enough, I've demonstrated an ability to misunderstand this license over and over and over. :)

-----

1 point by dram 1113 days ago | link

What I cancern about is the compatibility of anarki and 3.1.

If anarki is stickly compatibe with arc3.1, or at least have a branch which make compatibility as one of its goal, then its good to make anarki as default.

Currently there are some compatibility issues, so I'm afraid it will confuse starters.

tryarc.org is really cool, I was not aware of it.

arc.sh also fails here.

I just run `jekyll --server --auto`. Maybe caused by failing to fetch css files?

-----

1 point by akkartik 1113 days ago | link

I'm curious: Did any specific incompatibility cause you trouble?

The gotchas I'm concerned with are enumerated at https://sites.google.com/site/arclanguagewiki/arc-3_1/known-.... I think they're far worse than any incompatibilities anarki causes. Anarki's incompatibilities at least error out immediately, but some of these gotchas are quite insidious. They are they reason we try to push newcomers away from installing arc3.1 at https://sites.google.com/site/arclanguagewiki/getting-starte....

There's no value in being strictly compatible with an old, buggy release that never guaranteed compatibility in the first place. We should instead focus on a live version that's getting fixes over time, whether it's anarki or arc-nu or rainbow-js or something else.

The documentation at arcfn has been out of sync with arc3.1 as well as anarki for many years. I love that we're fixing this, but I'd rather gradually bring the docs in sync over time than switch to a more misleading version of the code.

I'm open to being convinced otherwise about this, and if you like you can revert the frontpage change while we argue :)

-----

2 points by dram 1113 days ago | link

I am wandering what's the purpose of people who come here.

Some random thoughts:

1. want to learn about Lisp and Arc

2. want to learn about language design and implementation

3. want to deploy a clone of Hacker News

4. want to use Arc as a daily programming tool

5. want to make a fork :)

For 1, I think bugs in Arc is not too fatal for those guys, we just need to make them aware of those bugs.

For 2, they need to, and I think they would like to investigate those bugs, so I think its better to let them fix those bugs by themself, learning from mistakes is effective. :)

For 3, those people will not tolerant of bugs, but compatibility is also critical for them, both about codes and data. As they need to consider how much work they will need to do when PG release a new version.

For 4, they will satisfied with anarki or other forks.

For 5, as a fork, they need to treat something as a reference, and I think vanilla arc is the most suitable one.

So I think it's more suitable to make vanilla arc as default, as it can make more people happy. Anyone not satisfied with it can choose forks.

PS: I'm in group 3. :)

I'm not sure how far has anarki diverged from vanilla arc, and whether data is still compatibe with it, so I decide to use vanilla arc, and integrate some bug fixes.

PS 2: Of course, if PG can release a new version, that would be the most suitable choice. :)

-----

1 point by akkartik 1113 days ago | link

Ok, I'm outvoted just looking at the votes, so feel free to make arc3.1 the default.

But I still think you're chasing some mythic notion of compatibility. From http://www.arclanguage.org: "Arc is still fluid and future releases are guaranteed to break all your code." There is no "reference" here; if you want upgrades to be smooth you're guaranteed to be disappointed.

"if PG can release a new version, that would be the most suitable choice. :)"

Even if that new version gets no bugfixes for 4 years?! O_O What if that next version takes ten years to show up? Heck, what if it takes a year to show up. Are you sure you'll still care?

I don't know anybody on this site who still uses arc 3.1. Even my 'curated bugfixes' repo at http://github.com/akkartik/arc was a short-lived thing. It's just the nature of this community to go off on some tangent :)

Have you read the gotchas page? Many of those gotchas I'm talking about aren't minor bugs. They took weeks of pain and in some cases months to come up with a fix. I wouldn't wish that pain on anyone. For example, for several months I thought that arc and racket was just really slow, all it could do was 1 request per second. But it just seemed slow because all my requests were getting throttled because of some code in HN that most sites will never need, because they'll never have that much traffic.

Perhaps the compromise position would be the 'stable' branch of anarki. But I'm not aware of anyone who uses it. I really think that if you want to benefit from this community anarki is the most common baseline, and the whole point of a new site is to give newcomers the benefit of more updated information than the existing site, and to get them using what the veterans here are most familiar with so that they can get their questions answered soonest.

If the community has new ideas should we go try them out, or should we wait for PG to first grant them his permission? I know what he'd do :) And if people here have new ideas it's worth getting them feedback from others as long as we can be responsive to issues when they come up. And I think we're pretty responsive :) Arc is a bleeding-edge language, and we shouldn't try to act otherwise.

(Incidentally, yes, the HN site on anarki is indeed data-incompatible with arc3.1. It hashes passwords with sha512 rather than sha1, for one: http://arclanguage.org/item?id=17278. Which would you use?)

Hold on, I'll post a poll. I don't actually know that anarki is the most commonly used :) I'm also interested in rocketnia's reasoning of this whole issue.

-----

2 points by dram 1113 days ago | link

Although not thought every point throughtly, I have read gotchas page for several times.

I'm not against to bug fixes, but I think anarki has go far beyond that.

Take password hash for example, if let me choose, I'll remain it as is. If someone have hosted HN-like site using arc3.1, it'll be hard for them to use anarki instead because of that change.

-----

1 point by akkartik 1113 days ago | link

Ok, glad we can agree on the common ground of bug fixes. Perhaps we should make the stable branch in anarki the default. I'm not sure what's on it at the moment, but it's probably quite close to arc3.1, and we can patch in the biggest fixes to it.

In general, I'm uncomfortable supporting a version that we are not empowered to update. That's basically my biggest objection.

This community has had a culture of letting newcomers come in and show off new ideas to each other. I think that is valuable, so I'm in favor of allowing anyone to update the default version most of us use. But we can agree to disagree on that score :)

(I still think you're WRONG about the password issue :) What'll you do if PG switches the hash in the next release? SHA-1 is insecure, and an insecure default is a recipe for reputation damage down the road. Good thing arc isn't very popular..)

-----

1 point by dram 1113 days ago | link

Ideally, I would like to see arc3.1 be shown as default, along with a pack contains seperated patch files to critical bugs.

And we can treat anarki as a fully fork, with no restriction and full freedom.

About password issue. If PG switches hash, he surely will consider about compatibility, without that, all users of HN will need to reset their passwords.

-----

1 point by akkartik 1113 days ago | link

You: "About password issue. If PG switches hash, he surely will consider about compatibility.."

I'll quote PG and RTM again: "Arc is still fluid and future releases are guaranteed to break all your code." http://www.arclanguage.org

I interpret this sentence on the frontpage to mean that he will not be concerned about compatibility. Arc is for exploratory programming. If you have users you're on your own. I really don't see how you can interpret it any other way.

The good news is that migrating passwords isn't hard. I've done it for a site myself.

-----

1 point by dram 1113 days ago | link

PG and RTM may break other code, but I think they will not break their own code, as news.arc is inside of Arc, not outside. :)

I'm curious how did you migrate passwords, I thought some more code are needed to migrate them automatically.

-----

2 points by akkartik 1113 days ago | link

Yeah, I wrote some more code :)

First I transformed all existing hashes:

  (maptable [list 'sha512_sha1 (sha512 _)] hpasswords*)
Then, as users login and I momentarily have their unhashed passwords, I hash it with just sha512, making the hpasswords* value:

  (= hpasswords*.user
     (list 'sha512 (sha512 password)))
Password verification can now use the first element (the 'type') to decide how to hash the password.

-----

1 point by akkartik 1113 days ago | link

"I think they will not break their own code, as news.arc is inside of Arc, not outside."

But then how would they ever migrate beyond sha1? Would the hundred-year language save passwords in a way that gets more insecure every year?

I think arc's default assumption is that there's no difference between 'inside' and 'outside'. And this is how lisp used to be.

-----

2 points by dram 1113 days ago | link

Another method would be hash sha1 hashed values directly, like:

  (sha512 (+ (sha1 pw) user-salt site-salt))
Anyway, existing passwords still need to be migrated manually.

BTW, for security, it is also unsecure to pass unhashed passwords around network, unless use https.

-----

1 point by akkartik 1113 days ago | link

"BTW, for security, it is also unsecure to pass unhashed passwords around network, unless use https."

Yes. Though you can get that with apache or nginx.

-----

1 point by akkartik 1113 days ago | link

"Ideally, I would like to see arc3.1 be shown as default, along with a pack containing separate patch files for critical bugs."

This could actually be quite cool! Full transparency; we show the default, and we enumerate its biggest issues along with their fixes. That sets expectations in advance. Yes, make it so :)

-----

1 point by thaddeus 1113 days ago | link

If your counting votes then yes please do a poll instead. I think arnarki should be the recommended version we provide to new users.

-----

3 points by dram 1115 days ago | link

Failed to run arcfn-docs generation code using anarki, but do not have problem if using vanilla arc3.1.

There may be some compatibility issues.

Anyone interests to investigate can pull latest anarki code and run ./generate.sh in extras/arcfn-docs.

-----

1 point by akkartik 1115 days ago | link

Thanks for looking at it. Like you suggested, I think it's fine to just show the documentation for arc3.1 for starters.

-----

2 points by akkartik 1116 days ago | link

This is a great idea! So you're envisioning the code would be at http://github.com/arclanguage/anarki, and the docs would be at http://arclanguage.github.io/anarki? That has a certain symmetry to it. Yes, let's try it. Are you volunteering to work on this? :) Let me know if you need anything, if there are permissions issues, etc.

-----

3 points by dram 1116 days ago | link

I'm not sure if we should treat anarki and vanilla arc seperately.

If anarki is mostly compatible with the vanilla one, I think we can just put docs under http://arclanguage.github.io/doc, and add notes if some functions differently between them.

This is about stuff that overlapped by this two. For extensions and new libraries in anarki, we can make a dedicated page for them. e.g. http://arclanguage.github.io/anarki.

I'm not familiar with anarki, so not sure if this way is appropriate?

-----

2 points by zck 1115 days ago | link

I'd worry about treating them separately, at least depending how much anarki's stable branch (which is supposed to be very close to vanilla Arc) is emphasized compared to its more experimental branches.

-----

3 points by dram 1115 days ago | link

So I think we can update existing documents to v3.1 as the first step, and put other things to consider in the future.

-----

3 points by rocketnia 1115 days ago | link

I like the idea of describing Arc 3.1 in the main docs. This way the docs can describe the Arc features people have already strived to keep consistent in projects like Jarc, Rainbow, Arcueid, and Arc/Nu. If other libraries or language variants need their own subpages, those can spring up as necessary. :)

---

A project like this should probably use an "arclanguage.github.io" repo rather than some other repo's gh-pages branch.[1]

The arcfn static site generator may lead to some hassle. The generated website artifacts need to be pushed to the master branch, so they'll be the first thing someone sees when they delve into the repo to make a wiki edit. GitHub goes out of its way to make it easy to edit a repo as though it's a wiki[2], but that method of update won't trigger a very expressive build language[3], let alone anything that supports an Arc-based generator. Unless we have another server that does builds in response to a GitHub post-receive hook[4], in which case why not host the website there instead?

To use a custom generator, or to use Jekyll directly... both of these choices seem to have problems.

Another option would be to do keep Arc code inside <script> tags and run it with something like Rainbow.js, but search engines probably wouldn't index any content generated this way.

Hopefully someone here will be more optimistic about these ideas than I am. ^_^

[1] https://help.github.com/articles/creating-pages-with-the-aut...

[2] https://github.com/blog/844-forking-with-the-edit-button

[3] http://jekyllbootstrap.com/lessons/jekyll-introduction.html#...

[4] https://help.github.com/articles/post-receive-hooks

-----

3 points by dram 1115 days ago | link

Thank you for your wonderful ideas, I learn more about github services. :)

Some quick thoughts:

Can we split arcfn docs into two parts: tutorial and reference.

The tutorial part can integrate with current Google Site wiki contents, and can be renderred by Jekyll so it can be more like a wiki.

And the reference part need to be generate locally and then push the static html to the repo.

All those two part can reside on "arclanguage.github.io" repo.

The repo structure may be like this:

  arclanguage.github.io/
  |-- index.html
  |-- tutorial/ ; or move all stuffs to the top dir?
  |-- docs/     ; static html. (reference instead of docs?)
  |-- _docs/    ; source of docs
  |-- anarki/
  |-- jarc/
  |-- ...
Also, we can use a post receive hooks to generate docs directly.

-----

2 points by akkartik 1115 days ago | link

If you're doing it, you're the boss :)

That plan seems plausible. We can always try something else if we run into problems.

-----

1 point by dram 1114 days ago | link

OK.

Please create a new repo named arclanguage.github.io, then I'll do some initial work.

As I'm not good at document and English, so wish more guys can join. :)

-----

1 point by akkartik 1114 days ago | link

Ah, sorry I didn't realize you didn't have permissions. You should be able to create a repo now.

-----

1 point by dram 1114 days ago | link

Thx.

-----

1 point by kinleyd 1112 days ago | link

Hey, well done. It's beginning to look pretty good!

-----