Clojurians Log v2

Could you explain what Asciidoc provides that markdown does not?

Quite a bit. Here is a helpful link: https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/

Oh sorry, that was poorly phrased. Let me try again: what does asciidoc provide that markdown does not, that you would like to use in docstrings?

It's not so much a matter of what it does or does not provide, it's consistency that is key. At work we have standarised on Asciidoc (for many of the reasons outlined in the afforementioned link). Having the ability to support Asciidoc reduces the mental overhead of having to learn something like CommonMark or Markdown, whilst in no-way diminishing the choice of those people who do wish to continue to use CommonMark or Markdown as before. Choice is good, and if that choice supports people in reducing the burden of learning something else, then fantastic!

(we use Antora at work too, to bring all our documentation across the various projects together into a central documentation store)

A PR that gives people the choice to use Asciidoc everywhere, is something that I, and others would welcome.

@dharrigan while I personally don’t find the mental overhead taxing, I respect that others might find it annoying. To me the small differences in the syntaxes for the markdown I use is totally fine. Once we add something like this, we have to support it forever. Can we make sure this is really important to folks in the cljdoc community? If we do entertain AsciiDoc docstrings we would need to do a bit of thinking. How will this work? (I think you are suggesting an option in cljdoc.edn?). The wikilink syntax is likely not be compatible with AsciiDoc. So we’d have to decide what to do there. We also limit CommonMark in docstrings by not allowing embedded HTML, would we need to do something similar for AsciiDoc? And I guess we should check for performance differences between the AsciiDoc and CommonMark renderers in this scenario.

That's a great gesture. Thank you. An option in cljdoc.edn would be great. Perhaps @claudius.nicolae might have input here since they were considering a PR?

I was thinking a manifest file of sorts in jar/META-INF/ in what's published on clojars, but I'm open to something better

Putting it in, as option, a processor, in the cljdoc.edn would make it more transparent I think.

and yes, wikilinks is not supported in AsciiDoc, perhaps then it would need support of the link: macro

I just thought of another design question. I have been looking, on and off for the last long while, at how cljdoc renders CommonMark and AsciiDoc (AsciiDoc rendering is currently a bit weak). One the the areas of study is maybe rendering elements a bit differently in a docstring because the visual context is different than an article. I wonder what this would mean if we allow the full rich set of AsciiDoc elements in a docstring. CommonMark’s limited visual vocabulary is actually helpful here. Just something more to ponder.

Adoc has <<ref>> I think can be used for wikilinking

Yes, that would work too

If you want to continue this adoc docstring experiment, exploration of rendering can be done in cljdoc-exerciser. https://cljdoc.org/d/lread/cljdoc-exerciser/1.0.53/doc/readme

@martinklepsch final say, yay/nay?

Inclined towards “nay” right now, mostly due to the maintenance effort / impact equation. An Architecture Decision Record (ADR) like we’ve done for other things might be good to document the tradeoffs of the two ways forward but that’d also require a bit of work and I don’t want to guarantee that it’ll convince me. A larger number of people asking for it might help too so feel free to open an issue to gather support. I hope this isn’t frustrating or anything. Cljdoc being an open source project I try very hard to operate it as lean as possible...

No biggie; made https://github.com/cljdoc/cljdoc/issues/435 ticket; if it gets blessing I'll try my hand at a pr.

Thanks @claudius.nicolae, I added in my comments from here on Slack to the issue!