[groff] Work-related rants

[Larry Kollar]

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)