From ae1aa1270c634480662617d00b7107b437f2aa09 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:16:55 +0100 Subject: [PATCH] docs(readme): convert README.adoc -> Markdown README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) — AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 --- README.adoc | 149 ------------------------------------------ README.md | 181 ++++++++++++++++++++++++++-------------------------- 2 files changed, 92 insertions(+), 238 deletions(-) delete mode 100644 README.adoc diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 6670c7f..0000000 --- a/README.adoc +++ /dev/null @@ -1,149 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[MPL-2.0-or-later,link="https://opensource.org/licenses/MPL-2.0"] -= DocMatrix -image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=openssourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/docmatrix"] - - - - -:toc: left -:toclevels: 3 -:icons: font -:source-highlighter: rouge - -image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] - -== License & Philosophy - -This project must declare **MPL-2.0-or-later** for platform/tooling compatibility. - -Philosophy: **Palimpsest**. The MPL-2.0 (PMPL) text is provided in `license/MPL-2.0.txt`, and the canonical source is the palimpsest-license repository. - -Cross-platform document editor with format tabs (TXT/MD/ADOC/DJOT/ORG/RST/TYP). Gossamer GUI + Ada TUI. Graph visualization, OCR, TTS/STT, Nickel pipelines. - -== Features - -* *Format Tabs* - View and edit the same document in multiple markup formats -* *Unified AST* - Lossless conversion between formats -* *GUI* - Gossamer with ReScript frontend -* *TUI* - Ada with AdaCurses for terminal usage -* *Graph Visualization* - ArangoDB for document relationships -* *Accessibility* - OCR, TTS, STT support -* *Pipelines* - Nickel-based import/export transformations - -== Supported Formats - -[cols="1,2", options="header"] -|=== -| Format | Description - -| TXT | Plain text -| MD | Markdown (CommonMark) -| ADOC | AsciiDoc -| DJOT | Djot markup -| ORG | Org-mode -| RST | reStructuredText -| TYP | Typst -|=== - -== Quick Start - -[source,bash] ----- -# Check dependencies -just deps - -# Build all components -just build - -# Run GUI -just run-gui - -# Run TUI -just run-tui ----- - -== Architecture - -[source] ----- -crates/ -├── formatrix-core/ # AST, parsers, renderers -├── formatrix-gui/ # Gossamer commands -├── formatrix-db/ # ArangoDB client -└── formatrix-pipeline/ # Nickel executor - -tui/src/ # Ada TUI source -ui/src/ # ReScript components -pipelines/ # Nickel pipeline definitions -container/ # Wolfi container configs ----- - -== Development - -=== Prerequisites - -* Rust (stable) -* Deno -* GNAT + gprbuild (for TUI) -* GTK4 + WebKit2GTK (for GUI) - -=== Build Commands - -[source,bash] ----- -just build # Build all -just build-core # Build Rust core only -just build-tui # Build Ada TUI only -just build-ui # Build ReScript UI only -just test # Run all tests -just fmt # Format all code -just lint # Lint all code ----- - -=== Containers - -[source,bash] ----- -just container-build # Build Wolfi image -just compose-up # Start with ArangoDB -just container-run-tui # Run TUI in container ----- - -== RSR Compliance - -This project follows the Rhodium Standard Repositories specification: - -* *Tier 2* - Full-featured multi-language project -* See link:RSR_COMPLIANCE.adoc[RSR_COMPLIANCE.adoc] for details - -== Related Scripts - -Automation scripts from https://github.com/hyperpolymath/scripts[hyperpolymath/scripts]: - -[cols="1,2", options="header"] -|=== -| Script | Purpose - -| `asdfman.sh` | Manage asdf plugins and versions -| `init_bashrc_three_ply.sh` | Modular bashrc setup (three-layer architecture) -| `k-check.sh` | Kinoite cluster validation -| `k-intune.sh` | Kinoite tuning scripts -| `langstrap.sh` | Mass language install utilities -| `sysenv.sh` | System environment setup -| `touchscreen_hunter_killer.sh` | Touchscreen calibration/management -|=== - -These scripts follow the same language policy (Bash, Rust, ReScript, Deno, Gleam, Guile Scheme) and multi-forge mirroring strategy. - -== License - -MPL-2.0 with Palimpsest philosophy. - -== Links - -* link:.machine_readable/6a2/STATE.a2ml[Project State] -* link:.machine_readable/6a2/ECOSYSTEM.a2ml[Ecosystem Position] -* link:.machine_readable/6a2/META.a2ml[Architecture Decisions] -* link:PALIMPSEST.adoc[Palimpsest Philosophy] diff --git a/README.md b/README.md index 5655681..22cc062 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,57 @@ -[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) - + -image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[MPL-2.0-or-later,link="https://opensource.org/licenses/MPL-2.0"] -// SPDX-License-Identifier: CC-BY-SA-4.0 -= DocMatrix +[![MPL-2](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](https://opensource.org/licenses/MPL-2.0) = DocMatrix [![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=openssourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/docmatrix) +[![Palimpsest](https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg)](https://github.com/hyperpolymath/palimpsest-license) +# License & Philosophy -:toc: left -:toclevels: 3 -:icons: font -:source-highlighter: rouge +This project must declare **MPL-2.0-or-later** for platform/tooling +compatibility. -image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] +Philosophy: **Palimpsest**. The MPL-2.0 (PMPL) text is provided in +`license/MPL-2.0.txt`, and the canonical source is the +palimpsest-license repository. -== License & Philosophy +Cross-platform document editor with format tabs +(TXT/MD/ADOC/DJOT/ORG/RST/TYP). Gossamer GUI + Ada TUI. Graph +visualization, OCR, TTS/STT, Nickel pipelines. -This project must declare **MPL-2.0-or-later** for platform/tooling compatibility. +# Features -Philosophy: **Palimpsest**. The Palimpsest-MPL (PMPL) text is provided in `license/PMPL-1.0.txt`, and the canonical source is the palimpsest-license repository. +- **Format Tabs** - View and edit the same document in multiple markup + formats -Cross-platform document editor with format tabs (TXT/MD/ADOC/DJOT/ORG/RST/TYP). Gossamer GUI + Ada TUI. Graph visualization, OCR, TTS/STT, Nickel pipelines. +- **Unified AST** - Lossless conversion between formats -== Features +- **GUI** - Gossamer with ReScript frontend -* *Format Tabs* - View and edit the same document in multiple markup formats -* *Unified AST* - Lossless conversion between formats -* *GUI* - Gossamer with ReScript frontend -* *TUI* - Ada with AdaCurses for terminal usage -* *Graph Visualization* - ArangoDB for document relationships -* *Accessibility* - OCR, TTS, STT support -* *Pipelines* - Nickel-based import/export transformations +- **TUI** - Ada with AdaCurses for terminal usage -== Supported Formats +- **Graph Visualization** - ArangoDB for document relationships -[cols="1,2", options="header"] -|=== -| Format | Description +- **Accessibility** - OCR, TTS, STT support -| TXT | Plain text -| MD | Markdown (CommonMark) -| ADOC | AsciiDoc -| DJOT | Djot markup -| ORG | Org-mode -| RST | reStructuredText -| TYP | Typst -|=== +- **Pipelines** - Nickel-based import/export transformations -== Quick Start +# Supported Formats -[source,bash] ----- +| Format | Description | +|--------|-----------------------| +| TXT | Plain text | +| MD | Markdown (CommonMark) | +| ADOC | AsciiDoc | +| DJOT | Djot markup | +| ORG | Org-mode | +| RST | reStructuredText | +| TYP | Typst | + +# Quick Start + +```bash # Check dependencies just deps @@ -62,37 +63,36 @@ just run-gui # Run TUI just run-tui ----- +``` + +# Architecture + + crates/ + ├── formatrix-core/ # AST, parsers, renderers + ├── formatrix-gui/ # Gossamer commands + ├── formatrix-db/ # ArangoDB client + └── formatrix-pipeline/ # Nickel executor -== Architecture + tui/src/ # Ada TUI source + ui/src/ # ReScript components + pipelines/ # Nickel pipeline definitions + container/ # Wolfi container configs -[source] ----- -crates/ -├── formatrix-core/ # AST, parsers, renderers -├── formatrix-gui/ # Gossamer commands -├── formatrix-db/ # ArangoDB client -└── formatrix-pipeline/ # Nickel executor +# Development -tui/src/ # Ada TUI source -ui/src/ # ReScript components -pipelines/ # Nickel pipeline definitions -container/ # Wolfi container configs ----- +## Prerequisites -== Development +- Rust (stable) -=== Prerequisites +- Deno -* Rust (stable) -* Deno -* GNAT + gprbuild (for TUI) -* GTK4 + WebKit2GTK (for GUI) +- GNAT + gprbuild (for TUI) -=== Build Commands +- GTK4 + WebKit2GTK (for GUI) -[source,bash] ----- +## Build Commands + +```bash just build # Build all just build-core # Build Rust core only just build-tui # Build Ada TUI only @@ -100,50 +100,53 @@ just build-ui # Build ReScript UI only just test # Run all tests just fmt # Format all code just lint # Lint all code ----- +``` -=== Containers +## Containers -[source,bash] ----- +```bash just container-build # Build Wolfi image just compose-up # Start with ArangoDB just container-run-tui # Run TUI in container ----- +``` -== RSR Compliance +# RSR Compliance This project follows the Rhodium Standard Repositories specification: -* *Tier 2* - Full-featured multi-language project -* See link:RSR_COMPLIANCE.adoc[RSR_COMPLIANCE.adoc] for details +- **Tier 2** - Full-featured multi-language project + +- See RSR_COMPLIANCE for + details + +# Related Scripts + +Automation scripts from +[hyperpolymath/scripts](https://github.com/hyperpolymath/scripts): -== Related Scripts +| Script | Purpose | +|----|----| +| `asdfman.sh` | Manage asdf plugins and versions | +| `init_bashrc_three_ply.sh` | Modular bashrc setup (three-layer architecture) | +| `k-check.sh` | Kinoite cluster validation | +| `k-intune.sh` | Kinoite tuning scripts | +| `langstrap.sh` | Mass language install utilities | +| `sysenv.sh` | System environment setup | +| `touchscreen_hunter_killer.sh` | Touchscreen calibration/management | -Automation scripts from https://github.com/hyperpolymath/scripts[hyperpolymath/scripts]: +These scripts follow the same language policy (Bash, Rust, ReScript, +Deno, Gleam, Guile Scheme) and multi-forge mirroring strategy. -[cols="1,2", options="header"] -|=== -| Script | Purpose +# License -| `asdfman.sh` | Manage asdf plugins and versions -| `init_bashrc_three_ply.sh` | Modular bashrc setup (three-layer architecture) -| `k-check.sh` | Kinoite cluster validation -| `k-intune.sh` | Kinoite tuning scripts -| `langstrap.sh` | Mass language install utilities -| `sysenv.sh` | System environment setup -| `touchscreen_hunter_killer.sh` | Touchscreen calibration/management -|=== +MPL-2.0 with Palimpsest philosophy. -These scripts follow the same language policy (Bash, Rust, ReScript, Deno, Gleam, Guile Scheme) and multi-forge mirroring strategy. +# Links -== License +- [Project State](.machine_readable/6a2/STATE.a2ml) -PMPL-1.0 with Palimpsest philosophy. +- [Ecosystem Position](.machine_readable/6a2/ECOSYSTEM.a2ml) -== Links +- [Architecture Decisions](.machine_readable/6a2/META.a2ml) -* link:.machine_readable/6a2/STATE.a2ml[Project State] -* link:.machine_readable/6a2/ECOSYSTEM.a2ml[Ecosystem Position] -* link:.machine_readable/6a2/META.a2ml[Architecture Decisions] -* link:PALIMPSEST.adoc[Palimpsest Philosophy] +- [Palimpsest Philosophy](PALIMPSEST.adoc)