1

Using Man-mode in Emacs 27 on Arch Linux, for reading the zshall(1) manual page, the manual page appears to have been formatted to display on 16 separate pages, with each page being displayed separately. I'm seeing this behavior for the zshall(1) manual page, using the Emacs+GTK build from Arch Linux, in X Windows and at the console.

I'm also seeing this page-splitting behavior for the zshall(1) manual page in Emacs 28 on FreeBSD.

Perhaps this page-splitting behavior may be unique to the zshall(1) manual page, or manual pages using a similar formatting convention? Comparatively, the bash(1) manual page is displayed all in one page, in both Emacs installations. To own opinion, this is the ideal presentation for the manual page. It's easy to search and page through.

Maybe this has been around in Emacs for a while? Personally, I've not seen this page-splitting behavior outside of the manual pages for ZSH.

Searching the Emacs Lisp source code for Man-mode in Emacs 27 on Arch, I've been unable to locate any option for disabling the page-splitting behavior. I've also searched for a function for searching the content of those 16 pages. Presently, I'm only able to search each of the 16 pages separately.

To my own opinion, this page-splitting behavior makes it considerably more difficult to navigate the content of the manual page. Perhaps there may be some way to join any separate pages in the variable Man-page-list under the Man-mode buffer and display those all at one time, in Emacs Lisp? May there be any known workaround outside of that, to display the content all in one page?

Health, all

Sean Champ
  • 60
  • 5
  • 1
    I think you mean `zshell` ? – phils Oct 24 '21 at 04:00
  • Is this *different* to what happens when you read the man pages outside of Emacs? You've neglected to say, but it's the very first question to ask. – phils Oct 24 '21 at 04:04
  • A very simple 'workaround' is to use the Emacs core package [WoMan](https://www.gnu.org/software/emacs/manual/html_mono/woman.html). – dalanicolai Oct 24 '21 at 16:01

1 Answers1

3

If you look at the source of the zshall manpage (/usr/share/man/man1/zshall.1 for me) you'll find a section towards the end that looks like

.so man1/zshroadmap.1
.so man1/zshmisc.1
.so man1/zshexpn.1
.so man1/zshparam.1
.so man1/zshoptions.1
.so man1/zshbuiltins.1
.so man1/zshzle.1
.so man1/zshcompwid.1
.so man1/zshcompsys.1
.so man1/zshcompctl.1
.so man1/zshmodules.1
.so man1/zshtcpsys.1
.so man1/zshzftpsys.1
.so man1/zshcontrib.1

.so is the troff request to include a file. Assuming your terminal manpage viewer (man) is not using pre-compiled manpages, it is effectively concatenating those files with zshall.1 acting as a wrapper and sends the result to a pager. Emacs's "Man mode", being "smarter" than a just a pager treats this as something akin to a "collection" that you can navigate through. It doesn't even quite get that right. You'll notice that the first page of zshall(1) (when viewed in "Man mode") is missing its footer. Move to the last page (zshcontrib(1) for me), and you'll see the footer is concatenated there.

So, I think there are a couple of issues at play here. We have an outdated viewing paradigm1 ("Man mode"), a manpage (zshall.1) source written from the perspective of a terminal viewer (man) and like with many other "old fashioned" things in Emacs, a lack of people annoyed enough about the situation to do anything about it.

A feature request for a flag to toggle concat-ing or "collecting" via M-x report-emacs-bug might get something moving. In the meantime you might want to try pre-compiling zshall(1). If I were to do that on my system for man, I'd do

$ mkdir -p /usr/share/man/cat1
$ PAGER=/bin/cat man zshall > /usr/share/man/cat1/zshall.1
$ MANPATH=/usr/share/man: man zshall

I'm sure it's easy enough to set the MANPATH when using "Man mode".

  1. Such a thing was handy when viewing large sets of documentation typeset in some flavor of roff. At least it was better than flipping through multiple three-ring binders.
nega
  • 3,091
  • 15
  • 21