search

onilabs / stratifiedjs

Oni StratifiedJS (previously Apollo)
http://onilabs.com/stratifiedjs
Other
231 stars 22 forks source link

add to Addy's ES6-tools & sjs: » #language/ reorg? #15

Closed tomByrer closed 10 years ago

tomByrer commented 10 years ago

Thought you guys would want to review before I sent in the PR. https://github.com/tomByrer/es6-tools/commit/20a8ecd775ed4870b338080ac50e8a2ac3fb6d1a

However, when prepping this, I found the linked doc hard to read. Perhaps it could use spliting it &/or restructuring. So I'd like to hold off & fix that page so I don't have to re-submit the PR to Addy's Tools page.

It seems you have 3 sections that can be separate pages or better separated visually. Either way, I'd like Concurrency primitives & Syntax enhancements over JavaScript to get their own left-hand menu links. Not sure how to proceed...

timbertson commented 10 years ago

Hmm, it's a bit tricky. The docs are currently split up via type (i.e builtins are all the symbols, while syntax is all the language features). We provide the toplevel summary you linked to as an overview (with links to the specific symbols), but since that's just markdown it could be difficult to style specifically.

We could instead arrange it by function instead of type, but I'm not convinced that's a better ordering in the scheme of things. In particular: when you want to find out what some piece of syntax does you can hit up #language/syntax and scan through the available options. If syntax were scattered between different sections, you wouldn't necessarily know where to look (since you don't yet know what the syntax does).

As for the PR, there seems to be an empty linke there? More importantly, the first link (under onilabs.com) should probably go to https://conductance.io/reference#sjs:%23language/syntax::calling-javascript, as it sits alongside the rest of the documentation.

tomByrer commented 10 years ago

syntax were scattered between different sections

Good point. I was hoping some way to link deeper to the headers, like https://conductance.io/reference#sjs:%23language::%23Syntax enhancements over JavaScript

timbertson commented 10 years ago

Yep, that seems useful, so I've added it to the doc browser. Since the # is already used for symbols, it uses a ~ for an anchor-within-symbol. There's now a little pilcrow anchor on each <h2>, so you can link directly to e.g: https://conductance.io/reference#sjs:%23language/~concurrency-primitives