Hi Peter!
On Tue, 26 Jan 2021 21:11:32 -0500
Peter Desjardins <> wrote:
> I'm finding that more documentation tools are optimized for consuming
> markdown these days. For example, some commercial API portal framework
> <https://redoc.ly/docs/developer-portal/organizing-files/>s and
> site-generation tools use markdown as their default input formats.
>
> Does anyone have a nice solution for using tools that consume markdown when
> you write and maintain your documentation source in DocBook XML format?
>
> I have considered using a utility like Pandoc as a final processing step.
> So the chain would be something like DocBook > XSLT > HTML > Pandoc >
> markdown.
>
> I have also wondered whether anyone has built DocBook XSLT that directly
> converts the XML to markdown.
>
> Do you have something that works well for you?
>
See:
https://www.shlomifish.org/philosophy/computers/web/choice-of-docs-formats/ for
a roundup. pandoc often does an imperfect job from my experience. I prefer
asciidoctor over the markdowns because it has a first-class docbook 5/xml
backend support and because "every markdown dialect has an army and a navy"
(see:
https://en.wikipedia.org/wiki/A_language_is_a_dialect_with_an_army_and_navy ).
Also see https://twitter.com/shlomif/status/1350006472877420546 about why
both "herd mentality" or "anti-popular"/"anti-mainstream" fixation and
prejudices are not good.
> Thanks!
>
> Peter
--
Shlomi Fish https://www.shlomifish.org/
https://youtu.be/GoEn1YfYTBM - Tiffany Alvord - âFall Togetherâ
People who think they know everything greatly annoy those of us who do.
â Source unknown, via Linuxâs fortune-mod
Please reply to list if it's a mailing list post - https://shlom.in/reply .
