exactdoc 0.3.0b1__tar.gz

exactdoc-0.3.0b1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Ebin Babu Thomas
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

exactdoc-0.3.0b1/MANIFEST.in

@@ -0,0 +1,12 @@
+# What goes into the source distribution (sdist) uploaded to PyPI.
+#
+# The sdist is the wheel's source plus what a packager needs to rebuild it:
+# exactdoc/, pyproject.toml, README.md and LICENSE, which setuptools includes
+# on its own. Everything else stays in the repository.
+#
+# tests/ is pruned explicitly because setuptools adds tests/test*.py by
+# default, and those files cannot run from an sdist: they need testkit/, the
+# frozen corpus and the golden IR, none of which belong in a package download.
+# scripts/check_dist.py enforces this list on every build (CI and release).
+prune tests
+global-exclude *.py[cod] __pycache__

exactdoc-0.3.0b1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: exactdoc
+Version: 0.3.0b1
+Summary: High-fidelity PDF to DOCX that survives Google Docs, with a render-back diff that proves it
+Author: Ebin Babu Thomas
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/ebt55/exactdoc
+Project-URL: Documentation, https://github.com/ebt55/exactdoc/blob/main/docs/usage.md
+Project-URL: Changelog, https://github.com/ebt55/exactdoc/blob/main/CHANGELOG.md
+Project-URL: Source, https://github.com/ebt55/exactdoc
+Project-URL: Issues, https://github.com/ebt55/exactdoc/issues
+Keywords: pdf,docx,pdf-to-docx,pdf-to-word,google-docs,document-conversion,ooxml,layout-analysis,pdfium,whitepaper,research-paper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Office/Business :: Office Suites
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pypdfium2>=4.25
+Requires-Dist: python-docx>=1.1
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=10.0
+Requires-Dist: lxml>=4.9
+Provides-Extra: test
+Requires-Dist: reportlab>=4.0; extra == "test"
+Requires-Dist: fpdf2>=2.7; extra == "test"
+Provides-Extra: mupdf
+Requires-Dist: pymupdf>=1.23; extra == "mupdf"
+Provides-Extra: gdocs
+Requires-Dist: google-api-python-client>=2.100; extra == "gdocs"
+Requires-Dist: google-auth-httplib2>=0.1; extra == "gdocs"
+Requires-Dist: google-auth-oauthlib>=1.1; extra == "gdocs"
+Dynamic: license-file
+
+# exactdoc
+
+**Turn a PDF into a Word document that looks like the original and that you
+can actually edit.**
+
+exactdoc writes a DOCX made of real headings, paragraphs, lists, tables,
+footnotes and page headers, and lays them out so each page matches the PDF.
+Its output is measured by opening it in Microsoft Word, LibreOffice and Google
+Docs and comparing every page with the original. It runs entirely on your
+machine: no telemetry, no account, and no network unless you ask for the
+optional Google Docs measurement ([details](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/install.md#what-talks-to-the-network)).
+
+![Animation. On the left, page 1 of a whitepaper as the original PDF. On the right, the DOCX exactdoc made from it, shown in turn as Microsoft Word, Google Docs and LibreOffice lay it out. All four pages look almost the same.](https://raw.githubusercontent.com/ebt55/exactdoc/v0.3.0b1/docs/images/hero-readers.gif)
+
+<sub>Page 1 of one of the project's test whitepapers, converted with the default
+settings; Google Docs shows the DOCX made for it ([still image](https://raw.githubusercontent.com/ebt55/exactdoc/v0.3.0b1/docs/images/hero-readers.png),
+[how it was made](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/images/README.md)). Small differences remain: Google Docs
+adds a thin white strip above the dark band, and the footer's page number sits
+further left than in the PDF, set larger in Word and Google Docs.</sub>
+
+> **Beta (0.3.0b1), on PyPI.** Not announced yet: see the results on
+> [documents it has never seen](#tested-on-documents-it-has-never-seen) below.
+
+## Install
+
+You need Python 3.9 or newer.
+
+```bash
+pip install --pre exactdoc
+exactdoc --version
+```
+
+Optional, and recommended: **[LibreOffice](https://www.libreoffice.org/download/)**
+(free). When it is installed, exactdoc opens its own DOCX in it, compares each
+page with the PDF and corrects page breaks and spacing. Without it, exactdoc
+converts in one pass and says so. [docs/install.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/install.md) covers the
+fonts LibreOffice needs on Linux, how long the check takes, and the optional
+extras.
+
+## Quick start
+
+```bash
+exactdoc report.pdf                                    # writes report.docx next to it
+exactdoc report.pdf --output-profile gdocs --refine 0  # a DOCX made for Google Docs
+exactdoc --input-dir pdfs --out-dir docx --recursive   # a whole folder
+```
+
+```python
+from exactdoc import convert
+convert("report.pdf", "report.docx")                                  # with LibreOffice's check
+convert("report.pdf", "report.docx", refine_rounds=0, oracle="none")  # without LibreOffice
+```
+
+exactdoc never replaces a file you did not name. The Google Docs option writes
+the same document in a form Google Docs' importer reads correctly; it is still
+made offline, and you upload it to Drive yourself. Every option, the Python API
+and the exit codes are in [docs/usage.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/usage.md).
+
+## What you get
+
+The DOCX is built from the same pieces you would use to write the document in
+Word yourself, not from text boxes pinned to the page:
+
+![Page 2 of the whitepaper's DOCX with its parts labelled: a header that repeats on every page, a bulleted list, Heading 2 and Heading 1 styles, a table with real rows and cells, a chart kept as a picture, and a footer with a live page number.](https://raw.githubusercontent.com/ebt55/exactdoc/v0.3.0b1/docs/images/editable-structure.png)
+
+- **Headings** use Word's heading styles, so the navigation pane and Google
+  Docs' outline work.
+- **Paragraphs** flow and re-wrap when you edit them.
+- **Lists** are real bulleted and numbered lists.
+- **Tables** are real tables, with merged cells and rows that run over pages.
+- **Headers and footers** repeat on every page, with live page numbers.
+  **Footnotes** are real Word footnotes (plain text in the Google Docs output,
+  because Docs moves real ones), and links still work.
+- **Charts, logos and artwork** stay pictures, placed where the PDF has them.
+
+## What works, and what does not yet
+
+What exactdoc promises depends on the program that made the PDF. Documents
+written as flowing text in **Word, Google Docs, LibreOffice or LaTeX** are
+promised. Designed layouts are not, yet. Numbers below are from the release
+measurement ([record](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/evidence/release-documents-2026-10-11.json)) and,
+where they say "never seen", from [the test below](#tested-on-documents-it-has-never-seen)
+([results](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/evidence/holdout2-2026-10-11.json)).
+
+| Kind of PDF | Today |
+|---|---|
+| Letters, memos, policies, syllabi and other documents of up to 20 pages written in Word, Google Docs, LibreOffice or LaTeX | Works well |
+| Résumés | Mostly: of 8 never seen, 5 kept their page count and words; a federal-style résumé went from 3 pages to 6 |
+| Reports over 20 pages written in Word | Mixed: of 4 never seen, one came back exact; three US government audit reports gained 2–4 pages, with about a third of their words on the right page |
+| Long documents written in LaTeX | Mostly: two manuals never seen came back page for page; a 77-page technical report came back with 78 pages and 42% of its words on the right page |
+| Tables, simple two-column pages, headers, footers, footnotes, links | Works well |
+| Latin, Cyrillic and Greek text | Works well |
+| Chinese, Japanese and Korean text | Partly: the text survives, but some runs become pictures |
+| Arabic, Hebrew and Persian (right-to-left) | Partly: right-to-left paragraphs in reading order; pages can grow, and the Google Docs output is not yet right-to-left |
+| Long documents opened in Google Docs | Mostly: some gain pages (IRS Publication 15: 62 pages for 59) |
+| Designed reports and annual reports (InDesign, Affinity, QuarkXPress, Publisher) | Not yet: the text stays editable, but the layout does not hold |
+| Multi-column booklets (IRS, GPO, Federal Register style) | Not yet: IRS Publication 501 grows from 31 pages to 45 in LibreOffice |
+| Dense journal papers, equations | Not yet: equations come apart, and pages can be added |
+| Slide decks, brochures, posters | Not yet |
+| Web pages printed from a browser | Not yet: a 7-page Wikipedia article printed from Chrome came back with 8 pages and a third of its words on the right page |
+| Scans without a text layer, fillable forms, over 250 pages | Refused with a clear message and exit code (no OCR is built in; `--max-pages` raises the cap) |
+
+<table>
+<tr>
+<td width="50%"><img src="https://raw.githubusercontent.com/ebt55/exactdoc/v0.3.0b1/docs/images/works-tables.png" alt="A page of tables, PDF beside DOCX. A table with merged header cells, a nested table and a long striped table look the same in both."></td>
+<td width="50%"><img src="https://raw.githubusercontent.com/ebt55/exactdoc/v0.3.0b1/docs/images/not-yet-dense-paper.png" alt="Page 1 of a two-column arXiv paper beside its DOCX. The text and columns match, but a summation equation is broken apart, outlined in red."></td>
+</tr>
+<tr>
+<td><b>Works:</b> tables become real Word tables, merged cells included.</td>
+<td><b>Not yet:</b> in a dense arXiv paper (CC BY 4.0) the text converts, but equations come apart.</td>
+</tr>
+</table>
+
+To see which program made a PDF, open **File → Properties** in a PDF viewer and
+read the Producer and Application fields, or run `exactdoc --diagnose your.pdf`,
+which prints them without any of the document's text. The full list, with
+numbers, is in [docs/deep-dive/limitations.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/deep-dive/limitations.md);
+more side-by-side pictures are in [docs/examples.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/examples.md).
+
+## How we know
+
+Measured, not eyeballed. Every change must pass 16 frozen test documents,
+gated on every push in CI inside the pinned measurement image, and
+each milestone converts 95 frozen PDFs (those 16 and 79 more, most of them
+public real-world documents), opens every DOCX in LibreOffice, Microsoft Word
+and Google Docs, and compares it with the PDF page by page. In the final
+measurement for the beta ([record](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/evidence/release-documents-2026-10-11.json),
+[scorecard](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/evidence/beta-readiness-2026-10-11.json)):
+
+- all 41 promised documents of up to 20 pages kept exactly their page count in
+  all three;
+- of the 21 promised documents over 20 pages, all 21 in LibreOffice and Word,
+  and 18 in Google Docs, kept their page count within 2% (or one page) with at
+  least 85% of their words on the right page;
+- across everything, including the kinds marked "Not yet", Word opened all 90
+  DOCX files without asking to repair one, and in Google Docs
+  66 of the 90 compared came back with exactly the right number of pages.
+  The other five are PDFs exactdoc refuses on purpose.
+
+These are the documents exactdoc was developed against, so they show how well
+it does on PDFs it has seen. How the measurement works:
+[docs/deep-dive/measured-state.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/deep-dive/measured-state.md).
+
+### Tested on documents it has never seen
+
+Before the release, 32 public PDFs never used in development were sealed and
+then converted once, on the release candidate. 23 were classed as promised
+before the run, including the web page now marked "Not yet". The verdicts were
+the same in LibreOffice and Word; Google Docs was not part of this test ([results](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/evidence/holdout2-2026-10-11.txt), [data](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/evidence/holdout2-2026-10-11.json)):
+
+- **No crashes, and Word opened all 32 cleanly: pass.**
+- **Short promised documents: fail.** 13 of 16 kept exactly their page count, but only 12 of 16 had at least 90% of their words on the right page, below the 80% bar. The four misses: a CMU sample résumé set (9 pages for 8), a federal-style résumé, a LaTeX résumé (88% of words) and a Wikipedia article printed from Chrome (8 pages for 7).
+- **No unusable result: fail.** The federal-style résumé came back with 6 pages for 3 and about a third of its text on the right page.
+- **Long promised documents (reported):** a median page-count error of 1.3%; 4 of 7 within 2% (or one page), and 3 of 7 with at least 85% of their words on the right page.
+
+This did not meet the bar we set in advance for announcing it; 0.3.0b2 is the
+fix release.
+
+## Fonts
+
+The DOCX names only fonts that a standard Windows 10 or 11 computer with
+Microsoft Office has, with one exception: Chinese, Japanese, Korean, Arabic,
+Hebrew, Persian and Thai text keeps the PDF's own font name, so a reader who
+has that font sees it and one who does not gets Word's default for the script.
+The fonts the test documents name this way are `Noto Sans CJK JP`,
+`IPAPGothic`, `WenQuanYi Zen Hei`, `DFKai-SB`, `DejaVu Sans`,
+`Noto Naskh Arabic`, `David`, `Narkisim`, `BNazanin` and `Thonburi`.
+
+## Contributing
+
+PRs welcome. See [CONTRIBUTING.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/CONTRIBUTING.md) for the one-command quality
+check every PR runs. If a conversion goes wrong,
+[report it](https://github.com/ebt55/exactdoc/issues/new?template=bad-conversion.yml)
+with the output of `exactdoc --diagnose your.pdf` instead of the PDF itself.
+
+## Learn more
+
+| | |
+|---|---|
+| [docs/install.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/install.md) | LibreOffice and its fonts, timing, the optional extras, what talks to the network |
+| [docs/usage.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/usage.md) | Every option, the Python API, batch mode, exit codes |
+| [docs/deep-dive/limitations.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/deep-dive/limitations.md) | What does not work yet, with numbers |
+| [docs/examples.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/examples.md) | More pages side by side, the good and the bad |
+| [docs/deep-dive/measured-state.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/deep-dive/measured-state.md) | How the numbers are measured |
+| [CHANGELOG.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/CHANGELOG.md) | What changed, release by release |
+| [SECURITY.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/SECURITY.md) | Reporting a security problem privately |
+| [docs/README.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/README.md) | Index of every deeper document |
+
+## Licence
+
+exactdoc is [Apache-2.0](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/LICENSE). A default install pulls in no copyleft code.
+The optional `mupdf` extra (`pip install "exactdoc[mupdf]"`) adds PyMuPDF, which is
+AGPL-3.0; it is only a reference for measurements and does not change the output.
+Details: [docs/deep-dive/licensing.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/deep-dive/licensing.md) and
+[docs/license-audit.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/license-audit.md).

exactdoc-0.3.0b1/README.md

@@ -0,0 +1,195 @@
+# exactdoc
+
+**Turn a PDF into a Word document that looks like the original and that you
+can actually edit.**
+
+exactdoc writes a DOCX made of real headings, paragraphs, lists, tables,
+footnotes and page headers, and lays them out so each page matches the PDF.
+Its output is measured by opening it in Microsoft Word, LibreOffice and Google
+Docs and comparing every page with the original. It runs entirely on your
+machine: no telemetry, no account, and no network unless you ask for the
+optional Google Docs measurement ([details](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/install.md#what-talks-to-the-network)).
+
+![Animation. On the left, page 1 of a whitepaper as the original PDF. On the right, the DOCX exactdoc made from it, shown in turn as Microsoft Word, Google Docs and LibreOffice lay it out. All four pages look almost the same.](https://raw.githubusercontent.com/ebt55/exactdoc/v0.3.0b1/docs/images/hero-readers.gif)
+
+<sub>Page 1 of one of the project's test whitepapers, converted with the default
+settings; Google Docs shows the DOCX made for it ([still image](https://raw.githubusercontent.com/ebt55/exactdoc/v0.3.0b1/docs/images/hero-readers.png),
+[how it was made](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/images/README.md)). Small differences remain: Google Docs
+adds a thin white strip above the dark band, and the footer's page number sits
+further left than in the PDF, set larger in Word and Google Docs.</sub>
+
+> **Beta (0.3.0b1), on PyPI.** Not announced yet: see the results on
+> [documents it has never seen](#tested-on-documents-it-has-never-seen) below.
+
+## Install
+
+You need Python 3.9 or newer.
+
+```bash
+pip install --pre exactdoc
+exactdoc --version
+```
+
+Optional, and recommended: **[LibreOffice](https://www.libreoffice.org/download/)**
+(free). When it is installed, exactdoc opens its own DOCX in it, compares each
+page with the PDF and corrects page breaks and spacing. Without it, exactdoc
+converts in one pass and says so. [docs/install.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/install.md) covers the
+fonts LibreOffice needs on Linux, how long the check takes, and the optional
+extras.
+
+## Quick start
+
+```bash
+exactdoc report.pdf                                    # writes report.docx next to it
+exactdoc report.pdf --output-profile gdocs --refine 0  # a DOCX made for Google Docs
+exactdoc --input-dir pdfs --out-dir docx --recursive   # a whole folder
+```
+
+```python
+from exactdoc import convert
+convert("report.pdf", "report.docx")                                  # with LibreOffice's check
+convert("report.pdf", "report.docx", refine_rounds=0, oracle="none")  # without LibreOffice
+```
+
+exactdoc never replaces a file you did not name. The Google Docs option writes
+the same document in a form Google Docs' importer reads correctly; it is still
+made offline, and you upload it to Drive yourself. Every option, the Python API
+and the exit codes are in [docs/usage.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/usage.md).
+
+## What you get
+
+The DOCX is built from the same pieces you would use to write the document in
+Word yourself, not from text boxes pinned to the page:
+
+![Page 2 of the whitepaper's DOCX with its parts labelled: a header that repeats on every page, a bulleted list, Heading 2 and Heading 1 styles, a table with real rows and cells, a chart kept as a picture, and a footer with a live page number.](https://raw.githubusercontent.com/ebt55/exactdoc/v0.3.0b1/docs/images/editable-structure.png)
+
+- **Headings** use Word's heading styles, so the navigation pane and Google
+  Docs' outline work.
+- **Paragraphs** flow and re-wrap when you edit them.
+- **Lists** are real bulleted and numbered lists.
+- **Tables** are real tables, with merged cells and rows that run over pages.
+- **Headers and footers** repeat on every page, with live page numbers.
+  **Footnotes** are real Word footnotes (plain text in the Google Docs output,
+  because Docs moves real ones), and links still work.
+- **Charts, logos and artwork** stay pictures, placed where the PDF has them.
+
+## What works, and what does not yet
+
+What exactdoc promises depends on the program that made the PDF. Documents
+written as flowing text in **Word, Google Docs, LibreOffice or LaTeX** are
+promised. Designed layouts are not, yet. Numbers below are from the release
+measurement ([record](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/evidence/release-documents-2026-10-11.json)) and,
+where they say "never seen", from [the test below](#tested-on-documents-it-has-never-seen)
+([results](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/evidence/holdout2-2026-10-11.json)).
+
+| Kind of PDF | Today |
+|---|---|
+| Letters, memos, policies, syllabi and other documents of up to 20 pages written in Word, Google Docs, LibreOffice or LaTeX | Works well |
+| Résumés | Mostly: of 8 never seen, 5 kept their page count and words; a federal-style résumé went from 3 pages to 6 |
+| Reports over 20 pages written in Word | Mixed: of 4 never seen, one came back exact; three US government audit reports gained 2–4 pages, with about a third of their words on the right page |
+| Long documents written in LaTeX | Mostly: two manuals never seen came back page for page; a 77-page technical report came back with 78 pages and 42% of its words on the right page |
+| Tables, simple two-column pages, headers, footers, footnotes, links | Works well |
+| Latin, Cyrillic and Greek text | Works well |
+| Chinese, Japanese and Korean text | Partly: the text survives, but some runs become pictures |
+| Arabic, Hebrew and Persian (right-to-left) | Partly: right-to-left paragraphs in reading order; pages can grow, and the Google Docs output is not yet right-to-left |
+| Long documents opened in Google Docs | Mostly: some gain pages (IRS Publication 15: 62 pages for 59) |
+| Designed reports and annual reports (InDesign, Affinity, QuarkXPress, Publisher) | Not yet: the text stays editable, but the layout does not hold |
+| Multi-column booklets (IRS, GPO, Federal Register style) | Not yet: IRS Publication 501 grows from 31 pages to 45 in LibreOffice |
+| Dense journal papers, equations | Not yet: equations come apart, and pages can be added |
+| Slide decks, brochures, posters | Not yet |
+| Web pages printed from a browser | Not yet: a 7-page Wikipedia article printed from Chrome came back with 8 pages and a third of its words on the right page |
+| Scans without a text layer, fillable forms, over 250 pages | Refused with a clear message and exit code (no OCR is built in; `--max-pages` raises the cap) |
+
+<table>
+<tr>
+<td width="50%"><img src="https://raw.githubusercontent.com/ebt55/exactdoc/v0.3.0b1/docs/images/works-tables.png" alt="A page of tables, PDF beside DOCX. A table with merged header cells, a nested table and a long striped table look the same in both."></td>
+<td width="50%"><img src="https://raw.githubusercontent.com/ebt55/exactdoc/v0.3.0b1/docs/images/not-yet-dense-paper.png" alt="Page 1 of a two-column arXiv paper beside its DOCX. The text and columns match, but a summation equation is broken apart, outlined in red."></td>
+</tr>
+<tr>
+<td><b>Works:</b> tables become real Word tables, merged cells included.</td>
+<td><b>Not yet:</b> in a dense arXiv paper (CC BY 4.0) the text converts, but equations come apart.</td>
+</tr>
+</table>
+
+To see which program made a PDF, open **File → Properties** in a PDF viewer and
+read the Producer and Application fields, or run `exactdoc --diagnose your.pdf`,
+which prints them without any of the document's text. The full list, with
+numbers, is in [docs/deep-dive/limitations.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/deep-dive/limitations.md);
+more side-by-side pictures are in [docs/examples.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/examples.md).
+
+## How we know
+
+Measured, not eyeballed. Every change must pass 16 frozen test documents,
+gated on every push in CI inside the pinned measurement image, and
+each milestone converts 95 frozen PDFs (those 16 and 79 more, most of them
+public real-world documents), opens every DOCX in LibreOffice, Microsoft Word
+and Google Docs, and compares it with the PDF page by page. In the final
+measurement for the beta ([record](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/evidence/release-documents-2026-10-11.json),
+[scorecard](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/evidence/beta-readiness-2026-10-11.json)):
+
+- all 41 promised documents of up to 20 pages kept exactly their page count in
+  all three;
+- of the 21 promised documents over 20 pages, all 21 in LibreOffice and Word,
+  and 18 in Google Docs, kept their page count within 2% (or one page) with at
+  least 85% of their words on the right page;
+- across everything, including the kinds marked "Not yet", Word opened all 90
+  DOCX files without asking to repair one, and in Google Docs
+  66 of the 90 compared came back with exactly the right number of pages.
+  The other five are PDFs exactdoc refuses on purpose.
+
+These are the documents exactdoc was developed against, so they show how well
+it does on PDFs it has seen. How the measurement works:
+[docs/deep-dive/measured-state.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/deep-dive/measured-state.md).
+
+### Tested on documents it has never seen
+
+Before the release, 32 public PDFs never used in development were sealed and
+then converted once, on the release candidate. 23 were classed as promised
+before the run, including the web page now marked "Not yet". The verdicts were
+the same in LibreOffice and Word; Google Docs was not part of this test ([results](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/evidence/holdout2-2026-10-11.txt), [data](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/evidence/holdout2-2026-10-11.json)):
+
+- **No crashes, and Word opened all 32 cleanly: pass.**
+- **Short promised documents: fail.** 13 of 16 kept exactly their page count, but only 12 of 16 had at least 90% of their words on the right page, below the 80% bar. The four misses: a CMU sample résumé set (9 pages for 8), a federal-style résumé, a LaTeX résumé (88% of words) and a Wikipedia article printed from Chrome (8 pages for 7).
+- **No unusable result: fail.** The federal-style résumé came back with 6 pages for 3 and about a third of its text on the right page.
+- **Long promised documents (reported):** a median page-count error of 1.3%; 4 of 7 within 2% (or one page), and 3 of 7 with at least 85% of their words on the right page.
+
+This did not meet the bar we set in advance for announcing it; 0.3.0b2 is the
+fix release.
+
+## Fonts
+
+The DOCX names only fonts that a standard Windows 10 or 11 computer with
+Microsoft Office has, with one exception: Chinese, Japanese, Korean, Arabic,
+Hebrew, Persian and Thai text keeps the PDF's own font name, so a reader who
+has that font sees it and one who does not gets Word's default for the script.
+The fonts the test documents name this way are `Noto Sans CJK JP`,
+`IPAPGothic`, `WenQuanYi Zen Hei`, `DFKai-SB`, `DejaVu Sans`,
+`Noto Naskh Arabic`, `David`, `Narkisim`, `BNazanin` and `Thonburi`.
+
+## Contributing
+
+PRs welcome. See [CONTRIBUTING.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/CONTRIBUTING.md) for the one-command quality
+check every PR runs. If a conversion goes wrong,
+[report it](https://github.com/ebt55/exactdoc/issues/new?template=bad-conversion.yml)
+with the output of `exactdoc --diagnose your.pdf` instead of the PDF itself.
+
+## Learn more
+
+| | |
+|---|---|
+| [docs/install.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/install.md) | LibreOffice and its fonts, timing, the optional extras, what talks to the network |
+| [docs/usage.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/usage.md) | Every option, the Python API, batch mode, exit codes |
+| [docs/deep-dive/limitations.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/deep-dive/limitations.md) | What does not work yet, with numbers |
+| [docs/examples.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/examples.md) | More pages side by side, the good and the bad |
+| [docs/deep-dive/measured-state.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/deep-dive/measured-state.md) | How the numbers are measured |
+| [CHANGELOG.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/CHANGELOG.md) | What changed, release by release |
+| [SECURITY.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/SECURITY.md) | Reporting a security problem privately |
+| [docs/README.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/README.md) | Index of every deeper document |
+
+## Licence
+
+exactdoc is [Apache-2.0](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/LICENSE). A default install pulls in no copyleft code.
+The optional `mupdf` extra (`pip install "exactdoc[mupdf]"`) adds PyMuPDF, which is
+AGPL-3.0; it is only a reference for measurements and does not change the output.
+Details: [docs/deep-dive/licensing.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/deep-dive/licensing.md) and
+[docs/license-audit.md](https://github.com/ebt55/exactdoc/blob/v0.3.0b1/docs/license-audit.md).