pdfmd-cli 3.15.0__tar.gz → 3.18.0__tar.gz

{pdfmd_cli-3.15.0/pdfmd_cli.egg-info → pdfmd_cli-3.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfmd-cli
-Version: 3.15.0
+Version: 3.18.0
 Summary: One command from Markdown to a good-looking PDF: a Pandoc wrapper with smart defaults, project-file discovery and a multi-engine fallback chain
 Author: Ali Perdekhan
 License-Expression: MIT
@@ -213,6 +213,64 @@ into a single PDF, in the order of each file's `chapter:` front-matter
 field. See [`examples/book/`](https://github.com/aliperdehan/pdfmd/tree/main/examples/book/). `-i FILE` leaves one file
 out, and `--exclude-unnumbered` skips files without a `chapter:`.
 
+### One long document in several files
+
+For an article-style document that has grown too long to edit as one file
+(and unlike `-r`, one that should read as a single document, not a
+sequence of chapters), keep a *scaffold* with the front matter, and the
+text in a `parts/` folder beside it, one file per section, each starting with
+its own heading:
+
+```
+report.md                    front matter only (title, author, ...)
+parts/10-introduction.md
+parts/20-methods.md
+parts/30-discussion.md
+```
+
+Switch it on once, in a `metadata.yaml` shared by your documents, so the
+content files carry no typesetting:
+
+```yaml
+pdfmd-options:
+  parts: auto        # a document is a scaffold only if parts/ or sections/ exists
+```
+
+```console
+$ pdfmd report                  # the whole document, report.pdf
+$ pdfmd report#methods          # just that part, report.methods.pdf
+$ pdfmd report#discussion+appendix      # several: always in report order
+$ pdfmd parts/20-methods.md     # same as report#methods
+$ pdfmd report --list-parts
+$ pdfmd old-report.md --split new-folder   # cut an existing single file into parts
+$ pdfmd old-report.md --split new-folder --split-depth 2   # ...and subsections too
+```
+
+The parts are joined in filename order into one Pandoc run, so the result is
+identical to the same text in a single file: labels, citations and numbering
+work across parts, and paths are written relative to the scaffold's folder
+whichever part they are in. A part rebuilt alone is much faster to compile
+but cannot see the others, so references to them print as `??`. See
+[`examples/parts/`](https://github.com/aliperdehan/pdfmd/tree/main/examples/parts/).
+
+#### Faster rebuilds: the cache
+
+```yaml
+pdfmd-options:
+  cache: {aux: true}      # or: pdfmd report --cache
+```
+
+keeps LaTeX's cross-reference files between builds (in `~/.cache/pdfmd`), so
+an unchanged document is typeset once instead of two or three times, and a
+part built on its own shows the real numbers of the parts left out (taken
+from the last full build) instead of `??`. It never skips a build: Pandoc and
+LaTeX still process the whole document from the current sources and package
+every time, so a change shows in the next build. `cache: {plots: true}` (or
+`--cache-plots`, with nulabreport >= 1.26.0) additionally stores each plot as a
+PDF and reuses it until the package, the preamble, the engine or the plot's
+data file changes. Off by default; `--no-cache` for one build; `pdfmd --clear-cache`
+(or deleting the folder) is always safe.
+
 ### Tables straight from a CSV file
 
 ```markdown

{pdfmd_cli-3.15.0 → pdfmd_cli-3.18.0}/README.md

@@ -193,6 +193,64 @@ into a single PDF, in the order of each file's `chapter:` front-matter
 field. See [`examples/book/`](https://github.com/aliperdehan/pdfmd/tree/main/examples/book/). `-i FILE` leaves one file
 out, and `--exclude-unnumbered` skips files without a `chapter:`.
 
+### One long document in several files
+
+For an article-style document that has grown too long to edit as one file
+(and unlike `-r`, one that should read as a single document, not a
+sequence of chapters), keep a *scaffold* with the front matter, and the
+text in a `parts/` folder beside it, one file per section, each starting with
+its own heading:
+
+```
+report.md                    front matter only (title, author, ...)
+parts/10-introduction.md
+parts/20-methods.md
+parts/30-discussion.md
+```
+
+Switch it on once, in a `metadata.yaml` shared by your documents, so the
+content files carry no typesetting:
+
+```yaml
+pdfmd-options:
+  parts: auto        # a document is a scaffold only if parts/ or sections/ exists
+```
+
+```console
+$ pdfmd report                  # the whole document, report.pdf
+$ pdfmd report#methods          # just that part, report.methods.pdf
+$ pdfmd report#discussion+appendix      # several: always in report order
+$ pdfmd parts/20-methods.md     # same as report#methods
+$ pdfmd report --list-parts
+$ pdfmd old-report.md --split new-folder   # cut an existing single file into parts
+$ pdfmd old-report.md --split new-folder --split-depth 2   # ...and subsections too
+```
+
+The parts are joined in filename order into one Pandoc run, so the result is
+identical to the same text in a single file: labels, citations and numbering
+work across parts, and paths are written relative to the scaffold's folder
+whichever part they are in. A part rebuilt alone is much faster to compile
+but cannot see the others, so references to them print as `??`. See
+[`examples/parts/`](https://github.com/aliperdehan/pdfmd/tree/main/examples/parts/).
+
+#### Faster rebuilds: the cache
+
+```yaml
+pdfmd-options:
+  cache: {aux: true}      # or: pdfmd report --cache
+```
+
+keeps LaTeX's cross-reference files between builds (in `~/.cache/pdfmd`), so
+an unchanged document is typeset once instead of two or three times, and a
+part built on its own shows the real numbers of the parts left out (taken
+from the last full build) instead of `??`. It never skips a build: Pandoc and
+LaTeX still process the whole document from the current sources and package
+every time, so a change shows in the next build. `cache: {plots: true}` (or
+`--cache-plots`, with nulabreport >= 1.26.0) additionally stores each plot as a
+PDF and reuses it until the package, the preamble, the engine or the plot's
+data file changes. Off by default; `--no-cache` for one build; `pdfmd --clear-cache`
+(or deleting the folder) is always safe.
+
 ### Tables straight from a CSV file
 
 ```markdown