{"id":210,"date":"2024-11-19T09:27:47","date_gmt":"2024-11-19T08:27:47","guid":{"rendered":"https:\/\/www.softwolves.com\/wolfblog\/?p=210"},"modified":"2024-11-19T22:01:23","modified_gmt":"2024-11-19T21:01:23","slug":"making-man-pages-easier-to-read","status":"publish","type":"post","link":"https:\/\/www.softwolves.com\/wolfblog\/2024\/11\/19\/making-man-pages-easier-to-read\/","title":{"rendered":"Making man pages easier to read"},"content":{"rendered":"\n

The abundance of man (short for manual<\/em>) pages in Unix and Linux systems is amazing, (almost) all commands are well-documented, and so are the programming APIs that a developer like me need to access on a daily basis. The only problem is that the default reader for them, the man<\/em> command, displays them as text in a terminal window.<\/p>\n\n\n\n

You can coerce the GNU man program to output manual pages as PostScript, however, but you need to feed that into a program that can display the PostScript. I use evince<\/em>, the GNOME Document Viewer, for that. Unfortunately, there is some sort of interoperability issue here that, at least on my installation, blocks copy-paste from the generated PostScript.<\/p>\n\n\n\n

I found that if I convert the PostScript to PDF using ps2pdf, copy-paste works. This is a lot to type to open a single manual page, however, so I ended up writing a script for it. Since I used to write a lot of Perl scripts earlier, the script also lets me look up the Perl manual using perldoc<\/em> (which can be told to output nroff, the input format for manual pages, so that it can then go through the whole chain and end up as PDF).<\/p>\n\n\n\n

This is what my little script has evolved to now. Since I have it running on several different machines, it does some detection of which software is installed, but it does need GNU man<\/em> and GNOME evince<\/em> at the very least (or you can replace it with the PS\/PDF viewer of your choice). If ps2pdf<\/em> is installed, it displays a PDF version for better interoperability. You can ask it for a manual page, to read perldoc from a file, or look up the perldoc manual by entering perldoc entry<\/em> as the parameters. YMMV.<\/p>\n\n\n

\n#!\/bin\/bash\n# gman: Display manual page as PDF\n# Written by Peter Krefting <peter AT softwolves.pp.se>\n# SPDX-License-Identifier: BSD-2-Clause\n\nif [ -z "$1" ]; then\n  echo "Usage: gman perldoc <page>"\n  echo "Usage: gman <file> | <manpage>..."\n  echo\n  echo "  Displays manual or perldoc documents as PDF"\n  echo "  <page>     Perldoc page to display"\n  echo "  <file>     File to open (perldoc or man)"\n  echo "  <manpage>  Manual page to display"\n  exit 0\nfi\n\nif [ -x \/usr\/bin\/mktemp ]; then\n  TEMPFILE="$(mktemp "$TMPDIR\/XXXXXXXXXX.ps")"\nelif [ -x \/usr\/bin\/tempfile ]; then\n  # Disable "tempfile is deprecated. Use mktemp instead", since we tried that...\n  # shellcheck disable=SC2186\n  TEMPFILE="$(tempfile --suffix .ps)"\nelse\n  echo 'FIXME: Unable to create temporary file!' >&2\n  exit 1\nfi\nif [ -f "$1" ]; then\n  # Perldoc on file, unless manual file\n  if [[ "$1" == *.[0-9]* ]]; then\n    man -Tps "$1" > "$TEMPFILE"\n  else\n    perldoc -onroff -d"$TEMPFILE.nroff" "$1"\n    man -Tps "$TEMPFILE.nroff" > "$TEMPFILE"\n    rm "$TEMPFILE.nroff"\n  fi\nelif [ "$1" = "perldoc" ]; then\n  # Perldoc manual\n  if [ -n "$3" ]; then\n    perldoc -onroff -d"$TEMPFILE.nroff" "$2" "$3"\n  else\n    perldoc -onroff -d"$TEMPFILE.nroff" "$2"\n  fi\n  man -Tps "$TEMPFILE.nroff" > "$TEMPFILE"\n  rm "$TEMPFILE.nroff"\nelse\n  # Assume manual page\n  man -Tps "$@" > "$TEMPFILE"\nfi\nif [ -x \/usr\/bin\/ps2pdf ]; then\n  ps2pdf "$TEMPFILE" "$TEMPFILE.pdf"\n  ( evince "$TEMPFILE.pdf" 2> \/dev\/null ; rm "$TEMPFILE.pdf" ) &\n  rm "$TEMPFILE"\nelse\n  ( evince "$TEMPFILE" 2> \/dev\/null ; rm "$TEMPFILE" ) &\nfi\n<\/pre><\/div>","protected":false},"excerpt":{"rendered":"
The abundance of man (short for manual) pages in Unix and Linux systems is amazing, (almost) all commands are well-documented, and so are the programming APIs that a developer like me need to access on a daily basis. The only problem is that the default reader for them, the man command, displays them as text […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7],"tags":[11,70],"class_list":["post-210","post","type-post","status-publish","format-standard","hentry","category-software","tag-linux","tag-script"],"_links":{"self":[{"href":"https:\/\/www.softwolves.com\/wolfblog\/wp-json\/wp\/v2\/posts\/210","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.softwolves.com\/wolfblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.softwolves.com\/wolfblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.softwolves.com\/wolfblog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.softwolves.com\/wolfblog\/wp-json\/wp\/v2\/comments?post=210"}],"version-history":[{"count":3,"href":"https:\/\/www.softwolves.com\/wolfblog\/wp-json\/wp\/v2\/posts\/210\/revisions"}],"predecessor-version":[{"id":213,"href":"https:\/\/www.softwolves.com\/wolfblog\/wp-json\/wp\/v2\/posts\/210\/revisions\/213"}],"wp:attachment":[{"href":"https:\/\/www.softwolves.com\/wolfblog\/wp-json\/wp\/v2\/media?parent=210"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.softwolves.com\/wolfblog\/wp-json\/wp\/v2\/categories?post=210"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.softwolves.com\/wolfblog\/wp-json\/wp\/v2\/tags?post=210"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}