Clojurians Log v2

ok, just pushed com.phronemophobic/vt and pushed an update to membrane.term. I might as well go ahead and push membrane.term to clojars as well. I think we decided to hold off on version 1.0 for now, so maybe start with 0.9.0?

ok, membrane.term is now on clojars, https://clojars.org/com.phronemophobic/membrane.term

Heya @smith.adriane do you prefer GitHub markdown over AsciiDoc? I’ve developed a preference for adoc and am wondering if a convert to that format would work for you for membrane.term? If not that’s fine too. Why do I ask for membrane.term? Other than it being my personal preference, I like that: • it generates a table of contents • it includes user attributes (replacement variables), this can make things like updates for release easier • and it might make reusing some code I have for changelog updating-on-release easier

I do prefer github markdown over asciidoc, but that's only because I don't know AsciiDoc. I'm not opposed to checking out alternatives. Let me read up on asciidoc and see what it's like!

It’s really not important. But… if it satisfies a curiosity, by all means! I am guessing that you will like it.

how does the substitution work? do you have a source file and an output file? what's the format for the output file?

It happens at render time. https://raw.githubusercontent.com/lread/test-doc-blocks/main/doc/01-user-guide.adoc. At the top I have the doc title, some adoc attributes, and then user attributes :clojure-version: and :lib-version:

= User Guide
:toclevels: 5
:toc:
:clojure-version: 1.10.3
// NOTE: lib-version is automatically updated by release workflow
:lib-version: 1.0.166-alpha

[source,clojure,subs="attributes+"]
----
  :gen-doc-tests {:replace-deps {org.clojure/clojure {:mvn/version "{clojure-version}"}
                                 com.github.lread/test-doc-blocks {:mvn/version "{lib-version}"}}
                  ;; for -X syntax support specify exec-fn
                  :exec-fn lread.test-doc-blocks/gen-tests
                  ;; for -M syntax support specify main-opts
                  :main-opts ["-m" "lread.test-doc-blocks" "gen-tests"]}
----

I have a release workflow that updates :lib-version: within this file (and commits that change) when I do a release.

ah. ok, and github supports rendering like this?

or is there another step [to view the substituted version on github]?

GitHub replaces attributes at render time.

Cljdoc does this too.

The only thing I don’t really like about GitHub treatment of adoc is that it does not honor the richness of adoc. It converts all elements but does not beautifully style all elements. Nothing is broken. Just stuff looks a bit rough sometimes.

No worse that CommonMark styling really, but adoc has a much richer set of elements.

Got a fresh snowfall here. Gonna go for a walk and enjoy it! Later!

Before I trod off: cljdoc does a bit of a better job at adoc styling, but I feel it should do more and I will eventually get back to working on that. FWIW, https://cljdoc.org/d/lread/cljdoc-exerciser/1.0.57/doc/document-tests/asciidoctor-features.