search

clj-holmes / clj-watson

clojure deps SCA
Eclipse Public License 2.0
77 stars 8 forks source link

Consider switching to AsciiDoc for docs #102

Closed lread closed 1 month ago

lread commented 1 month ago

I'm happy to help improve clj-watson docs, but I am much more comfortable in AsciiDoc. Would you be ok with switching?

Some things I like about AsciiDoc. It:

  1. Can automatically generate a table of contents.
  2. Has attributes; this is handy for things like setting the current version as a variable at the top of a doc.
  3. Is amenable to one sentence per line. This makes diffs quite nice and helps avoid run-on sentences.
  4. It is more expressive; you'll never have to drop down to HTML.

One thing to note is that although GitHub always renders AsciiDoc, it does not make much effort to render all constructs beautifully. For example, AsciiDoc has admonitions which are semantically equivalent to the GitHub Markdown alerts I recently added, but GitHub doesn't bother to render them beautifully. (That said, I find the GitHub Markdown alerts so relatively loud that they steal from the overall structure of the doc).

If our strong preference is GitHub Markdown, I can live with it. But I strongly prefer AsciiDoc and felt it worth my time to ask.

seancorfield commented 1 month ago

I don't know/use AsciiDoc so I would prefer not to switch.

lread commented 1 month ago

If you do get curious someday and want to explore the awesomeness that is AsciiDoc, happy to help you on that journey.