How to add literal code lines in manual page? - formatting

Question

I'd like to embed a block of code like this:
foreach my $n (1..10) {
print "$n\n";
}
in a groff 'man' document and not have it reformat it into a single line. I'd like to suppress all formatting, and not have groff recognize and process any special characters. This would be like the <pre> and </pre> tags in HTML. Is this possible to do in groff? Thanks.

Answer 1

You can turn off fill-mode with the .nf request, and turn off escape processing with .eo; they are correspondingly restored with .fi and .ec. groff will process these correctly, but it is possible that some alternate man-page formatters will not.
Example:
.TH "Manpage Test" SO
.SH NAME
Manpage test \- test manpage formatting
.SH DETAILS
Here is the example.
.RS
.nf
.eo
foreach my $n (1..10) {
print "$n\n";
}
.ec
.fi
.RE
.P
And there you have the example.
The code snippet should be rendered as "pre-formatted", and
following text should be back to filled/adjusted.
.SH AUTHOR
Evil Otto
Renders as:
Manpage Test(SO) Manpage Test(SO)
NAME
Manpage test - test manpage formatting
DETAILS
Here is the example.
foreach my $n (1..10) {
print "$n\n";
}
And there you have the example. The code snippet should be rendered as
"pre-formatted", and following text should be back to filled/adjusted.
AUTHOR
Evil Otto
Manpage Test(SO)

Answer 2

Few now remember that originally man pages were typeset for printing and not only terminal viewing. It's still possible by outputting postscript (man -Tps) or better dvi intermediate:
man -Tdvi ... > /tmp/man.dvi && dvipdfmx /tmp/man.dvi -o /tmp/man.pdf && xdg-open /tmp/man.pdf
and it's a somewhat good test for "semantic correctness" of formatting that otherwise looks same on terminal.
evil otto's answer is a good start but keeps the regular variable-width font:
You probably want a monospaced Courier font:
.RS
.ft CR
.nf
.eo
foreach my $n (1..10) {
print "$n\n";
}
.ec
.fi
.ft R
.RE
which can be shortened with .EX...EE macro for typesetting examples (plus, it saves and restores previous font family which is cleaner than hardcoding .ft R):
.RS
.EX
.eo
foreach my $n (1..10) {
print "$n\n";
}
.ec
.EE
.RE
.EX is an "extension", no idea what that means for its portability 🤷
groff documentation claims .EX takes an optional indent parameter (which could replace the .RS....RE) but it didn't work for me (and I don't see any such logic in the implementation).