[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] Work-related rants
[groff] Work-related rants
Sun, 16 Dec 2018 02:20:32 -0500
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
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).
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
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
(-ms, -mm, -me, -mom). One of my first exposures to Unix was Idris, 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).
- [groff] Work-related rants,
Larry Kollar <=