diff --git a/docs/exporter.md b/docs/exporter.md index d577d4e..7e66bda 100644 --- a/docs/exporter.md +++ b/docs/exporter.md @@ -26,7 +26,31 @@ python3 tools/exporter.py presentation.pptx --output pdf --target-size 5MB python3 tools/exporter.py document.pdf --output pdf --pdf-quality email --target-size 5MB ``` -Compression requires **Ghostscript** (`gs` on `PATH`). `--dpi` only controls PNG +Compression requires **Ghostscript**. Its package is generally named +`ghostscript`, while the executable placed on `PATH` is named `gs`: + +```sh +# Debian / Ubuntu +sudo apt install ghostscript + +# Fedora / RHEL +sudo dnf install ghostscript + +# Arch Linux +sudo pacman -S ghostscript + +# openSUSE +sudo zypper install ghostscript + +# Alpine Linux +sudo apk add ghostscript + +# macOS with Homebrew +brew install ghostscript +``` + +These commands are also shown by `python3 tools/exporter.py --help` and in the +error displayed when compression is requested without `gs`. `--dpi` only controls PNG resolution. `--pdf-quality` controls PDF image downsampling: | Quality | Image resolution | diff --git a/tests/test_exporter.py b/tests/test_exporter.py index fc23543..f178b88 100644 --- a/tests/test_exporter.py +++ b/tests/test_exporter.py @@ -173,6 +173,19 @@ class ExporterTests(unittest.TestCase): self.assertEqual(self.invoke(source, '--output', 'pdf', '--pdf-quality', 'email'), 1) self.assertFalse((self.root / 'input_export').exists()) + def test_help_lists_ghostscript_package_and_install_commands(self): + output = io.StringIO() + with contextlib.redirect_stdout(output), self.assertRaises(SystemExit) as error: + exporter.main(['--help']) + self.assertEqual(error.exception.code, 0) + help_text = output.getvalue() + self.assertIn('ghostscript` package', help_text) + self.assertIn('sudo apt install ghostscript', help_text) + self.assertIn('sudo dnf install ghostscript', help_text) + self.assertIn('sudo pacman -S ghostscript', help_text) + self.assertIn('sudo zypper install ghostscript', help_text) + self.assertIn('sudo apk add ghostscript', help_text) + def test_size_units_and_pdf_option_validation(self): self.assertEqual(exporter.byte_size('2.5MB'), 2500000) self.assertEqual(exporter.byte_size('2MiB'), 2097152) diff --git a/tools/exporter.py b/tools/exporter.py index 1d8fc4a..8a0ee42 100644 --- a/tools/exporter.py +++ b/tools/exporter.py @@ -17,6 +17,15 @@ else: from progress import Progress, status +GHOSTSCRIPT_INSTALL_HELP = '''Ghostscript is installed as the `ghostscript` package; its command is `gs`: + Debian / Ubuntu: sudo apt install ghostscript + Fedora / RHEL: sudo dnf install ghostscript + Arch Linux: sudo pacman -S ghostscript + openSUSE: sudo zypper install ghostscript + Alpine Linux: sudo apk add ghostscript + macOS (Homebrew): brew install ghostscript''' + + def output_formats(value): formats = list(dict.fromkeys(item.strip().lower() for item in value.split(','))) if any(item not in ('pdf', 'images') for item in formats): @@ -52,7 +61,7 @@ def compress_pdf(source, work, quality, target_size): return source gs = shutil.which('gs') if not gs: - raise RuntimeError('PDF compression requires Ghostscript (gs). Install Ghostscript and retry.') + raise RuntimeError('PDF compression requires Ghostscript (`gs`).\n' + GHOSTSCRIPT_INSTALL_HELP) first_dpi = {'original': 300, 'print': 300, 'email': 150, 'screen': 72}[quality] resolutions = [first_dpi] if target_size: @@ -216,7 +225,9 @@ def export(source, formats, destination, dpi, overwrite, cli_override, progress= def main(argv=None): - parser = argparse.ArgumentParser(description=__doc__) + parser = argparse.ArgumentParser( + description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter, + epilog='PDF compression dependency:\n' + GHOSTSCRIPT_INSTALL_HELP) parser.add_argument('file', type=Path, help='Source .pptx or .pdf') parser.add_argument('--output', required=True, type=output_formats, metavar='pdf,images', help='Comma-separated output formats: pdf, images')