Re: [docbook-apps] Generating markdown output from DocBook

[Shlomi Fish <shlomif@shlomifish.org>]

Hi Peter!

On Tue, 26 Jan 2021 21:11:32 -0500
Peter Desjardins <peter.desjardins.us@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 .