brewdoc 0.4.1 → 0.5.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 +47 -28
  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.5.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.5.0/FORMATS.md).
13
+ Version 0.4.1 added [selected ZIP/XML reader budgets](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.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
+ Version 0.5.0 adds ODT/ODP text and tables, selected MIME email bodies and exact UTF-8
18
+ Markdown/text pass-through. It preserves workbook Unicode and exposed datetime precision,
19
+ and selects one DOCX compatibility fallback.
20
+ It also adds textless PDF page facts and selected caption, table and math-spacing fixes.
21
+ See the [format contracts](FORMATS.md).
22
+
17
23
  ## Install
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
+ These examples select 0.5.0. Use a channel listed as available in [that release](https://github.com/kochetkov-ma/brewdoc/releases/tag/v0.5.0). Choose one method:
20
26
 
21
27
  Article mode is introduced in 0.4.0. Channel availability is listed in the release.
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.5.0"
31
+ uv tool install --python 3.12 "brewdoc==0.5.0"
32
+ pipx install --python 3.12 "brewdoc==0.5.0"
27
33
  ```
28
34
 
29
35
  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.
36
+ [INSTALL.md](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.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.5.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.5.0/brewdoc-0.5.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.5.0/brewdoc-0.5.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.5.0/brewdoc-0.5.0-macos-arm64.tar.gz)
40
46
 
41
47
  | Native target | Verification environment | JavaScript |
42
48
  |---|---|---|
@@ -46,15 +52,21 @@ 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.5.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.5.0).
63
+ [INSTALL.md](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.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](INSTALL.md#homebrew).
58
70
 
59
71
  ## Usage
60
72
 
@@ -74,12 +86,18 @@ Requests and output collisions are validated before writes. Paths resolve agains
74
86
 
75
87
  ## Markdown and receipts
76
88
 
77
- Successful output uses `brewdoc.markdown/2`: quoted source title, Metadata, Artifacts,
89
+ Parsed document output uses `brewdoc.markdown/2`: quoted source title, Metadata, Artifacts,
78
90
  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.
91
+ PPTX/ODP `slide/000001`, and DOCX/EPUB/HTML/ODT/EML `chapter/000001`.
92
+ Empty declared units remain navigable.
80
93
  Metadata holds source/selection/content hashes, conversion tallies and artifact capabilities;
81
94
  it excludes paths, timestamps, permissions and host data. EPUB retains declared publication metadata.
82
95
 
96
+ UTF-8 `.md` and `.txt` use `brewdoc.markdown/passthrough/1`: exact source bytes with
97
+ no generated envelope, contents or anchors. BOM, whitespace, newline variants and absent
98
+ final newline survive; empty input succeeds. The receipt reports route `text`, kind `none`
99
+ and zero units. Without `--out`, the JSON receipt precedes the unchanged body bytes.
100
+
83
101
  Conversion prints one JSON receipt line first. With `--out`, Markdown goes to the file;
84
102
  without it, Markdown follows on stdout. Local receipts use `brewdoc.receipt/1`; URL receipts use `brewdoc.receipt/2`.
85
103
 
@@ -97,7 +115,8 @@ without it, Markdown follows on stdout. Local receipts use `brewdoc.receipt/1`;
97
115
  | `acquisition` | URL provenance, frozen snapshot and capture status |
98
116
 
99
117
  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.
118
+ PDF/DOCX/PPTX emit ASCII; workbooks/HTML/EPUB/ODT/ODP/EML emit UTF-8 without BOM, with LF newlines.
119
+ Text pass-through retains the source UTF-8 encoding and newlines. JSON keeps ASCII escaping.
101
120
  The same local file or frozen snapshot produces identical bytes; live pages can change.
102
121
 
103
122
  ## Python API
@@ -128,12 +147,12 @@ brewdoc --url https://example.com/article --render-js --timeout 30 --out article
128
147
  Public destinations, DNS, redirects, TLS, requests and bytes are validated. Ordinary requests use GET;
129
148
  JS admits only the narrow credential-free HN Algolia XHR POST exception. Local HTML never fetches or runs scripts.
130
149
  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).
150
+ Timing-only expiry can preserve valid partial content; hard failures refuse output. [Full URL/JS limits](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/FORMATS.md#url-acquisition).
132
151
 
133
152
  ## Article mode
134
153
 
135
154
  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.
155
+ `brewdoc[render-js]==0.5.0`; supported standalone bundles include its prerequisites.
137
156
 
138
157
  ```sh
139
158
  brewdoc page.html --article --out article.md
@@ -155,21 +174,21 @@ without layout or inferred author/date metadata. The source title is unchanged.
155
174
 
156
175
  The receipt's `not_carried` and successful Markdown's Known omissions declare:
157
176
  `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)
177
+ The [article contract](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/FORMATS.md#article-selection)
159
178
  defines selection, refusals and limits.
160
179
 
161
- [Source-package CI](https://github.com/kochetkov-ma/brewdoc/actions/runs/38431645006) passed on
180
+ [Earlier source-package CI](https://github.com/kochetkov-ma/brewdoc/actions/runs/38431645006) passed on
162
181
  Ubuntu 22.04 x64/glibc with CPython 3.13.15, and macOS 15 ARM64/Windows Server 2025 x64
163
182
  with CPython 3.14.7. Each passed four independent wheel/sdist base/optional installs;
164
183
  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
184
+ tested patches, not a claim about newer versions. These results predate the 0.5.0 changes.
185
+ CPython 3.12.14 retains the local macOS full-suite baseline and existing CI smoke checks.
186
+ Package evidence is separate from standalone binaries; other OS/minor combinations, free-threaded CPython and other
168
187
  architectures remain untested here.
169
- See [package compatibility](https://github.com/kochetkov-ma/brewdoc/blob/v0.4.1/FORMATS.md#python-package-compatibility).
188
+ See [package compatibility](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/FORMATS.md#python-package-compatibility).
170
189
 
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)
190
+ [Format contracts](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/FORMATS.md) | [Corpus](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/benchmarks/CATALOG.md) | [Measurements](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/benchmarks/METHODOLOGY.md) | [Results](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/benchmarks/results/README.md)
191
+ [Releasing](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/RELEASING.md) | [Agent entry point](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/llms.txt) | [MIT license](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/LICENSE)
173
192
 
174
193
  ## Related projects
175
194
 
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.5.0",
33
+ "brewdoc-linux-x64-glibc": "0.5.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.5.0"
44
44
  }