They have some groff-relevance, so I thought I’d share. Both have to do with our recent move to DITA at work.
Rant the First: conditional page breaks ============================= Like *roff, making a PDF from DITA involves going straight from source through a formatting processor to PDF. Unlike *roff, neither DITA nor XSL:FO (the formatting objects that are analogous to *roff’s intermediate format) have the equivalent of .ne 2i (or whatever vertical space you specify). XSL:FO *does* have “keep with next/ previous,” but we haven’t added a user-specified keep (which can be done with the outputclass attribute). I’ve taken some smug satisfaction in pointing out that *roff has had .ne since the ‘70s, but nobody else seems to have figured out how useful it is. Not to mention diversions, or how -ms supports both keeps and floating keeps. Keep with previous/next is only partially adequate. There are many advantages to the new setup, not the least of which that it isn’t the old one, but this is going to be a thorn in our side as long as PDF is one of our requirements. (We had the same problem with the old system, but that hot mess at least output MSWeird files instead of going straight to PDF, which meant we had some pagination control.) Rant the Second: Embedded Manpages =============================== I was one of two people in our department tasked with overseeing the conversions. We had a high-end tool to work with, which was likely better than anything I could have cobbled up myself, but file conversions mean GIGO is at least one order of magnitude more important. So I got this email requesting a side project—we’ve gone from sort-of startup to “dang, we’re huge now” in the last couple of years—and a doc from one of the acquired companies didn’t get put on the conversion list because they *thought* it wouldn’t be needed. It was a CLI reference, and there was some question about whether it would be worth converting. (I think they were hoping it wouldn’t be, personally.) Anyway. They sent me an MS Weird file. I thought it would be fun to fart around with the DITA Open Toolkit’s Markdown support, so I fed it to Pandoc and wrote a couple quick’n’dirty awk scripts to split the output into topics and build a bookmap (what DITA uses to put topics in a hierarchy). I hadn’t looked really hard at the Weird document to begin with, but the output forced my hand. Ready for the scary part, kids? The CLI command documentation probably started out as manpages in the beginning. It looks like they formatted the manpages in a terminal window, then copied and pasted the output into the Weird doc as something akin to code blocks (monospaced, no fill). O M G whatta kludge I wrote another awk script to key on the erstwhile .SH headings and turn them into sub-sections inside the topics, then fed the whole mess into DITA Open Toolkit to convert everything to XML. I passed it on with a note essentially saying “this is the best I could do without getting really deep.” I don’t know if they decided it was worth pursuing. I put most of a day’s worth of work into it, so I hope they ran with it. It didn’t help that we constrained (i.e. eliminated) the syntax diagram elements… but if you saw me whining about mdoc last week, DITA’s syntax diagrams make mdoc look obvious by comparison. I didn’t try to parse all that stuff, because (especially if they decided not to update the doc) it would be more trouble than it was worth. Which leads to… Rant the Third: How *DO* you Embed Manpages? ====================================== Whether you’re using man or mdoc, it’s a separate macro package from the book-oriented packages (-ms, -mm, -me, -mom). One of my first exposures to Unix was Idris[1], which had an idiosyncratic set of macros for manpages (for example, using .SY instead of ‘.SH SYNOPSIS’). Sounds like overkill at first, but if you want to embed manpages in your reference manual? “All you have to do” is support those macros in your manual-oriented package. Actually, come to think of it, Idris had a port of runoff at best. It didn’t actually support macros; all those idiosyncrasies were hard-coded. Making it do what I needed was the primary reason I learned C in the first place. But in a modern *nix environment, where groff is a given, it’s still difficult at best to mix macro packages when it comes to producing documentation. You can always produce them separately, then use a PDF tool to combine them, but that doesn’t fix the table of contents or header/footer consistency. I guess that’s one of the points of both Docbook and DITA; you can use the same grammar to produce both tutorial and reference material, and combine them into a single deliverable. It can’t be worse than pasting a load of terminal output into a block of monospaced text. But this leads to wonder: how best to add images to an extisting document. After nearly 50 years, manpages are still relevant—which is why both Docbook and DITA attempt to support them as output (however poorly). [1] https://en.wikipedia.org/wiki/Idris_(operating_system)
