CODEWITHSUNDEEP
formattingmanpagegroff
Kevin Zembower
Kevin Zembower

Reputation: 3

How to add literal code lines in manual page?

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.

Upvotes: 0

Views: 383

Answers (2)

Beni Cherniavsky-Paskin
Beni Cherniavsky-Paskin

Reputation: 10039

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: dvi rendering with .RS .nf .eo

You probably want a monospaced Courier font:

dvi rendering with .RS .EX .eo

.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).

Upvotes: 1

evil otto
evil otto

Reputation: 10582

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)

Upvotes: 2

Related Questions