README.md

   1 # pdfman: View UNIX manual pages as Portable Document Format (PDF) files
   2
   3 `pdfman` converts UNIX manual pages to PDF documents using Ghostscript's
   4 `ps2pdf`(1) or Apple's `pstopdf`(1) command (included in macOS up to version 13
   5 "Ventura") and displays them by calling `xdg-open`(1) or `open`(1) on the
   6 resulting PDF file.
   7 This enhances the useability of the manual pages quite a bit, because you now
   8 can make use of your preferred PDF file viewer and all of its functionality.
   9
  10 The conversion is only done once and a cached PDF file gets used for subsequent
  11 invocations for the same topic.
  12
  13 ## Prerequisites
  14
  15 The `pdfman` script makes use of the following tools, which need to be available
  16 on the local system in the default search `$PATH`:
  17
  18 - `xdg-open`(1) _or_ `open`(1).
  19 - Either `ps2pdf`(1) of the Ghostscript suite _or_ `pstopdf`(1) which was
  20   included in Apple macOS up to version 13 "Ventura".
  21
  22 Note: `pdfman` silently falls back to "normal" `man`(1) behavior if any of the
  23 required tools is _not_ found.
  24
  25 ## Usage
  26
  27 ```bash
  28 pdfman [-v] [-T] [<section>] <topic> ...
  29 pdfman <man(1) options> <arguments> ...
  30 pdfman {--help|--version>}
  31 ```
  32
  33 - `-v`: Enable verbose output.
  34 - `-T`: Force regular `man`(1) behavior, don't use PDF files.
  35
  36 ### Hint
  37
  38 You can setup an alias from `man` to `pdfman` in your shell startup files to not
  39 forget to use it :-)
  40
  41 ```bash
  42 alias man=pdfman
  43 ```