John Gardner <[email protected]> wrote:
> G. Branden Robinson wrote: > >> mandoc(1), unsurprisingly, doesn't typeset pic(1) diagrams (p. 117). >> Unfortunately because it also doesn't set a man(7) `EX`/`EE` display in a >> monospaced typeface, the fallback ASCII art is mostly unintelligible. > > […] > > Pikchr is a project closely connected to SQLite, and it's used to render > railroad diagrams of SQL clause syntax. It's quite efficient, though their > disparaging remarks about Troff being a "historically significant but now > obsolete markup language" low-key pisses me off, especially knowing they > implicitly mean Markdown is Troff's "modern" replacement. I like Markdown for what it is, and I in no way consider it a “modern replacement” for *roff. Each has its strengths—Markdown for web-based documents, *roff for PDF and printed documents. Markdown is great for rapid composition as well, and utilities like Pandoc or lowdown can transform it into *roff -ms/-man/-mdoc for further refinement. I need to look into Pikchr, to see if it’s possible to create diagrams that work for both it and pic(1). That could be a fun digression, now that the kids are all in school and I won’t be on the hook to watch them all day. > […] > Anyway, Mandoc isn't a typesetting system, and it makes no allusions to > being one. I'm not even sure why they bothered with PDF output (because it > really *is* shit), and even its HTML output could do with some sanding, so > to speak. It's great at what it does: render manual pages for terminal > display quickly and competently […] Very good point. Each formatter has its strengths: * Mandoc for rendering manpages on a terminal display[1] * *roff for PDF or printed output (or rendering manpages on a terminal) * Markdown[2] for web-based output If you have to do all three, I would seriously suggest either Markdown or XML[3] as a starting point. Transform to whichever *roff macro package is most relevant for any non-web deliverables. — Larry [1] If you have a *roff that supports -mdoc, why would you need Mandoc? You can display -mdoc, -man, -ms, -mm, -mom, etc on a terminal with any *roff formatter (you might need Groff for -mdoc and -mom, not sure). [2] Don’t even think about coming at me with the convoluted corner-cases that “prove” Markdown isn’t worth thinking about, or whining about how many different variants there are. Pick one, stick with it, and hush. If you want to have something standard, Pandoc’s Markdown is pretty close to CommonMark. [3] Both DocBook (old) and DITA (not as old) can produce manpages, and they at least have a functional if not optimal PDF production route. Having worked with DITA for 7+ years, I’d recommend XML only for larger doc groups that either have the budget for support, or have more than one person in the group that can deal with XSLT.
