Arc Forumnew | comments | leaders | submitlogin
2 points by akkartik 3946 days ago | link | parent

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 3946 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 3946 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 3946 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 3945 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 3945 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 3945 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 3944 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 3944 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 3944 days ago | link

Thx.

-----