brewdoc 0.5.0 → 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 +47 -40
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -3,46 +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.5.0/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.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)
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
- 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).
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.
22
24
 
23
25
  ## Install
24
26
 
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:
26
-
27
- 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:
28
28
 
29
29
  ```sh
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"
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"
33
33
  ```
34
34
 
35
- Use a virtual environment for pip. Python 3.12+ is required; HTML/URL need CPython 3.12-3.14.
36
- [INSTALL.md](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/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.
37
37
  [Latest release](https://github.com/kochetkov-ma/brewdoc/releases/latest) lists actual assets and channel availability.
38
38
 
39
39
  ### Standalone downloads
40
40
 
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.
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.
42
42
 
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)
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)
46
46
 
47
47
  | Native target | Verification environment | JavaScript |
48
48
  |---|---|---|
@@ -52,26 +52,27 @@ Use downloads listed as available in the release. Python and dependencies are bu
52
52
 
53
53
  Older OSes, Linux musl/ARM64 and macOS Intel are outside this binary set.
54
54
  Windows is unsigned; macOS has an ad hoc signature without Developer ID/notarization.
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).
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).
56
56
 
57
57
  ### npm
58
58
 
59
59
  [![npm](https://img.shields.io/npm/v/brewdoc)](https://www.npmjs.com/package/brewdoc)
60
60
 
61
61
  npm targets Linux x64/glibc and macOS ARM64. Windows uses the GitHub native download or Python package.
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.
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
64
 
65
65
  ### Homebrew
66
66
 
67
67
  Use `kochetkov-ma/brew/brewdoc` only when the release lists it as available.
68
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).
69
+ glibc 2.35+. See [installation and lifecycle](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/INSTALL.md#homebrew).
70
70
 
71
71
  ## Usage
72
72
 
73
73
  ```sh
74
74
  brewdoc file.pdf --out file.md
75
+ brewdoc --body-only paper.pdf --out paper.md
75
76
  brewdoc book.epub --out book.md
76
77
  brewdoc file.xlsx --sheet Calc --sheet Inputs --out book.md
77
78
  brewdoc file.xlsm --artifact formula/sheet/000002=formulas.json
@@ -83,13 +84,16 @@ brewdoc --self-check
83
84
  caller order retains full-workbook ordinals. Artifact keys come from the Markdown artifact table.
84
85
  Requests and output collisions are validated before writes. Paths resolve against the caller's directory;
85
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).
86
89
 
87
90
  ## Markdown and receipts
88
91
 
89
92
  Parsed document output uses `brewdoc.markdown/2`: quoted source title, Metadata, Artifacts,
90
93
  Known omissions, Contents, then anchored units. PDF uses `page/000001`, workbooks `sheet/000001`,
91
94
  PPTX/ODP `slide/000001`, and DOCX/EPUB/HTML/ODT/EML `chapter/000001`.
92
- Empty declared units remain navigable.
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).
93
97
  Metadata holds source/selection/content hashes, conversion tallies and artifact capabilities;
94
98
  it excludes paths, timestamps, permissions and host data. EPUB retains declared publication metadata.
95
99
 
@@ -130,16 +134,18 @@ refs = brewdoc.list_book_artifacts("book.xlsm", sheets=("Calc",))
130
134
  payload = brewdoc.read_book_artifact("book.xlsm", refs[0].key, sheets=("Calc",))
131
135
  ```
132
136
 
133
- `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
134
138
  `render_pdf`, `render_doc`, `render_presentation`, `render_epub`, `render_html` and `render_book`.
135
139
  `read_formulas` provides typed formulas; `self_check` verifies installed routes. Local APIs never acquire URLs.
136
140
 
137
141
  ## Explicit URL acquisition
138
142
 
139
- `--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.
140
145
 
141
146
  ```sh
142
147
  brewdoc --url https://example.com/article --out article.md
148
+ brewdoc --url https://arxiv.org/pdf/1706.03762 --out attention.md
143
149
  brewdoc --url https://example.com/article --render-js --timeout 30 --out article.md
144
150
  ```
145
151
 
@@ -147,12 +153,12 @@ brewdoc --url https://example.com/article --render-js --timeout 30 --out article
147
153
  Public destinations, DNS, redirects, TLS, requests and bytes are validated. Ordinary requests use GET;
148
154
  JS admits only the narrow credential-free HN Algolia XHR POST exception. Local HTML never fetches or runs scripts.
149
155
  Optional JS needs installed/bundled prerequisites, refuses unsupported runtimes before HTTP and downloads no engine.
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).
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).
151
157
 
152
158
  ## Article mode
153
159
 
154
160
  Introduced in 0.4.0; use a channel listed as available in the release. For Python JS capture, install
155
- `brewdoc[render-js]==0.5.0`; supported standalone bundles include its prerequisites.
161
+ `brewdoc[render-js]==0.6.0`; supported standalone bundles include its prerequisites.
156
162
 
157
163
  ```sh
158
164
  brewdoc page.html --article --out article.md
@@ -165,17 +171,18 @@ code, receipt, markdown = brewdoc.run("page.html", article=True)
165
171
  markdown, tally = brewdoc.render_html("page.html", article=True)
166
172
  ```
167
173
 
168
- Article mode selects one explicit article or a qualified main subtree. It suits single articles
169
- and documentation pages with those literal HTML elements. Feeds with peer articles, ambiguous
170
- main regions and pages without a qualified subtree refuse. A visible form disqualifies main
171
- fallback; an explicit article can retain forms. There is no full-page fallback or text scoring.
172
- 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,
173
180
  without layout or inferred author/date metadata. The source title is unchanged.
174
181
 
175
- 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:
176
183
  `body content outside the selected article or main subtree; complete page coverage is not claimed`.
177
- The [article contract](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/FORMATS.md#article-selection)
178
- 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.
179
186
 
180
187
  [Earlier source-package CI](https://github.com/kochetkov-ma/brewdoc/actions/runs/38431645006) passed on
181
188
  Ubuntu 22.04 x64/glibc with CPython 3.13.15, and macOS 15 ARM64/Windows Server 2025 x64
@@ -185,10 +192,10 @@ tested patches, not a claim about newer versions. These results predate the 0.5.
185
192
  CPython 3.12.14 retains the local macOS full-suite baseline and existing CI smoke checks.
186
193
  Package evidence is separate from standalone binaries; other OS/minor combinations, free-threaded CPython and other
187
194
  architectures remain untested here.
188
- See [package compatibility](https://github.com/kochetkov-ma/brewdoc/blob/v0.5.0/FORMATS.md#python-package-compatibility).
195
+ See [package compatibility](https://github.com/kochetkov-ma/brewdoc/blob/v0.6.0/FORMATS.md#python-package-compatibility).
189
196
 
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)
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)
192
199
 
193
200
  ## Related projects
194
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.5.0",
33
- "brewdoc-linux-x64-glibc": "0.5.0"
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.5.0"
43
+ "version": "0.6.0"
44
44
  }