Skip to content

Commit 3886cef

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
docs(readme): convert README.adoc -> Markdown (renders on Glama/profile/community-health) (#18)
README was AsciiDoc → renders as raw markup in Markdown consumers (Glama MCP directory, GitHub community-health, GitHub profile). pandoc asciidoc→GFM (badges → clickable), SPDX header kept, duplicate `.adoc` removed. Part of the estate README-format fix. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 528d989 commit 3886cef

2 files changed

Lines changed: 85 additions & 154 deletions

File tree

‎README.adoc‎

Lines changed: 0 additions & 87 deletions
This file was deleted.

‎README.md‎

Lines changed: 85 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,107 @@
1-
[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath)
1+
<!--
2+
SPDX-License-Identifier: CC-BY-SA-4.0
3+
SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
-->
25

3-
// SPDX-License-Identifier: CC-BY-SA-4.0
4-
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
6+
`blocky-writer` is a Mozilla Firefox extension for block-based PDF form
7+
filling.
58

6-
= blocky-writer
7-
:toc: preamble
8-
:icons: font
9+
# Stack
910

10-
`blocky-writer` is a Mozilla Firefox extension for block-based PDF form filling.
11+
- Extension UI: ReScript + React
1112

12-
== Stack
13+
- Background/content scripts: ReScript
1314

14-
* Extension UI: ReScript + React
15-
* Background/content scripts: ReScript
16-
* Core processing: Rust compiled to WebAssembly (WASM)
17-
* Local storage: IndexedDB
15+
- Core processing: Rust compiled to WebAssembly (WASM)
1816

19-
== Repo Layout
17+
- Local storage: IndexedDB
2018

21-
* `src/` — ReScript sources for popup UI, background script, content script, and core modules
22-
* `public/` — static extension files (`manifest.json`, popup HTML, icons)
23-
* `rust/pdftool_core/` — Rust WASM crate for block detection and PDF operations
24-
* `scripts/` — build helpers for WASM and extension bundles
19+
# Repo Layout
2520

26-
== Quick Start
21+
- `src/` — ReScript sources for popup UI, background script, content
22+
script, and core modules
2723

28-
. Install dependencies (Deno-first):
29-
+
30-
[source,bash]
31-
----
32-
deno install
33-
----
24+
- `public/` — static extension files (`manifest.json`, popup HTML,
25+
icons)
3426

35-
. Build ReScript output and bundle extension assets:
36-
+
37-
[source,bash]
38-
----
39-
deno task build
40-
----
27+
- `rust/pdftool_core/` — Rust WASM crate for block detection and PDF
28+
operations
4129

42-
. Build the Rust WASM package:
43-
+
44-
[source,bash]
45-
----
46-
deno task build:wasm
47-
----
30+
- `scripts/` — build helpers for WASM and extension bundles
4831

49-
. Run the extension in Firefox via `web-ext`:
50-
+
51-
[source,bash]
52-
----
53-
deno task dev
54-
----
32+
# Quick Start
5533

56-
. Run core fill fixture tests (error taxonomy + AcroForm writeback):
57-
+
58-
[source,bash]
59-
----
60-
deno task test:core-fill
61-
----
34+
1. Install dependencies (Deno-first):
6235

63-
== Notes
36+
``` bash
37+
deno install
38+
```
6439

65-
* Rust `fill_blocks` now performs AcroForm-aware writeback for text/select and button widgets, and emits structured taxonomy errors (`code`, `message`, `context`).
66-
* Popup/background/content surfaces preserve taxonomy codes from the Rust WASM boundary.
67-
* Source files include SPDX headers targeting MPL-2.0.
40+
<!-- -->
6841

69-
== Firefox Troubleshooting
42+
1. Build ReScript output and bundle extension assets:
7043

71-
* If `deno task dev` fails with `ECONNREFUSED 127.0.0.1:<port>`, verify Firefox is installed and runnable.
72-
* Close stale Firefox instances launched by prior `web-ext` sessions, then retry `deno task dev`.
73-
* You can run `web-ext` directly with an explicit binary when needed:
74-
+
75-
[source,bash]
76-
----
77-
deno run -A npm:web-ext run --source-dir dist --firefox /usr/bin/firefox
78-
----
44+
``` bash
45+
deno task build
46+
```
7947

80-
== Architecture
48+
<!-- -->
8149

82-
See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard.
50+
1. Build the Rust WASM package:
8351

84-
Wondering how this works? See link:EXPLAINME.adoc[].
52+
``` bash
53+
deno task build:wasm
54+
```
8555

86-
== License
56+
<!-- -->
8757

88-
SPDX-License-Identifier: CC-BY-SA-4.0 +
89-
See link:LICENSE[LICENSE].
58+
1. Run the extension in Firefox via `web-ext`:
59+
60+
``` bash
61+
deno task dev
62+
```
63+
64+
<!-- -->
65+
66+
1. Run core fill fixture tests (error taxonomy + AcroForm writeback):
67+
68+
``` bash
69+
deno task test:core-fill
70+
```
71+
72+
# Notes
73+
74+
- Rust `fill_blocks` now performs AcroForm-aware writeback for
75+
text/select and button widgets, and emits structured taxonomy errors
76+
(`code`, `message`, `context`).
77+
78+
- Popup/background/content surfaces preserve taxonomy codes from the
79+
Rust WASM boundary.
80+
81+
- Source files include SPDX headers targeting MPL-2.0.
82+
83+
# Firefox Troubleshooting
84+
85+
- If `deno` `task` `dev` fails with `ECONNREFUSED` `127.0.0.1:<port>`,
86+
verify Firefox is installed and runnable.
87+
88+
- Close stale Firefox instances launched by prior `web-ext` sessions,
89+
then retry `deno` `task` `dev`.
90+
91+
- You can run `web-ext` directly with an explicit binary when needed:
92+
93+
``` bash
94+
deno run -A npm:web-ext run --source-dir dist --firefox /usr/bin/firefox
95+
```
96+
97+
# Architecture
98+
99+
See <a href="TOPOLOGY.md" class="md">TOPOLOGY</a> for a visual
100+
architecture map and completion dashboard.
101+
102+
Wondering how this works? See [EXPLAINME.adoc](EXPLAINME.adoc).
103+
104+
# License
105+
106+
SPDX-License-Identifier: CC-BY-SA-4.0\
107+
See [LICENSE](LICENSE).

0 commit comments

Comments
 (0)