[rescue] My Best Rescue to Date.. Ever

[Devin L. Ganger]

on 1/19/2006 11:09 AM Richard wrote:

> Perfectly reasonable for writing new man pages, but existing man pages
> that use the format-based tags should still work.  In other words, if
> you provide a troff clone, it should have a compatible set of an
> macros so that 'my-troff-clone -man foo.1' will work.

If you're providing a software package that is aimed at UNIX systems 
(and UNIX-alikes) in general, rather than a specific flavor, you should 
have a pretty compelling reason to break the way things are done without 
at least flagging it. I misremember the specific package now -- it's 
been years -- but I was installing it onto a Solaris box and the man 
page was written against the new macros, unlike pretty much everything 
else at the time. I could somewhat understand that, if they, y'know, had 
added the appropriate note to the OS-specific README telling you that 
you needed to install a new macro set, but they failed to do so -- and 
while they clearly called out the need for gmake and a couple of other 
non-Sun versions of utils, they failed to call out groff.

At this point in time groff did in fact come with all the right macro 
sets to read the traditional format, so Mr. Hendrix's assertions aside, 
there was no legal/licensing or technical reason to silently switch the 
macro formats. Unfortunately, this particular package (damn it, I *wish* 
I could remember what it was; I know it's not Sendmail, but it was part 
of the toolchain I had to install to get Sendmail compiled on Solaris 
under gcc) was just the tip of the iceberg and there was a noticeable 
flood of other software that followed suit shortly thereafter.

Now, using the new formats for the entire man set on one of the BSDs I 
can quite understand (and indeed, structural markup formatting is a 
great reason to choose the new macros for an entire distro); I just 
don't think it's an appropriate thing to assume for a more generally 
available piece of software unless you take pains to point out what 
needs to be changed so that your man pages actually work.

-- 
Devin L. Ganger <devin at thecabal.org>
Homepage: http://www.thecabal.org/~devin/
Devin on Earth: http://blogs.thecabal.org/blogs/devin/