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

{pdfmd_cli-3.18.0 → pdfmd_cli-3.20.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfmd-cli
-Version: 3.18.0
+Version: 3.20.4
 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
@@ -14,8 +14,17 @@ Classifier: Topic :: Text Processing :: Markup :: LaTeX
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+License-File: pdfmd_inkmd/LICENSE
+License-File: pdfmd_inkmd/assets/fonts/DejaVuSans-LICENSE.txt
 Requires-Dist: pyyaml
 Requires-Dist: pypdf
+Provides-Extra: math
+Requires-Dist: pymd2pdf<0.7,>=0.6; python_version >= "3.11" and extra == "math"
+Requires-Dist: matplotlib; extra == "math"
+Provides-Extra: emoji
+Requires-Dist: inkmd<0.6,>=0.5; extra == "emoji"
+Provides-Extra: pandoc
+Requires-Dist: pypandoc_binary; extra == "pandoc"
 Dynamic: license-file
 
 # pdfmd
@@ -78,9 +87,13 @@ To update later, run `pipx upgrade pdfmd-cli`. (The package is named
 The command is still `pdfmd`. For the latest unreleased code, use `pipx
 install git+https://github.com/aliperdehan/pdfmd`.)
 
-`pdfmd` drives programs that pip can't install, so you also need:
+For the full pipeline, `pdfmd` drives programs that pip can't install, so you
+also need (without them it still makes a plain PDF; see
+[No Pandoc?](#no-pandoc-the-built-in-fallback) below). The quickest way, with no
+admin rights, is `pdfmd --install full`, which puts Pandoc and Typst in pdfmd's own
+folders; the system installers below do the same job:
 
-- **[Pandoc](https://pandoc.org/installing.html)** (required)
+- **[Pandoc](https://pandoc.org/installing.html)**
 - **at least one PDF engine**. [Typst](https://typst.app) is the quickest
   start; a TeX distribution (MacTeX, TeX Live) gives the best results and
   is what you need for LaTeX packages and math-heavy documents.
@@ -111,7 +124,8 @@ Office files.
 <details>
 <summary>Without pipx</summary>
 
-`pdfmd.py` is a single file that needs Python 3.10+. It also runs
+`pdfmd.py` is a single file that needs Python 3.10+ (with `pdfmd_inkmd/`
+beside it for the no-Pandoc fallback). It also runs
 directly, and `pyyaml`/`pypdf` are optional (features that need them are
 skipped with a warning):
 
@@ -145,6 +159,63 @@ OK    quarto (only needed for .qmd files)  (/usr/local/bin/quarto)
 The numbers are the fallback order, and also shortcuts: `-e 6` means
 `-e typst`.
 
+### No Pandoc? The built-in fallback
+
+On a machine with no Pandoc, or Pandoc but no PDF engine, `pdfmd` does not
+stop: it builds a plain PDF with a pure-Python renderer that `pip` installed
+with it, and says so.
+
+```console
+$ pdfmd notes.md
+NOTE  Pandoc was not found: building with the built-in renderer (inkmd). The output is plain ...
+NATIVE  notes.md via inkmd
+WARN  native (inkmd): notes.md: 2 math expression(s) set as plain text (Unicode, sub/superscripts, display math centred); ...
+OK    notes.md
+```
+
+- **inkmd** is built in (vendored in `pdfmd_inkmd/`, about 2 MB, standard
+  library only, works offline, same input gives the same bytes). It reads
+  GitHub-flavoured Markdown: headings, emphasis, lists, task lists, tables,
+  code blocks, quotes, links, images, and PNG/JPEG. It cannot typeset math,
+  so formulas are set as readable text instead: Greek letters and operators
+  as Unicode, `x^2` and `x_i` as super/subscripts, `\frac{a}{b}` as `a/b`,
+  and display math (`$$...$$`, `\begin{equation}`, `aligned`) as its own
+  centred lines. No bookmarks, no page numbers.
+- **md2pdf** ([pymd2pdf](https://pypi.org/project/pymd2pdf/), ReportLab based) is
+  used when installed, for documents with footnotes, math or a title:
+  `pdfmd --install math` (same as `pip install "pdfmd-cli[math]"`; about
+  150 MB, Python 3.11+, installs matplotlib so formulas render offline, centred,
+  as real math; the few matplotlib cannot read are set as text like inkmd's).
+  Footnotes, bookmarks and syntax-highlighted code come with it.
+- `pdfmd --install emoji` (`pdfmd-cli[emoji]`, about 11 MB) adds the colour
+  emoji font; without it emoji print as `[rocket]`-style labels.
+- `pdfmd --install full` leaves the fallback behind: it installs **Pandoc** (the
+  real binary from PyPI's `pypandoc_binary`, about 35 MB, also `--install pandoc`
+  / `pdfmd-cli[pandoc]`) and **Typst** (Typst's own release from GitHub, about
+  15 MB, also `--install typst`, checked against the SHA-256 GitHub lists) into
+  pdfmd's own folders (`~/.local/share/pdfmd/bin`, `%LOCALAPPDATA%\pdfmd\bin`),
+  with no admin rights. A Pandoc or Typst already on your PATH always wins; to
+  remove them, `pip uninstall pypandoc_binary` and delete the `typst` file.
+
+Every input is treated as GitHub-flavoured Markdown. Pandoc-only syntax is
+converted where possible (`\newpage` and `<!-- pagebreak -->` become a page
+break, footnotes become endnotes for inkmd, `$` prices are not mistaken for math)
+and removed otherwise (heading and image attributes, `:::` divs, raw LaTeX,
+`<!-- comments -->`), with one warning per kind. CSV tables
+(`::: {.csv file="data.csv"}`) work as they do with Pandoc. The title, author and date in the
+front matter become a title block and the PDF's own title and author; other
+front-matter keys (`documentclass`, `header-includes`, `pdfmd-options`) are
+listed as not used. There are no filters, preambles, citations, slides, parts or
+report mode, and only Markdown input: for any of those, `pdfmd --install full`
+(or `brew install pandoc typst`, `winget install JohnMacFarlane.Pandoc Typst.Typst`).
+
+The built-in renderer is chosen automatically only when there is no Pandoc
+route; a Pandoc build that fails never falls back to it. Ask for it with
+`-e inkmd`, `-e md2pdf` or `-e native`, or `pdf-engine: inkmd` in `pdfmd-options`.
+When it runs on a terminal and had to leave something out, `pdfmd` offers the
+upgrades above (set `PDFMD_NO_PROMPT=1` to silence that; choosing "don't ask
+again" remembers it).
+
 ## Usage
 
 Every command below can be run from inside [`examples/`](https://github.com/aliperdehan/pdfmd/tree/main/examples/).
@@ -172,6 +243,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

pdfmd_cli-3.18.0/pdfmd_cli.egg-info/PKG-INFO → pdfmd_cli-3.20.4/README.md

@@ -1,23 +1,3 @@
-Metadata-Version: 2.4
-Name: pdfmd-cli
-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
-Project-URL: Homepage, https://github.com/aliperdehan/pdfmd
-Project-URL: Changelog, https://github.com/aliperdehan/pdfmd/blob/main/CHANGELOG.md
-Keywords: pandoc,markdown,pdf,latex,cli
-Classifier: Environment :: Console
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Text Processing :: Markup :: Markdown
-Classifier: Topic :: Text Processing :: Markup :: LaTeX
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pyyaml
-Requires-Dist: pypdf
-Dynamic: license-file
-
 # pdfmd
 
 [![Test](https://github.com/aliperdehan/pdfmd/actions/workflows/publish.yml/badge.svg)](https://github.com/aliperdehan/pdfmd/actions/workflows/publish.yml) [![PyPI](https://img.shields.io/pypi/v/pdfmd-cli)](https://pypi.org/project/pdfmd-cli/)
@@ -78,9 +58,13 @@ To update later, run `pipx upgrade pdfmd-cli`. (The package is named
 The command is still `pdfmd`. For the latest unreleased code, use `pipx
 install git+https://github.com/aliperdehan/pdfmd`.)
 
-`pdfmd` drives programs that pip can't install, so you also need:
+For the full pipeline, `pdfmd` drives programs that pip can't install, so you
+also need (without them it still makes a plain PDF; see
+[No Pandoc?](#no-pandoc-the-built-in-fallback) below). The quickest way, with no
+admin rights, is `pdfmd --install full`, which puts Pandoc and Typst in pdfmd's own
+folders; the system installers below do the same job:
 
-- **[Pandoc](https://pandoc.org/installing.html)** (required)
+- **[Pandoc](https://pandoc.org/installing.html)**
 - **at least one PDF engine**. [Typst](https://typst.app) is the quickest
   start; a TeX distribution (MacTeX, TeX Live) gives the best results and
   is what you need for LaTeX packages and math-heavy documents.
@@ -111,7 +95,8 @@ Office files.
 <details>
 <summary>Without pipx</summary>
 
-`pdfmd.py` is a single file that needs Python 3.10+. It also runs
+`pdfmd.py` is a single file that needs Python 3.10+ (with `pdfmd_inkmd/`
+beside it for the no-Pandoc fallback). It also runs
 directly, and `pyyaml`/`pypdf` are optional (features that need them are
 skipped with a warning):
 
@@ -145,6 +130,63 @@ OK    quarto (only needed for .qmd files)  (/usr/local/bin/quarto)
 The numbers are the fallback order, and also shortcuts: `-e 6` means
 `-e typst`.
 
+### No Pandoc? The built-in fallback
+
+On a machine with no Pandoc, or Pandoc but no PDF engine, `pdfmd` does not
+stop: it builds a plain PDF with a pure-Python renderer that `pip` installed
+with it, and says so.
+
+```console
+$ pdfmd notes.md
+NOTE  Pandoc was not found: building with the built-in renderer (inkmd). The output is plain ...
+NATIVE  notes.md via inkmd
+WARN  native (inkmd): notes.md: 2 math expression(s) set as plain text (Unicode, sub/superscripts, display math centred); ...
+OK    notes.md
+```
+
+- **inkmd** is built in (vendored in `pdfmd_inkmd/`, about 2 MB, standard
+  library only, works offline, same input gives the same bytes). It reads
+  GitHub-flavoured Markdown: headings, emphasis, lists, task lists, tables,
+  code blocks, quotes, links, images, and PNG/JPEG. It cannot typeset math,
+  so formulas are set as readable text instead: Greek letters and operators
+  as Unicode, `x^2` and `x_i` as super/subscripts, `\frac{a}{b}` as `a/b`,
+  and display math (`$$...$$`, `\begin{equation}`, `aligned`) as its own
+  centred lines. No bookmarks, no page numbers.
+- **md2pdf** ([pymd2pdf](https://pypi.org/project/pymd2pdf/), ReportLab based) is
+  used when installed, for documents with footnotes, math or a title:
+  `pdfmd --install math` (same as `pip install "pdfmd-cli[math]"`; about
+  150 MB, Python 3.11+, installs matplotlib so formulas render offline, centred,
+  as real math; the few matplotlib cannot read are set as text like inkmd's).
+  Footnotes, bookmarks and syntax-highlighted code come with it.
+- `pdfmd --install emoji` (`pdfmd-cli[emoji]`, about 11 MB) adds the colour
+  emoji font; without it emoji print as `[rocket]`-style labels.
+- `pdfmd --install full` leaves the fallback behind: it installs **Pandoc** (the
+  real binary from PyPI's `pypandoc_binary`, about 35 MB, also `--install pandoc`
+  / `pdfmd-cli[pandoc]`) and **Typst** (Typst's own release from GitHub, about
+  15 MB, also `--install typst`, checked against the SHA-256 GitHub lists) into
+  pdfmd's own folders (`~/.local/share/pdfmd/bin`, `%LOCALAPPDATA%\pdfmd\bin`),
+  with no admin rights. A Pandoc or Typst already on your PATH always wins; to
+  remove them, `pip uninstall pypandoc_binary` and delete the `typst` file.
+
+Every input is treated as GitHub-flavoured Markdown. Pandoc-only syntax is
+converted where possible (`\newpage` and `<!-- pagebreak -->` become a page
+break, footnotes become endnotes for inkmd, `$` prices are not mistaken for math)
+and removed otherwise (heading and image attributes, `:::` divs, raw LaTeX,
+`<!-- comments -->`), with one warning per kind. CSV tables
+(`::: {.csv file="data.csv"}`) work as they do with Pandoc. The title, author and date in the
+front matter become a title block and the PDF's own title and author; other
+front-matter keys (`documentclass`, `header-includes`, `pdfmd-options`) are
+listed as not used. There are no filters, preambles, citations, slides, parts or
+report mode, and only Markdown input: for any of those, `pdfmd --install full`
+(or `brew install pandoc typst`, `winget install JohnMacFarlane.Pandoc Typst.Typst`).
+
+The built-in renderer is chosen automatically only when there is no Pandoc
+route; a Pandoc build that fails never falls back to it. Ask for it with
+`-e inkmd`, `-e md2pdf` or `-e native`, or `pdf-engine: inkmd` in `pdfmd-options`.
+When it runs on a terminal and had to leave something out, `pdfmd` offers the
+upgrades above (set `PDFMD_NO_PROMPT=1` to silence that; choosing "don't ask
+again" remembers it).
+
 ## Usage
 
 Every command below can be run from inside [`examples/`](https://github.com/aliperdehan/pdfmd/tree/main/examples/).
@@ -172,6 +214,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