1

I'm using the groff man macros to produce general purpose documentation (not actually man pages) because they are easy to learn and use. I'd like control of the postscript page header as free text though.

The groff manual says:

Use the file man.local for local extensions to the man macros or for style changes.

Macro: .PT

Control the content of the headers. Normally, the header prints the command name and section number on either side, and the optional fifth argument to TH in the center.

How do I do this in practice?

1

The wording is obscure, but the advice is to modify the man.local file itself rather than override macros found in that file.

A good place to start is with the documentation: 5.21 Writing Macros (The GNU Troff Manual). That shows how to define macros.

The actual macros to study are heavily version-dependent. In Debian, I find the PT macro in the groff-base package, in

/usr/share/groff/1.21/tmac/an-old.tmac

as

.\" Redefine these to customize the header & footer
.
.de1 PT
.  tl '\\*[an-title](\\*[an-section])'\\*[an-extra3]'\\*[an-title](\\*[an-section])'
..

It passes named variables as the first parameter to .tl. To see what .tl is (grep is your friend) and what it does takes some work (mentioned here):

Are you aware that .tl (title) takes three parts, left, centre, and right?

On the other hand, groff's documentation has improved over the years: you can find ".tl" in the index.

As a rule, you will find that:

  • most of the macros (which you encounter in reading these files) are undocumented
  • grep'ing over the list of macros (grep -w helps) is the only way to find a particular macro
  • there are device-specific versions of some macros which override generic versions
0

If you like to get an idea on how to use modified macros that are intended to print man pages as a book, you may like to check the macros that are used to print the Solaris manual books:

https://sourceforge.net/p/schillix-on/schillix-on/ci/default/tree/usr/src/cmd/troff/troff.d/tmac.d/

Compare the "an" file with the "ansun" macro file. The latter is used to print books.

Note that these are macro sets for the original troff and not for the troff clone "groff", but as long as groff is compatible, it should work.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.