pdfmd-cli 3.15.1__tar.gz → 3.19.8__tar.gz

{pdfmd_cli-3.15.1/pdfmd_cli.egg-info → pdfmd_cli-3.19.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfmd-cli
-Version: 3.15.1
+Version: 3.19.8
 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
@@ -172,6 +172,75 @@ pdfmd lecture --to typst -o lecture.typ
 pdfmd lecture -o lecture.tex      # a complete, compilable .tex, not a fragment
 ```
 
+### Stopping part-way
+
+`--stop-at` ends the build after a stage; everything before it runs as normal:
+
+```sh
+pdfmd report --stop-at markdown   # report.assembled.md: the parts joined into one file
+pdfmd report --assemble-only      # the same, shorter
+pdfmd report --stop-at tex        # the standalone .tex a LaTeX engine would get (= --to latex)
+```
+
+The assembled file holds just the document text (and is marked
+`pdfmd-assembled: true`), so pdfmd never joins its parts a second time.
+
+By default it holds just the text. `--embed-metadata` also folds in what pdfmd
+finds beside the document (metadata, preamble, Lua filters, and the
+bibliography and CSL files the metadata names), so the file no longer needs
+them beside it. What the text points at otherwise (images, files a preamble
+`\input`s) is not embedded: keep it where the document finds it, relative to
+the assembled file.
+
+```sh
+pdfmd report --assemble-only --embed-metadata                  # metadata.yaml, preamble.tex, Lua filters, .bib/.csl
+pdfmd report --assemble-only --embed-metadata metadata preamble   # only those
+pdfmd report --assemble-only --embed-metadata --lua-mode ref   # name the filter instead of copying it
+```
+
+An embedded Lua filter sits in a `{=pdfmd}` block at the end of the file. A
+Lua filter can run any command, so one only runs if this machine's pdfmd
+embedded it (otherwise it is skipped with a warning, unless you pass
+`--trust-embedded`).
+
+`--lua-mode apply` runs the filters at assembly time instead, so the text
+already has their effect (approximate: Pandoc re-writes the text, and a filter
+that looks at `FORMAT` is embedded instead). `--unpack` goes the other way:
+
+```sh
+pdfmd report.assembled.md --unpack     # filters, preamble and metadata back into report.assembled.unpacked/
+```
+
+`pdfmd` finds `report.assembled.unpacked/` beside `report.assembled.md` by
+itself (its metadata, preambles and Lua filters), and `--unpack --slim` strips
+the unpacked parts out of the assembled file, leaving the lean document plus
+that folder.
+
+A document can name its own files and set what to embed, in `pdfmd-options`:
+
+```yaml
+pdfmd-options:
+  yaml: [base.yaml]        # metadata files (like -y); also `metadata:`, or grouped:
+  metadata:
+    preamble: my-preamble.tex
+    lua-filter: my.lua
+  embed: {lua: ref}        # what --assemble-only embeds without the flag
+```
+
+Plain HTML output is a fragment. For a finished page, or one file with
+everything (images, CSS) inlined, ask for it, on the command line or in the
+document:
+
+```sh
+pdfmd lecture -o lecture.html --self-contained
+```
+
+```yaml
+pdfmd-options:
+  default-output: html     # build to HTML when no format is given
+  html: {self-contained: true, css: style.css}
+```
+
 ### Slides
 
 ```sh
@@ -213,6 +282,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.1 → pdfmd_cli-3.19.8}/README.md

@@ -152,6 +152,75 @@ pdfmd lecture --to typst -o lecture.typ
 pdfmd lecture -o lecture.tex      # a complete, compilable .tex, not a fragment
 ```
 
+### Stopping part-way
+
+`--stop-at` ends the build after a stage; everything before it runs as normal:
+
+```sh
+pdfmd report --stop-at markdown   # report.assembled.md: the parts joined into one file
+pdfmd report --assemble-only      # the same, shorter
+pdfmd report --stop-at tex        # the standalone .tex a LaTeX engine would get (= --to latex)
+```
+
+The assembled file holds just the document text (and is marked
+`pdfmd-assembled: true`), so pdfmd never joins its parts a second time.
+
+By default it holds just the text. `--embed-metadata` also folds in what pdfmd
+finds beside the document (metadata, preamble, Lua filters, and the
+bibliography and CSL files the metadata names), so the file no longer needs
+them beside it. What the text points at otherwise (images, files a preamble
+`\input`s) is not embedded: keep it where the document finds it, relative to
+the assembled file.
+
+```sh
+pdfmd report --assemble-only --embed-metadata                  # metadata.yaml, preamble.tex, Lua filters, .bib/.csl
+pdfmd report --assemble-only --embed-metadata metadata preamble   # only those
+pdfmd report --assemble-only --embed-metadata --lua-mode ref   # name the filter instead of copying it
+```
+
+An embedded Lua filter sits in a `{=pdfmd}` block at the end of the file. A
+Lua filter can run any command, so one only runs if this machine's pdfmd
+embedded it (otherwise it is skipped with a warning, unless you pass
+`--trust-embedded`).
+
+`--lua-mode apply` runs the filters at assembly time instead, so the text
+already has their effect (approximate: Pandoc re-writes the text, and a filter
+that looks at `FORMAT` is embedded instead). `--unpack` goes the other way:
+
+```sh
+pdfmd report.assembled.md --unpack     # filters, preamble and metadata back into report.assembled.unpacked/
+```
+
+`pdfmd` finds `report.assembled.unpacked/` beside `report.assembled.md` by
+itself (its metadata, preambles and Lua filters), and `--unpack --slim` strips
+the unpacked parts out of the assembled file, leaving the lean document plus
+that folder.
+
+A document can name its own files and set what to embed, in `pdfmd-options`:
+
+```yaml
+pdfmd-options:
+  yaml: [base.yaml]        # metadata files (like -y); also `metadata:`, or grouped:
+  metadata:
+    preamble: my-preamble.tex
+    lua-filter: my.lua
+  embed: {lua: ref}        # what --assemble-only embeds without the flag
+```
+
+Plain HTML output is a fragment. For a finished page, or one file with
+everything (images, CSS) inlined, ask for it, on the command line or in the
+document:
+
+```sh
+pdfmd lecture -o lecture.html --self-contained
+```
+
+```yaml
+pdfmd-options:
+  default-output: html     # build to HTML when no format is given
+  html: {self-contained: true, css: style.css}
+```
+
 ### Slides
 
 ```sh
@@ -193,6 +262,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