Arc Forumnew | comments | leaders | submitlogin
3 points by dram 3945 days ago | link | parent

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

Thx.

-----