Hi, Andrew wrote on Sun, Nov 03, 2019 at 12:56:58PM +0000:
[ Pandoc ] > is one of the most useful tools I have ever used. If you are writing > any sort of documentation then I *highly* recommend checking it out I strongly oppose that point. There is no need at all to bother with pandoc when you write documentation. (It may be useful for other purposes, i have no idea). If you write documentation, just use the best format in the first place. If the project you are documenting allows checking in documentation in mdoc(7) format, use that. If the project also wants to cater for systems not supporting formatting of mdoc(7) documents (basically, system providing neither groff nor mandoc, which more or less boils down to some old commercial UNIXes), use mandoc(1) -T man at release tarball build time to produce man(7) versions of the mdoc(7) files and ship them in the release tarball, too. If the project you want to document does not allow checking in mdoc(7) files, write your documentation in perlpod(1). The widely available pod2man(1) tool converts perlpod(1) to high quality man(7) output. If, at some time, you want to upgrade to mdoc(7), the pod2mdoc(1) tool helps a lot with that conversion. If the project you want to document neither allows checking in mdoc(7) nor perlpod(1) sources, write your documentation with groff_man(7). Doing that well is admittedly harder than writing good mdoc(7) or perlpod(1) and results in somewhat lower output quality, but it's not rocket science either. Using any other format is a thoroughly bad idea. The worst one which you must avoid at all cost is DocBook, closely followed by Markdown and related formats. So, when talking about documentation, i have never encountered any problem that even made me look at pandoc, and i'm working on documentation a lot, including format conversions. The fact that pandoc appears to not support the most important documentation language, mdoc(7), at all, neither for input nor for output, already makes me raise an eyebrow or two, but even if it did, i still wouldn't see what it could possibly be useful for. Yours, Ingo
