Hi Peter! On Tue, 26 Jan 2021 21:11:32 -0500 Peter Desjardins <peter.desjardins...@gmail.com> 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 . --------------------------------------------------------------------- To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
