Document Ghostscript installation in exporter help

This commit is contained in:
Dandaedre 2026-10-20 12:07:59 +02:00
parent 76050c2f28
commit 3f0c13a004
3 changed files with 51 additions and 3 deletions

View File

@ -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 |

View File

@ -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)

View File

@ -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')