Hi, Ralph Corderoy wrote on Mon, Mar 05, 2018 at 03:43:43PM +0000:
> It's good a Markdown is working for you, but it and its ilk need to die > out. Others did a better job, e.g. http://www.methods.co.nz/asciidoc/ That may or may not be adequate for books, i don't know, but keep in mind that AsciiDoc must never, under any circumstances, be used for software documentation. It relies on DocBook, which has by far the lowest quality man(7) code generator on the planet. Besides being notoriously buggy and producing contorted, ugly, and highly non-portable code, that code generator is virtually unmaintained. Besides being the worst, it is also the most heavyweight documentation formatting system i'm aware of, and by far the slowest - on the order of 20 times slower than groff itself the last time i measured a few years ago. If you feel like you absolutely must auto-generate man(7) code for some reason rather than writing it properly by hand (or even better, writing mdoc(7) instead and converting that to man(7) for the handful of systems that still don't ship it), use perlpod(1) and pod2man(1). That's not perfect, but has always been very stable for a very long time without serious bugs that would be worth mentioning, and the generated code is not too messy. It's also reasonably simple and fast. Yours, Ingo P.S. I know this is drifting off-topic with respect to the OP, but an AsciiDoc advertisement on this list is too dangerous without a clarification, it might cause people to misunderstand and screw up the documentation of their project, even if it likely wasn't intended that way.
