Readme is really confusing

[sdegutis]

I just read your really detailed and excellent comparison of Silk, Bidi, and Secretary on some mailing list. And I'm super glad you didn't give in to the pressure to stop working on it, because theoretically and philosophically, I think it's the best one so far, and I agreed with all the pros/cons you outlined.

That said, in reading the readme page and trying to get started with it, the "Use" section is really really confusing. Nothing in there resembles the router I saw described in the mailing list. Nowhere do I see any kind of path-to-function mapping. So I'm left kind of confused how to use this. I'd love to use it, I'm sold on it, I just want to figure out how :)

[domkm]

Hi Steven,

You're absolutely correct -- the readme is terrible. I've been meaning to rewrite it.

• Use routes to create a route table.
• Use match or arrive to convert a match and extract params from a request.
• Use unmatch or depart to form a URL from params.

arrive and depart are wrappers around match and unmatch for common use cases.

Does this help?

[sdegutis]

Thanks @DomKM. Unfortunately it doesn't help very much. I'm much more of a visual person who needs to see actual example code to understand how something works. Maybe I'm the only person like this, in which case feel free to ignore me :)

[domkm]

Silk only handles matching and unmatching. Think of it like bidirectional regex for URLs. What happens after matching is entirely up to you. On the server, you'll probably want to form a Ring response and send it back to the client. In the browser, you'll probably want to change your application state, request new data, etc.

Silk ships with a function for forming Ring handlers, which is a very common use case. This might be illustrative in understanding how to use it with Ring.

Here are a couple open-source projects that use Silk:

• https://github.com/rukor/om-ssr/blob/c1e5de5b39a678a548570a7e579a92dd9a2488d6/src/com/firstlinq/om_ssr/state/silk.clj
• https://github.com/jarppe/suurjako/blob/5997ec8cc824d659b842f9c18fa1966d806bb14f/src/cljs/suurjako/routing.cljs

Please let me know if this helps. :)

Again, apologies for the bad readme and lack of official examples.

[mattly]

I have to agree with this. Having evaluated bidi or some custom hybrid of compojure + secretary for our route lookup, I think silk suits us best, but it's really confusing to get going with.

[domkm]

Closing since this is an old issue. I'll try to get to re-writing the readme at some point and would very happily accept PRs for this. Thanks.