@concordance-wiki/plugin-reader-office 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,67 @@
-# @concordance-wiki/plugin-reader-office
+<p align="center">
+  <img src="https://raw.githubusercontent.com/concordance-wiki/concordance/main/brand/concordance-mark.svg" width="72" alt="Concordance">
+</p>
 
-Metadata reader for Word, PowerPoint, Excel and PDF files. Contributes one `reader` for `.docx`, `.pptx`, `.xlsx` and `.pdf`; no system dependency.
+<h1 align="center">@concordance-wiki/plugin-reader-office</h1>
 
-`read({ path, payload: { bytes } })` returns `{ metadata, text: "" }`. The text stays empty: extraction belongs to the conversion story. The metadata carries what the file states about itself:
+<p align="center"><strong>Reads what your Word, PowerPoint, Excel and PDF files state about themselves, so every document gets a page.</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@concordance-wiki/plugin-reader-office"><img alt="npm" src="https://img.shields.io/npm/v/@concordance-wiki/plugin-reader-office?style=flat-square"></a>
+  <a href="https://github.com/concordance-wiki/concordance/blob/main/LICENSE"><img alt="Licence" src="https://img.shields.io/badge/licence-GPL--3.0--or--later-16181B?style=flat-square"></a>
+  <a href="https://github.com/concordance-wiki/concordance/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/concordance-wiki/concordance/ci.yml?branch=main&label=ci&style=flat-square"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/concordance-wiki/concordance/blob/main/docs/guides/getting-started.md">Getting started</a> ·
+  <a href="https://github.com/concordance-wiki/concordance/blob/main/docs/guides/configuration.md">Configuration</a> ·
+  <a href="https://github.com/concordance-wiki/concordance/blob/main/docs/guides/plugins.md">Plugins</a> ·
+  <a href="https://github.com/concordance-wiki/concordance/blob/main/plugins/reader-office/CHANGELOG.md">Changelog</a>
+</p>
+
+---
+
+## Why
+
+Half of what a team knows sits in office documents next to the markdown, and a wiki that ignores them is half a wiki. This plugin reads the metadata of `.docx`, `.pptx`, `.xlsx` and `.pdf` files in your repositories, title, author, subject, keywords, dates, page, word and slide counts, so that every document gets a page with what the file states about itself, is filed with the notes and shows up in the to-do list when nobody has summarised it. It is carried by [`@concordance-wiki/concordance`](https://www.npmjs.com/package/@concordance-wiki/concordance); install it on its own next to [`@concordance-wiki/cli`](https://www.npmjs.com/package/@concordance-wiki/cli). No system dependency.
+
+## Quick start
+
+```bash
+npm install --save-dev @concordance-wiki/plugin-reader-office
+```
+
+Then declare it in `concordance.yaml`, with the conversion plugin next to it when LibreOffice is available, for the preview and the text of every page:
+
+```yaml
+plugins:
+  - "@concordance-wiki/plugin-reader-office"
+  - "@concordance-wiki/plugin-convert-libreoffice"
+```
+
+Every `.docx`, `.pptx`, `.xlsx` and `.pdf` file of a source becomes a document entity whose properties come from the file.
+
+## What you get
+
+- **A page per document**, with the properties the file carries: title, author, subject, keywords, creation and modification dates, application.
+- **Counts that mean something**: the pages and words an office file declares, the page count of a PDF, the slides of a deck with their titles in order.
+- **The document's own dates**, created and modified as the file says, kept apart from the git commit date of the file.
+- **Only the bytes**: the reader never touches git, the file system or the clock; a corrupted file is a finding, not a failed build.
+- **Twins reconciled**: the build matches a document with the note that describes it, and the page of that note offers the file for download; a document nobody wrote about is listed on the to-do page.
+- **Usable alone**: `readOoxml(bytes, kind)` and `readPdf(bytes)` read the two families without the pipeline.
+
+## Documentation
+
+- [Plugins](https://github.com/concordance-wiki/concordance/blob/main/docs/guides/plugins.md), the reader contribution point
+- [Configuration reference](https://github.com/concordance-wiki/concordance/blob/main/docs/guides/configuration.md), `privacy.pseudonymize` for the authors a file names
+- [Home page](https://concordance-wiki.github.io/concordance/), the [demo wiki](https://concordance-wiki.github.io/demo-wiki/) and the [changelog](https://github.com/concordance-wiki/concordance/blob/main/plugins/reader-office/CHANGELOG.md)
+
+Part of [Concordance](https://github.com/concordance-wiki/concordance), GNU GPL v3 or later.
+
+<details>
+<summary>Inside the package</summary>
+
+`read({ path, payload: { bytes } })` returns `{ metadata, text: "" }`. The text stays empty: extraction belongs to the conversion plugin, which reads it from the PDF. The metadata carries what the file states about itself:
 
 | Property | docx, pptx, xlsx | pdf |
 |---|---|---|
@@ -17,8 +76,6 @@ An absent property is absent from the record. A package without `docProps` yield
 
 The dates are the document's own and are kept apart from the git commit date the ingested file carries: the reader reads nothing but the bytes it is given, never git, the file system or the clock. Authors are returned raw; pseudonymisation applies downstream, on the model, when it is enabled.
 
-PDF objects stored in compressed object streams are not scanned: the page count is then a lower bound and an Info dictionary hidden there is not seen. The text extraction story brings a full parser.
-
-Exports: the default plugin manifest, `read`, `extensions`, `readOoxml(bytes, kind)`, `readPdf(bytes)`, `isoDate` and the `OfficeMetadata` type.
+PDF objects stored in compressed object streams are not scanned: the page count is then a lower bound and an Info dictionary hidden there is not seen. The conversion plugin, which parses the whole PDF for its text, does not depend on that count.
 
-Part of [Concordance](../../README.md); see the [plugin guide](../../docs/guides/plugins.md).
+</details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@concordance-wiki/plugin-reader-office",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Metadata reader for docx, pptx, xlsx and pdf files: properties, dates, counts and slide titles.",
   "license": "GPL-3.0-or-later",
   "repository": {
@@ -29,12 +29,12 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "typecheck": "tsc -b tsconfig.json"
-  },
   "dependencies": {
-    "@concordance-wiki/core": "workspace:*",
     "fast-xml-parser": "5.11.1",
-    "fflate": "0.8.3"
+    "fflate": "0.8.3",
+    "@concordance-wiki/core": "0.2.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -b tsconfig.json"
   }
-}
+}