Re: [Groff] Choosing a portability target

[Larry Kollar]

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.

You could use nroff as a pre-processor. For example, if you have  
foo.man as a master, and want foo.1M and foo.8 for your  
distributions, make the following changes to foo.man:

.cc @
@ec |
@nf
.TH foo |*Z
.SH Name
foo \- the canonical example
.SH Synopsis
[etc]

It's a pretty simple change; add three lines to the beginning of the  
file and replace the number in the TH line with the "Z" string. You  
would have to escape any instances of the pipe or @ characters  
through the text as well (or choose a different pair), but the entire  
thing could be scripted fairly easily. Now set up your Makefile:

manpages: foo.1M foo.8 bar.4 bar.5 # etc....

.man.1M:
    groff -Tlatin1 -dZ1M $< | sed -e '/^$/d' > $@

.man.8:
    groff -Tlatin1 -dZ8 $< | sed -e '/^$/d' > $@

.man.4:
    groff -Tlatin1 -dZ4 $< | sed -e '/^$/d' > $@

.man.5:
    groff -Tlatin1 -dZ5 $< | sed -e '/^$/d' > $@

Type "make manpages" and you're done.

Now if the only difference between foo.1M and foo.8 is the section  
number, even this is overkill -- you could just replace the section  
number with a unique string & use sed instead of nroff as a pre- 
processor (but still use the Makefile to automate the process).  
However, if foo does slightly different things on Linux and Solaris,  
you could insert conditionals in your master file as well.

Remember that the current version of -man gives you a lot of control  
over the output, if you need to mimic a particular style for your  
Windows documentation.

--
Larry Kollar     k  o  l  l  a  r  @  a  l  l  t  e  l  .  n  e  t
Unix Text Processing: "UTP Revival"
http://unixtext.org/