I'm writing a man page for a script that I installed at my company, my first such man page. I began by copying the man page for cat to my new man/man1 directory. I then issued the man command for that page and got perfect output. I then started to edit that copied cat man file to adapt it to describe my script. At first all was well, each time I edited my man file and then entered man the output was steadily showing the information about my utility instead of about the cat command. But then I began seeing a problem. Every time I deleted irrelevant sections from the man file that had been relevant to the cat command, the output from my man file would start lower and lower down on my screen, with only blank lines above. When I restored those deleted lines the output from my man command would start back higher up on my screen again. The lines that I was deleting from my man file were well down from the top after many other commands, yet when they were deleted the result was blank lines before the output from my man file started displaying. What could be causing this?
The following is the content of my man file:
.TH SHOW_PATH "2" "November 2020" "GNU coreutils 8.22" "User Commands"
.SH NAME
show_path - displays your current path
.SH SYNOPSIS
.B show_path
.SH DESCRIPTION
." Add any additional description here
.PP
Displays your current path setting, directory by directory,
.br
in the same sequence in which the directories are searched.
.SH EXAMPLES
.TP
show_path
.SH AUTHOR
Written by Richard Baumann.
.SH COPYRIGHT
Copyright (co 2020 Exelixis, Inc.
UPDATE: It occurred to me that what I was seeing with regards to the output from my man page starting lower on the screen as content way down in the file was deleted was nothing more than the output being vertically-centered on the screen. If I can find the instruction in my man file that signals that the output should be vertically centered, or an instruction from an external roff user guide that turns it off, then I believe that the problem will be resolved.
FOLLOW-UP QUeSTION to MEUH:
That seems to work perfectly, but it leads me to two new questions. I started by inserting the "export PAGER" instruction near the top of my man page file, and found that it had no effect. I then entered the command export PAGER=cat man show_path at the command prompt, then entered man show_path, and it worked beautifully. I then entered unset PAGER at the command prompt, then entered man show_path at the command prompt again, and found that the output had reverted back to the problematic vertical centering on the screen display again. Those two steps demonstrated that the use of the PAGER system setting indeed had the desired effect. But here are my follow-up questions: (1) Setting the PAGER option affects the user's environment variables. My many man pages will be viewed by a large group of users across multiple departments. I would want whatever changes I make to the user's environment variables to be in effect only for the duration of the use of any of my man pages and then revert back to whatever they had been before the man command on any of my scripts was entered, i.e. I would need to know how to programmatically unset PAGER at the end of any man page that I write. (2) The setting of the PAGER environmental variable contains an element that is specific to each man page, i.e. the last token in the export instruction. Based on my findings so far, setting the PAGER environmental variable prior to issuing the man command is required. But its setting is dependent on which specific man command will follow. How can it be set so that a user can enter the man command on several of my scripts in a row and have them all work properly as a result of setting the PAGER environment variable only once prior to issuing the man command? Thanks in advance for your help, it is helping immensely so far.