From 3ea1f51deb1f9001830c03b2f395f64f85119d49 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 26 Dec 2025 11:11:31 +0000 Subject: [PATCH] Adopt eclipse-ssg canonical form for COBOL SSG identity Restructure README.adoc to follow the hyperpolymath SSG documentation pattern established by eclipse-ssg: - Add tagline: "Self-documenting static site generator in COBOL" - Add poetic hook: "Let divisions organize. Let records structure." - "Who Is This For?" audience targeting section - "Why Division One?" with 4 technical justifications and code examples - COBOL Division Primer table mapping divisions to SSG components - Architecture diagram showing division-based processing pipeline - Quick Start with GnuCOBOL build instructions - poly-ssg-mcp integration section Maintains standalone value while positioning as poly-ssg satellite. --- README.adoc | 245 +++++++++++++++++++++++++++------------------------- 1 file changed, 126 insertions(+), 119 deletions(-) diff --git a/README.adoc b/README.adoc index 92a5dfe..c2b04b0 100644 --- a/README.adoc +++ b/README.adoc @@ -1,177 +1,184 @@ = Division One SSG -Jonathan D.A. Jewell -v0.1.0, 2025-12-17 +:author: Jonathan D.A. Jewell +:email: jonathan@hyperpolymath.org +:revnumber: v0.1.0 +:revdate: 2025-12-17 :toc: left :toclevels: 3 :icons: font :source-highlighter: highlight.js :experimental: -== Overview +image:https://img.shields.io/badge/RSR-compliant-blue[RSR compliant] +image:https://img.shields.io/badge/poly--ssg-integrated-purple[poly-ssg integrated] +image:https://img.shields.io/badge/license-MIT%20OR%20AGPL--3.0--or--later-green[License: MIT OR AGPL-3.0-or-later] +image:https://img.shields.io/badge/status-experimental-orange[Status: experimental] -Division One SSG is a satellite repository providing **28 SSG (Static Site Generator) adapters** synchronized from the https://github.com/hyperpolymath/poly-ssg-mcp[poly-ssg-mcp hub]. These adapters enable unified access to diverse static site generators through the Model Context Protocol (MCP). +*Self-documenting static site generator in COBOL.* -=== Features +_Let divisions organize. Let records structure. Let pages compile._ -* **28 SSG Adapters** covering 17+ programming languages -* **MCP Integration** for standardized tool interfaces -* **Secure by Design** using Deno's permission model -* **RSR Compliant** following Rhodium Standard Repository guidelines +== Who Is This For? -== Quick Start +* **COBOL practitioners** seeking modern build tooling that speaks their language +* **Enterprise developers** wanting bank-grade reliability for content pipelines +* **Language preservationists** exploring COBOL beyond transaction processing +* **Polyglot SSG explorers** via https://github.com/hyperpolymath/poly-ssg-mcp[poly-ssg-mcp] integration -=== Prerequisites +== Why Division One? -* https://deno.land/[Deno] runtime (v1.40+) -* Target SSG installed (e.g., `zola`, `hakyll`, etc.) +=== 1. Self-Documenting Structure -=== Usage +COBOL's English-like syntax makes site configuration readable without comments: -[source,javascript] +[source,cobol] ---- -// Import an adapter -import * as zola from "./adapters/zola.js"; - -// Connect to the SSG -await zola.connect(); - -// Use available tools -const result = await zola.tools[1].execute({ path: "./my-site" }); // build - -// Disconnect -await zola.disconnect(); + IDENTIFICATION DIVISION. + PROGRAM-ID. SITE-CONFIG. + + DATA DIVISION. + WORKING-STORAGE SECTION. + 01 SITE-METADATA. + 05 SITE-TITLE PIC X(80) VALUE "My Technical Blog". + 05 SITE-AUTHOR PIC X(40) VALUE "J. Developer". + 05 BASE-URL PIC X(120) VALUE "https://blog.example.com". + 05 BUILD-DRAFTS PIC 9 VALUE 0. ---- -== Supported SSGs +=== 2. Record-Oriented Content Processing -[cols="1,3,2"] -|=== -|Language |SSGs |Adapters +COBOL's native record handling maps perfectly to front matter and structured content: -|Rust -|Zola, Cobalt, mdBook -|`zola.js`, `cobalt.js`, `mdbook.js` +[source,cobol] +---- + 01 POST-RECORD. + 05 POST-TITLE PIC X(200). + 05 POST-DATE PIC 9(8). + 05 POST-TAGS. + 10 TAG-ENTRY PIC X(30) OCCURS 10 TIMES. + 05 POST-BODY PIC X(65535). +---- -|Haskell -|Hakyll, Ema -|`hakyll.js`, `ema.js` +=== 3. Division Architecture -|Elixir -|Serum, NimblePublisher, Tableau -|`serum.js`, `nimble-publisher.js`, `tableau.js` +Site structure mirrors COBOL's four-division model: -|Julia -|Franklin, Documenter, StaticWebPages -|`franklin.js`, `documenter.js`, `staticwebpages.js` +[cols="1,2"] +|=== +|COBOL Division |Site Component -|Clojure -|Cryogen, Perun, Babashka -|`cryogen.js`, `perun.js`, `babashka.js` +|IDENTIFICATION +|Site metadata, author, version -|Racket -|Frog, Pollen -|`frog.js`, `pollen.js` +|ENVIRONMENT +|Input/output paths, build targets -|Scala -|Laika, ScalaTex -|`laika.js`, `scalatex.js` +|DATA +|Content records, templates, assets -|OCaml -|YOCaml -|`yocaml.js` +|PROCEDURE +|Build logic, transformations, rendering +|=== -|F# -|Fornax -|`fornax.js` +=== 4. Enterprise-Grade Reliability -|Kotlin -|Orchid -|`orchid.js` +The same precision that processes billions in daily transactions ensures your content pipeline never loses a byte. *No truncation. No encoding errors. No silent failures.* -|Swift -|Publish -|`publish.js` +== Quick Start -|Crystal -|Marmot -|`marmot.js` +=== Prerequisites -|Nim -|Nimrod -|`nimrod.js` +* GnuCOBOL 3.2+ (`cobc`) +* POSIX shell environment -|D -|Reggae -|`reggae.js` +=== Build & Run -|Tcl -|Wub -|`wub.js` +[source,bash] +---- +# Compile the generator +cobc -x -o divisionone src/divisionone.cob -|Erlang -|Zotonic -|`zotonic.js` +# Initialize a new site +./divisionone --init my-site -|Common Lisp -|Coleslaw -|`coleslaw.js` -|=== +# Build the site +./divisionone --build my-site +---- == Architecture -=== Adapter Pattern +---- + ┌─────────────────────────────────────────┐ + │ COBOL Runtime │ + └─────────────────────────────────────────┘ + │ + ┌───────────────────────────┼───────────────────────────┐ + ▼ ▼ ▼ + ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ + │ CONFIG │ │ CONTENT │ │ TEMPLATE │ + │ READER │ │ PARSER │ │ ENGINE │ + │ (ENVIRON) │ │ (DATA) │ │ (PROCED) │ + └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ + │ │ │ + └──────────────────────────┼──────────────────────────┘ + ▼ + ┌─────────────┐ + │ FILE │ + │ WRITER │ + └─────────────┘ +---- -Each adapter exports: +== Features -* `name` - SSG name -* `language` - Implementation language -* `description` - Brief description -* `connect()` - Initialize connection -* `disconnect()` - Cleanup -* `isConnected()` - Connection status -* `tools[]` - Available MCP tools +* **Incremental builds** — only recompile changed content records +* **Parallel section processing** — leverage COBOL's section-based execution +* **Fixed-width field validation** — catch content length issues at build time +* **COPY statement templating** — reusable content structures via copybooks +* **EBCDIC/ASCII agnostic** — works with any character encoding -=== Security +== COBOL Division Primer -* **Command Execution**: Uses `Deno.Command` with array-based arguments (immune to command injection) -* **No Shell Interpolation**: All parameters passed as discrete arguments -* **Deno Permissions**: Leverages Deno's security sandbox +[cols="1,1,3"] +|=== +|Division |Purpose |Division One Usage -== Project Structure +|`IDENTIFICATION` +|Program metadata +|Site name, version, author attribution ----- -divisionone-ssg/ -├── adapters/ # 28 SSG adapter implementations -├── .github/ # GitHub workflows and templates -├── META.scm # Architecture decisions -├── ECOSYSTEM.scm # Ecosystem positioning -├── STATE.scm # Project state tracking -├── SECURITY.md # Security policy -├── CONTRIBUTING.md # Contribution guidelines -├── CODE_OF_CONDUCT.md # Community guidelines -└── ROADMAP.md # Development roadmap ----- +|`ENVIRONMENT` +|I/O configuration +|Source paths, output directories, asset locations -== Related Projects +|`DATA` +|Variable declarations +|Content records, template variables, configuration -* https://github.com/hyperpolymath/poly-ssg-mcp[poly-ssg-mcp] - Hub repository with unified MCP server -* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium Standard Repositories] - Repository guidelines +|`PROCEDURE` +|Executable logic +|Build steps, content transformation, file generation +|=== -== Contributing +== Requirements -See link:CONTRIBUTING.md[CONTRIBUTING.md] for guidelines. +* **GnuCOBOL 3.2+** — open-source COBOL compiler +* Optional: **cobc-debug** for development builds -== Security +== Part of poly-ssg -See link:SECURITY.md[SECURITY.md] for reporting vulnerabilities. +Division One integrates with the polyglot SSG ecosystem through the Model Context Protocol: -== License +[source,bash] +---- +# Via poly-ssg-mcp +mcp call poly-ssg divisionone:build --path ./my-site +---- -Dual-licensed under https://opensource.org/licenses/MIT[MIT] OR https://www.gnu.org/licenses/agpl-3.0.html[AGPL-3.0-or-later]. +See https://github.com/hyperpolymath/poly-ssg-mcp[poly-ssg-mcp] for unified access to 28+ static site generators across 17 languages. -== Acknowledgments +== License -Part of the https://github.com/hyperpolymath[hyperpolymath] ecosystem. +SPDX-License-Identifier: `MIT OR AGPL-3.0-or-later` ---