Fork me on GitHub
#clerk
<
2023-04-16
>
teodorlu11:04:03

I was just wondering where compojure puts information about path parameters. I was about to go searching, when I figured, heck, I want to do programming, not google searching. So I added a tiny devui namespace, and viewed the request as a map and as a table. (:my-name (:request-params req)). Done. I never had to leave the REPL. Felt great. You guys rock!

🖤 6
teodorlu13:04:50

I stumbled on a pattern I think I'm going to use again:

(when-let [html (requiring-resolve 'nextjournal.clerk/html)]
  (html ,,,))
When Clerk isn't loaded, nothing happens. When Clerk is loaded, you get a nice preview. Kind of like rich comments. You can put them in the bottom of a document without harm. Yet, they can inform the usage of your library.

teodorlu13:04:58

Here's a bigger example:

(ns pandoc-wrapper
  (:require
   [clojure.string :as str]
   [babashka.process]))

(defn markdown->html
  "Converts mardown to html by shelling out to Pandoc"
  [markdown]
  (when (string? markdown)
    (slurp (:out (babashka.process/process "pandoc --from markdown+smart --to html" {:in markdown})))))

;; ## Clerk example usage

(when-let [html (requiring-resolve 'nextjournal.clerk/html)]
  (html
   (markdown->html (str/trim "
### Welcome

This is _it_.
"))))

teodorlu16:04:47

Right! But then you need a dependency on clerk-utils? But perhaps clerk-utils isn't big enough to make much of a difference!

Sam Ritchie16:04:27

I don’t think it has any dependencies itself if that helps

👍 2
teodorlu16:04:53

oh, wow, nice! I wasn't aware of that.

mkvlr15:04:05

@U3X7174KS curious if you’ve also tried clerk/example?

👀 2
Sam Ritchie17:04:01

I love clerk/example but I think that is a different concern, since clerk/example requires a clerk dependency

teodorlu17:04:01

yeah, in this case my code is being run with Clerk on JVM and from a babashka script, and as far as I’m aware, Clerk can’t run on Babashka (yet). Love that I can share a dependency between a JVM server and a small utility CLI.

mkvlr17:04:15

ah yeah, if you don;t want a dep on clerk you can have your own version of clerk/example that tries to requiring-resolve the one from clerk

👍 2
Sam Ritchie17:04:44

yep that’s what clerk-utils does for you!

👍 2
Sam Ritchie18:04:54

except instead of having to make new versions of anything you want to use you just wrap it all in the macro and use :as-alias , then you can use anything. nice and simple imo

👍 2
Sam Ritchie02:04:08

it is REALLY HARD to use clerk but ship a library without clerk…

👀 2
Sam Ritchie02:04:11

File: /Users/sritchie/code/clj/emmy/src/emmy/env.cljc
failed to require macro-ns "emmy.env", it was required by "emmy.env"
Error in phase :compile-syntax-check
FileNotFoundException: Could not locate nextjournal/clerk__init.class, nextjournal/clerk.clj or nextjournal/clerk.cljc on classpath.
	clojure.lang.RT.load (RT.java:462)
	clojure.lang.RT.load (RT.java:424)
	clojure.core/load/fn--6839 (core.clj:6126)
	clojure.core/load (core.clj:6125)

Sam Ritchie02:04:30

I can use as-alias, maybe, but I want to support clojure 1.10

teodorlu07:04:58

“clerk-usable notebooks but without clerk” sounds kind of like the goal of https://scicloj.github.io/kindly/, but kindly aims to abstract further; so that you can write notebooks that work fine with multiple notebook viewers (Clerk, Portal notebooks, etc). So it doesn’t encourage tight host (notebook viewer) interop. A possible solution could be to provide a dependency (“Clerk interface”) that contains all the vars from the nextjournal.clerk namespace, but falls back to a no-op when the proper clerk dependency is not found. That would be a bit of work, though. And it is possible (after all) to have an alias that includes the Clerk dependency, and adds "notebooks" to :paths. :thinking_face:

teodorlu07:04:54

oh, nice! 😁

teodorlu07:04:06

you read my mind before I could think it myself, haha

teodorlu07:04:39

You even provide proper docstrings 🙏 ❤️

Sam Ritchie15:04:16

@U3X7174KS I have been thinking about the Kindly note above, and of course I appreciate the push for more abstraction… but I also sort of feel like it may be a distraction from actually… WRITING a bunch of literate code and examples!! Like, we have tools that are pretty good and can do everything. and everyone working on Kindly must feel that way if they think that a common subset of these systems is expressive enough to get by. but do we have a good list of literate programs yet that we want to abstract? are people writing and publishing these?

Sam Ritchie15:04:25

I.m asking because I want to read them

teodorlu21:04:46

I think @UPGS9BS0L has experimented with Kindly for #C04DJMF8TNX.

teodorlu21:04:56

> but I also sort of feel like it may be a distraction from actually… WRITING a bunch of literate code and examples I broadly agree. At least for myself. I feel like I need more practice doing the thing (writing real content) before I'm able to contribute anything meaningful to the tooling. I find abstraction really hard until I have a few specific examples, then it feels more natural afterwards. For my own use, I've been using Clerk almost exclusively. The book is a good reference, the tooling is well explained, dependency tracking and reactivity works, and I'm not hindered by bugs. -- I'd love for us to have the privilege of too much content that we want to move around. Because then we have the content. Before we have the content, the problem is that we don't have the content (my opinion). And it's easer to port content than create it the first time (my opinion).

👍 2
Kira Howe04:04:59

This is the catch-22 imo.. I guess first of all by “content” do you mean the literate programs? I like clerk for experimenting and trying things out but there is some friction using it to create educational materials.. part of it is that writing large amounts of test as clojure comments is not ideal. This is somewhat mitigated using the markdown viewer, but then it’s hard to figure out a convention for when to use which. Some other points of friction I’ve run into include customising the html artifact (i.e. would be nice to add pagination, custom links at the bottom of the page, etc) and lack of support for other types of artifacts (like an epub or pdf)

👍 2
Kira Howe04:04:49

anyway the cookbook is underway and still being written every day so there should be lots of “content” soon to experiment with!

👍 2
teodorlu05:04:47

> I guess first by "content" do you mean literate programs? > Yup. Or "rich texts explaining something, powered by visualizations we can make with code". You are creating substantially longer texts than what I've made with clerk. And having more control might make sense when you're publishing a book. In contrast, I've mostly been happy following Clerk's defaults, wanting to get something out quickly rather than a good big thing out eventually. Though I can't help but see some similarities between your project and Sam's (see for example https://roadtoreality.substack.com/p/the-dynamic-notebook and https://roadtoreality.substack.com/p/a-tentative-roadmap).

mkvlr06:04:50

> there is some friction using it to create educational materials.. part of it is that writing large amounts of test as clojure comments is not ideal. This is somewhat mitigated using the markdown viewer, but then it’s hard to figure out a convention for when to use which. @UPGS9BS0L would love to learn more about this. > Some other points of friction I’ve run into include customising the html artifact (i.e. would be nice to add pagination, custom links at the bottom of the page, etc) this should be possible today but needs to at least be documented and maybe made easier. > lack of support for other types of artifacts (like an epub or pdf) for our https://px23.clerk.vision, we did produce a https://storage.clerk.garden/nextjournal/clerk-px23@eace4eb4123b1f791e188205e77aa07dc136b9c9/README.pdf using pandoc and latex. Here’s the https://github.com/mk/clerk-px23/blob/main/dev/latex.clj if you’re interested. So also possible but we’re less sure this should be part of clerk. There’s a lot of small decisions like how to deal with references and provide alternative content for interactive stuff that I think are context-dependent: one example from that essay is that we treated every link to https://doi.org as a reference and fetched the metadata for the given DOI. Would love to see others experiment with this and report back though.

👀 2