readme

README.md

@@ -0,0 +1,69 @@
+# PDF Grid Generator Script
+
+This script takes a PDF file and arranges it into a grid of specified rows and columns, with an optional margin applied to each page. The final output is a centered and optionally cropped PDF.
+
+## Requirements
+
+Ensure the following programs are installed on your system:
+
+- **pdfjam**: A tool to manipulate PDF files, typically available via your package manager.
+- **pdfcrop**: A utility to crop PDF files, often included with TeX Live.
+- **pdfinfo**: A command-line utility to extract information from PDF files, part of the `poppler-utils` package.
+- **pdfcropmargins**: A Python package to adjust the margins of a PDF. It's recommended to install this using `pipx`.
+
+### Installing pdfcropmargins
+
+It's recommended to use `pipx` to install `pdfcropmargins` to avoid conflicts with your system Python packages:
+
+```bash
+pipx install pdfcropmargins
+```
+
+If you don't have `pipx` installed, you can install it with:
+
+```bash
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+```
+
+Or, alternatively, install `pdfcropmargins` directly with `pip` (not recommended):
+
+```bash
+pip install pdfcropmargins
+```
+
+## Usage
+
+To run the script, use the following command:
+
+```bash
+./pdf-jammer.sh input.pdf rows columns [margin]
+```
+
+### Arguments:
+
+- `input.pdf`: The path to the input PDF file.
+- `rows`: The number of rows in the output grid.
+- `columns`: The number of columns in the output grid.
+- `[margin]`: (Optional) The margin to apply around each page, in centimeters. Defaults to `0` if not provided.
+
+### Example:
+
+```bash
+./pdf-jammer.sh example.pdf 2 3 1
+```
+
+This command arranges the `example.pdf` into a grid of 2 rows and 3 columns with a 1 cm margin around each page.
+
+## Output
+
+The script generates a centered PDF with the filename `jammed.pdf` in the current directory.
+
+## Error Handling
+
+The script includes error checks to ensure the required programs are installed and that the `pdfjam` and `pdfcropmargins` commands succeed. If an error occurs, the script will exit early with a relevant message.
+
+## License
+
+This script is provided "as-is" without any warranty. Use it at your own risk.
+