Re: [Groff] Choosing a portability target

[Clarke Echols]

Meg McRoberts wrote:
> One small thought about man page compatibility...  We have a fundamental
> problem between Linux and most Unix systems because of the section-naming
> differences.  I have never figured out a good way around that.  My current
> job includes responsibility for a handful of man pages about applications
> that run on Linux, Solaris, and Windows.  For Windows, I just run the text
> into a PDF file and publish it.  And I don't have a good solution for what
> to do about man pages for Linux and Solaris -- all the information may be
> the same but file formats are section 5 on Linux and section 4 on Solaris;
> administrative commands are section 8 on Linux and section 1M on Solaris.

The problem is Berkeley Unix vs. AT&T Unix.  AT&T put admin commands
in section 1M and file formats in section 4.  Berkeley put them in
8 and 5.  Linux apparently followed the Berkeley convention.  HP made
the change from Berkeley to the AT&T arrangement at HP-UX 5.0 in 1985,
and it appears that Solaris (and I assume AIX) also follows that
convention.  I have no clue why the Linux crowd took the Berkeley
route.  Maybe it's a "California thing"?

> As for the larger discussions, most of what I'm writing does not need any
> fancy formatting.  I would love to know the basic set of codings I can use
> that are pretty likely to work on any system.  I might some day decide to
> use something that isn't so portable but I wouldn't accidentally do that.
>
> meg

In all of my manpage work, I used .TH, .SH, .SS, .TP, .IP, .RS, .RE,
.B, .BR, .RB, .IR, .RI, .BI, .IB, and a set I created for "computer
font" (Courier): .CI, .IC, .RC, .CR (.BC and .CB were never needed
because the C family was used in syntax and Bold was never used in
that context).  I don't recall using any others.  I sometimes used
\c at the end of a line when I ran out of space (I tried to keep
lines under about 70 characters in source text) and needed to have
no whitespace between words/arguments.  .ne, .br, and an occasional
.bp (maybe) were about all of the low-level requests I ever used.
I used .PP instead of .P for paragraphs.  I may have occasionally
used .ce, but it was very rare, if ever.

I also included tables and equations (.TS, .TE, and the equation
begin/end labels (.EQ and .EE ? -- don't recall what they were),
but never had any real problems.  To split tables across pages, I
tried to arrange the tables so they worked correctly on troff and
man(1)/nroff formatting by using .if n and .if t requests to get
correct paging breaks.

I wrote a shell script that used vi and ran sed inside of vi
non-interactively (vi $file <vi_commands_file and inside of that
file I used a line: 1G followed by !Gsed -f sedfile to run the
entire file through sed with sedfile containing the sed commands).
Worked like a charm and got rid of all of the \fR, \fB, \fI, etc.
junk and changed it all to macro calls (.BR, .IR, etc.).  I could
overhaul 1000 files in 5 minutes on a 30 Mhz processor.  We didn't
have 2-GHz machines back in the 1980s!

And people wonder why I don't like Windows.  :-)  Sheesh!

Clarke (principle author of "The Ultimate Guide to the Vi and Ex
        Text Editors")