> We've discussed moving to Markdown. Unfortunately, while Markdown is > great for HTML, it's pretty terrible for things that are not HTML. > Certainly there are tools that convert Markdown to other formats, but > I'm not aware of any single tool (outside of Pandoc[0]) that does so into > all the formats we offer, including HTML, PDF, Texinfo, and manual > pages. Markdown also comes in a large variety of variants and writing > documentation to please any substantial number of tools is very > difficult. Actually, there a plenty of converters out there converting Markdown to anything. You many find many websites that are using these converters for providing conversion online. In case there'd be a particular target language that actually may be missing, you may want to employ a 2-step process: e.g., just convert Markdown to HTML and from there to anything else. Once established, documentation would get updated automatically with every build and always correspond to the latest version. I've been working with many documentation teams (e.g., Microsoft, Alphabet) who are using their own Markdown compilers for adding hyperlinks, warnings etc. in their automation script converting Markdown to HTML. In all the cases I've seen it's a simple pre-compiler, replacing particular tokens with actual Markdown content before conversion. Moreover, Markdown commonly accepts a restricted set of HTML tags, so you may even extend Markdown inline for anything fancy.
