brewdoc 0.4.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +66 -40
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -3,40 +3,46 @@
3
3
  [![PyPI](https://img.shields.io/pypi/v/brewdoc)](https://pypi.org/project/brewdoc/)
4
4
  [![CI](https://github.com/kochetkov-ma/brewdoc/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kochetkov-ma/brewdoc/actions/workflows/ci.yml)
5
5
  [![Release](https://img.shields.io/github/v/release/kochetkov-ma/brewdoc)](https://github.com/kochetkov-ma/brewdoc/releases/latest)
6
- [![MIT](https://img.shields.io/github/license/kochetkov-ma/brewdoc)](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/LICENSE)
6
+ [![MIT](https://img.shields.io/github/license/kochetkov-ma/brewdoc)](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/LICENSE)
7
7
 
8
8
  Fast, deterministic document-to-Markdown conversion for agent systems. Easy to install. No model weights, OCR or external services.
9
9
 
10
10
  Local conversion runs offline after installation, with no runtime component downloads.
11
11
  Supported documents become one Markdown file and a JSON receipt describing omissions.
12
- See [formats and limits](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/FORMATS.md).
13
- Version 0.4.1 adds [selected ZIP/XML reader budgets](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/FORMATS.md#zipxml-reader-limits)
12
+ See [formats and limits](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/FORMATS.md).
13
+ Version 0.4.1 added [selected ZIP/XML reader budgets](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/FORMATS.md#zipxml-reader-limits)
14
14
  for DOCX/PPTX and workbook metadata/artifacts. Excessive work refuses before output
15
15
  writes; native workbook values and total process memory remain outside those bounds.
16
16
 
17
- ## Install
17
+ Version 0.5.0 added ODT/ODP text and tables, selected MIME email bodies and exact UTF-8
18
+ Markdown/text pass-through. It preserved workbook Unicode and exposed datetime precision,
19
+ and selected one DOCX compatibility fallback.
20
+ It also added textless PDF page facts and selected caption, table and math-spacing fixes.
21
+ Version 0.6.0 writes cleaner Markdown with minimal escaping, adds `--body-only`, accepts
22
+ documents through `--url`, decodes legacy HTML charsets and falls back to the whole page in
23
+ article mode.
18
24
 
19
- These examples select 0.4.1. Use a channel listed as available in [that release](https://github.com/kochetkov-ma/brewdoc/releases/tag/v0.4.1). Choose one method:
25
+ ## Install
20
26
 
21
- Article mode is introduced in 0.4.0. Channel availability is listed in the release.
27
+ These examples select 0.6.0. Use a channel listed as available in [that release](https://github.com/kochetkov-ma/brewdoc/releases/tag/v0.6.0). Choose one method:
22
28
 
23
29
  ```sh
24
- python -m pip install "brewdoc==0.4.1"
25
- uv tool install --python 3.12 "brewdoc==0.4.1"
26
- pipx install --python 3.12 "brewdoc==0.4.1"
30
+ python -m pip install "brewdoc==0.6.0"
31
+ uv tool install --python 3.12 "brewdoc==0.6.0"
32
+ pipx install --python 3.12 "brewdoc==0.6.0"
27
33
  ```
28
34
 
29
- Use a virtual environment for pip. Python 3.12+ is required; HTML/URL need CPython 3.12-3.14.
30
- [INSTALL.md](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/INSTALL.md) covers prerequisites, Windows, uvx, PATH, update and removal.
35
+ Use a virtual environment for pip. Python 3.12+ is required; local and URL HTML need CPython 3.12-3.14.
36
+ [INSTALL.md](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/INSTALL.md) covers prerequisites, Windows, uvx, PATH, update and removal.
31
37
  [Latest release](https://github.com/kochetkov-ma/brewdoc/releases/latest) lists actual assets and channel availability.
32
38
 
33
39
  ### Standalone downloads
34
40
 
35
- Use downloads listed as available in the release. Python and dependencies are bundled. Verify [SHA256SUMS](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.4.1/SHA256SUMS) and keep the entire extracted directory.
41
+ Use downloads listed as available in the release. Python and dependencies are bundled. Verify [SHA256SUMS](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.6.0/SHA256SUMS) and keep the entire extracted directory.
36
42
 
37
- [![Linux x64 download](https://img.shields.io/badge/Linux_x64-download-blue)](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.4.1/brewdoc-0.4.1-linux-x64.tar.gz)
38
- [![Windows x64 download](https://img.shields.io/badge/Windows_x64-download-blue)](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.4.1/brewdoc-0.4.1-windows-x64.zip)
39
- [![macOS ARM64 download](https://img.shields.io/badge/macOS_ARM64-download-blue)](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.4.1/brewdoc-0.4.1-macos-arm64.tar.gz)
43
+ [![Linux x64 download](https://img.shields.io/badge/Linux_x64-download-blue)](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.6.0/brewdoc-0.6.0-linux-x64.tar.gz)
44
+ [![Windows x64 download](https://img.shields.io/badge/Windows_x64-download-blue)](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.6.0/brewdoc-0.6.0-windows-x64.zip)
45
+ [![macOS ARM64 download](https://img.shields.io/badge/macOS_ARM64-download-blue)](https://github.com/kochetkov-ma/brewdoc/releases/download/v0.6.0/brewdoc-0.6.0-macos-arm64.tar.gz)
40
46
 
41
47
  | Native target | Verification environment | JavaScript |
42
48
  |---|---|---|
@@ -46,20 +52,27 @@ Use downloads listed as available in the release. Python and dependencies are bu
46
52
 
47
53
  Older OSes, Linux musl/ARM64 and macOS Intel are outside this binary set.
48
54
  Windows is unsigned; macOS has an ad hoc signature without Developer ID/notarization.
49
- Linux archives have checksums, without a detached publisher signature. [Download and launch](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/INSTALL.md#standalone).
55
+ Linux archives have checksums, without a detached publisher signature. [Download and launch](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/INSTALL.md#standalone).
50
56
 
51
57
  ### npm
52
58
 
53
59
  [![npm](https://img.shields.io/npm/v/brewdoc)](https://www.npmjs.com/package/brewdoc)
54
60
 
55
61
  npm targets Linux x64/glibc and macOS ARM64. Windows uses the GitHub native download or Python package.
56
- Use npm/npx only when listed as available in [the release](https://github.com/kochetkov-ma/brewdoc/releases/tag/v0.4.1).
57
- [INSTALL.md](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/INSTALL.md#npm-and-npx) contains exact-version installation, update and removal instructions.
62
+ Use npm/npx only when listed as available in [the release](https://github.com/kochetkov-ma/brewdoc/releases/tag/v0.6.0).
63
+ [INSTALL.md](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/INSTALL.md#npm-and-npx) contains exact-version installation, update and removal instructions.
64
+
65
+ ### Homebrew
66
+
67
+ Use `kochetkov-ma/brew/brewdoc` only when the release lists it as available.
68
+ It installs the complete native bundle on macOS 15+ ARM64 or Linux x64 with system
69
+ glibc 2.35+. See [installation and lifecycle](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/INSTALL.md#homebrew).
58
70
 
59
71
  ## Usage
60
72
 
61
73
  ```sh
62
74
  brewdoc file.pdf --out file.md
75
+ brewdoc --body-only paper.pdf --out paper.md
63
76
  brewdoc book.epub --out book.md
64
77
  brewdoc file.xlsx --sheet Calc --sheet Inputs --out book.md
65
78
  brewdoc file.xlsm --artifact formula/sheet/000002=formulas.json
@@ -71,15 +84,24 @@ brewdoc --self-check
71
84
  caller order retains full-workbook ordinals. Artifact keys come from the Markdown artifact table.
72
85
  Requests and output collisions are validated before writes. Paths resolve against the caller's directory;
73
86
  `--out` creates parents. Refusal preserves existing output. Self-check is offline and has its own output.
87
+ `--body-only` drops the title, metadata, omissions, contents and unit anchors; unit headings stay
88
+ only for several units. The receipt is unchanged. See [body-only output](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/FORMATS.md#body-only-output).
74
89
 
75
90
  ## Markdown and receipts
76
91
 
77
- Successful output uses `brewdoc.markdown/2`: quoted source title, Metadata, Artifacts,
92
+ Parsed document output uses `brewdoc.markdown/2`: quoted source title, Metadata, Artifacts,
78
93
  Known omissions, Contents, then anchored units. PDF uses `page/000001`, workbooks `sheet/000001`,
79
- PPTX `slide/000001`, and DOCX/EPUB/HTML `chapter/000001`. Empty declared units remain navigable.
94
+ PPTX/ODP `slide/000001`, and DOCX/EPUB/HTML/ODT/EML `chapter/000001`.
95
+ Empty declared units remain navigable. Escaping is minimal; HTML, EPUB and EML omit form
96
+ controls and write images with alt text as `![alt](src)`. See [Markdown escaping](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/FORMATS.md#markdown-escaping).
80
97
  Metadata holds source/selection/content hashes, conversion tallies and artifact capabilities;
81
98
  it excludes paths, timestamps, permissions and host data. EPUB retains declared publication metadata.
82
99
 
100
+ UTF-8 `.md` and `.txt` use `brewdoc.markdown/passthrough/1`: exact source bytes with
101
+ no generated envelope, contents or anchors. BOM, whitespace, newline variants and absent
102
+ final newline survive; empty input succeeds. The receipt reports route `text`, kind `none`
103
+ and zero units. Without `--out`, the JSON receipt precedes the unchanged body bytes.
104
+
83
105
  Conversion prints one JSON receipt line first. With `--out`, Markdown goes to the file;
84
106
  without it, Markdown follows on stdout. Local receipts use `brewdoc.receipt/1`; URL receipts use `brewdoc.receipt/2`.
85
107
 
@@ -97,7 +119,8 @@ without it, Markdown follows on stdout. Local receipts use `brewdoc.receipt/1`;
97
119
  | `acquisition` | URL provenance, frozen snapshot and capture status |
98
120
 
99
121
  Exit 0 means conversion, 1 refusal and 2 invalid usage. Success does not prove content fidelity or complete JavaScript.
100
- PDF/DOCX/PPTX/workbooks emit ASCII; HTML/EPUB emit UTF-8 without BOM, with LF newlines. JSON keeps ASCII escaping.
122
+ PDF/DOCX/PPTX emit ASCII; workbooks/HTML/EPUB/ODT/ODP/EML emit UTF-8 without BOM, with LF newlines.
123
+ Text pass-through retains the source UTF-8 encoding and newlines. JSON keeps ASCII escaping.
101
124
  The same local file or frozen snapshot produces identical bytes; live pages can change.
102
125
 
103
126
  ## Python API
@@ -111,16 +134,18 @@ refs = brewdoc.list_book_artifacts("book.xlsm", sheets=("Calc",))
111
134
  payload = brewdoc.read_book_artifact("book.xlsm", refs[0].key, sheets=("Calc",))
112
135
  ```
113
136
 
114
- `run` accepts `sheets` and an `artifact_outputs` key-to-path mapping. Renderers include
137
+ `run` accepts `sheets`, an `artifact_outputs` key-to-path mapping, `article` and `body_only`. Renderers include
115
138
  `render_pdf`, `render_doc`, `render_presentation`, `render_epub`, `render_html` and `render_book`.
116
139
  `read_formulas` provides typed formulas; `self_check` verifies installed routes. Local APIs never acquire URLs.
117
140
 
118
141
  ## Explicit URL acquisition
119
142
 
120
- `--url` deliberately acquires a public HTTP(S) page before local conversion.
143
+ `--url` deliberately acquires a public HTTP(S) page or supported document before local conversion.
144
+ Content-Type and magic bytes pick the route: HTML, PDF, Office, OpenDocument, EPUB, EML or text.
121
145
 
122
146
  ```sh
123
147
  brewdoc --url https://example.com/article --out article.md
148
+ brewdoc --url https://arxiv.org/pdf/1706.03762 --out attention.md
124
149
  brewdoc --url https://example.com/article --render-js --timeout 30 --out article.md
125
150
  ```
126
151
 
@@ -128,12 +153,12 @@ brewdoc --url https://example.com/article --render-js --timeout 30 --out article
128
153
  Public destinations, DNS, redirects, TLS, requests and bytes are validated. Ordinary requests use GET;
129
154
  JS admits only the narrow credential-free HN Algolia XHR POST exception. Local HTML never fetches or runs scripts.
130
155
  Optional JS needs installed/bundled prerequisites, refuses unsupported runtimes before HTTP and downloads no engine.
131
- Timing-only expiry can preserve valid partial content; hard failures refuse output. [Full URL/JS limits](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/FORMATS.md#url-acquisition).
156
+ Timing-only expiry can preserve valid partial content; hard failures refuse output. [Full URL/JS limits](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/FORMATS.md#url-acquisition).
132
157
 
133
158
  ## Article mode
134
159
 
135
160
  Introduced in 0.4.0; use a channel listed as available in the release. For Python JS capture, install
136
- `brewdoc[render-js]==0.4.1`; supported standalone bundles include its prerequisites.
161
+ `brewdoc[render-js]==0.6.0`; supported standalone bundles include its prerequisites.
137
162
 
138
163
  ```sh
139
164
  brewdoc page.html --article --out article.md
@@ -146,30 +171,31 @@ code, receipt, markdown = brewdoc.run("page.html", article=True)
146
171
  markdown, tally = brewdoc.render_html("page.html", article=True)
147
172
  ```
148
173
 
149
- Article mode selects one explicit article or a qualified main subtree. It suits single articles
150
- and documentation pages with those literal HTML elements. Feeds with peer articles, ambiguous
151
- main regions and pages without a qualified subtree refuse. A visible form disqualifies main
152
- fallback; an explicit article can retain forms. There is no full-page fallback or text scoring.
153
- Selection uses the recovered static HTML or frozen JS snapshot,
174
+ Article mode keeps visible `main` (or role main) content, or outer `article` content when no main
175
+ exists; articles outside a main are dropped when one exists. Page-chrome landmarks are skipped, but
176
+ a header inside an article or a nav inside main stays.
177
+ Peer articles and multiple mains render in DOM order. When no candidate renders, the whole clean
178
+ page renders and the receipt adds `article_fallback: true`; selection never refuses for page
179
+ structure. There is no text scoring. Selection uses the recovered static HTML or frozen JS snapshot,
154
180
  without layout or inferred author/date metadata. The source title is unchanged.
155
181
 
156
- The receipt's `not_carried` and successful Markdown's Known omissions declare:
182
+ When content is selected, the receipt's `not_carried` and Markdown's Known omissions declare:
157
183
  `body content outside the selected article or main subtree; complete page coverage is not claimed`.
158
- The [article contract](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/FORMATS.md#article-selection)
159
- defines selection, refusals and limits.
184
+ The [article contract](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/FORMATS.md#article-selection)
185
+ defines selection, fallback and limits.
160
186
 
161
- [Source-package CI](https://github.com/kochetkov-ma/brewdoc/actions/runs/38431645006) passed on
187
+ [Earlier source-package CI](https://github.com/kochetkov-ma/brewdoc/actions/runs/38431645006) passed on
162
188
  Ubuntu 22.04 x64/glibc with CPython 3.13.15, and macOS 15 ARM64/Windows Server 2025 x64
163
189
  with CPython 3.14.7. Each passed four independent wheel/sdist base/optional installs;
164
190
  optional JS executed on Unix and refused before requests on Windows. These are selected
165
- tested patches, not a claim about newer versions. CPython 3.12.14 retains the local macOS
166
- full-suite baseline and existing CI smoke checks. Package evidence is separate from the
167
- standalone binaries; other OS/minor combinations, free-threaded CPython and other
191
+ tested patches, not a claim about newer versions. These results predate the 0.5.0 changes.
192
+ CPython 3.12.14 retains the local macOS full-suite baseline and existing CI smoke checks.
193
+ Package evidence is separate from standalone binaries; other OS/minor combinations, free-threaded CPython and other
168
194
  architectures remain untested here.
169
- See [package compatibility](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/FORMATS.md#python-package-compatibility).
195
+ See [package compatibility](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/FORMATS.md#python-package-compatibility).
170
196
 
171
- [Format contracts](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/FORMATS.md) | [Corpus](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/benchmarks/CATALOG.md) | [Measurements](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/benchmarks/METHODOLOGY.md) | [Results](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/benchmarks/results/README.md)
172
- [Releasing](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/RELEASING.md) | [Agent entry point](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/llms.txt) | [MIT license](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/LICENSE)
197
+ [Format contracts](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/FORMATS.md) | [Corpus](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/benchmarks/CATALOG.md) | [Measurements](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/benchmarks/METHODOLOGY.md) | [Results](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/benchmarks/results/README.md)
198
+ [Releasing](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/RELEASING.md) | [Agent entry point](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/llms.txt) | [MIT license](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/LICENSE)
173
199
 
174
200
  ## Related projects
175
201
 
package/package.json CHANGED
@@ -29,8 +29,8 @@
29
29
  "license": "MIT",
30
30
  "name": "brewdoc",
31
31
  "optionalDependencies": {
32
- "brewdoc-darwin-arm64": "0.4.1",
33
- "brewdoc-linux-x64-glibc": "0.4.1"
32
+ "brewdoc-darwin-arm64": "0.6.0",
33
+ "brewdoc-linux-x64-glibc": "0.6.0"
34
34
  },
35
35
  "publishConfig": {
36
36
  "access": "public",
@@ -40,5 +40,5 @@
40
40
  "type": "git",
41
41
  "url": "git+https://github.com/kochetkov-ma/brewdoc.git"
42
42
  },
43
- "version": "0.4.1"
43
+ "version": "0.6.0"
44
44
  }