Initial work on extended asciidoc

.gitignore

@@ -11,3 +11,4 @@ DerivedData/
 artifacts/
 .vscode
 .cache
+.swiftpm

Package.swift

@@ -19,6 +19,7 @@ let package = Package(
       .library(name: "AsciiDocExtensions", targets: ["AsciiDocExtensions"]),
       .library(name: "AsciiDocTools", targets: ["AsciiDocTools"]),
       .library(name: "AsciiDocAntora", targets: ["AsciiDocAntora"]),
+      .library(name: "AsciiDocPagedRendering", targets: ["AsciiDocPagedRendering"]),
 
       .executable(name: "asciidoc-swift", targets: ["asciidoc-swift"])
     ],
@@ -28,12 +29,15 @@ let package = Package(
         .package(url: "https://github.com/openorbit/swift-hunspell", branch: "main"),
         .package(url: "https://github.com/openorbit/swift-yaml", branch: "main"),
         .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
+        .package(url: "https://github.com/mattt/swift-yyjson.git", from: "0.5.0"),
     ],
     targets: [
         // Core parsing/semantic engine (Foundation + RegexBuilder only)
         .target(
             name: "AsciiDocCore",
-            dependencies: [],
+            dependencies: [
+                .product(name: "YYJSON", package: "swift-yyjson")
+            ],
             path: "Sources/AsciiDocCore",
             swiftSettings: [
                 // Keep indexes Unicode-safe, discourage unsafe operations
@@ -45,6 +49,7 @@ let package = Package(
             dependencies: [
                 .product(name: "Stencil", package: "Stencil"),
                 "AsciiDocCore",
+                "AsciiDocPagedRendering",
             ],
             path: "Sources/AsciiDocRender",
             swiftSettings: [
@@ -81,6 +86,11 @@ let package = Package(
             path: "Sources/AsciiDocAntora"
         ),
 
+        .target(
+            name: "AsciiDocPagedRendering",
+            dependencies: ["AsciiDocCore"],
+            path: "Sources/AsciiDocPagedRendering"
+        ),
 
         // CLI executable that the TCK will invoke
         .executableTarget(
@@ -91,6 +101,7 @@ let package = Package(
                 "AsciiDocExtensions",
                 "AsciiDocTools",
                 "AsciiDocAntora",
+                "AsciiDocPagedRendering",
                 .product(name: "ArgumentParser", package: "swift-argument-parser")
             ],
             path: "Sources/asciidoc-swift",
@@ -105,7 +116,7 @@ let package = Package(
         // Unit tests for the core; add fixture files under Tests/AsciiDocCoreTests/Fixtures as needed
         .testTarget(
             name: "AsciiDocCoreTests",
-            dependencies: ["AsciiDocCore", "AsciiDocTools", "AsciiDocRender"],
+            dependencies: ["AsciiDocCore", "AsciiDocTools", "AsciiDocRender", "AsciiDocPagedRendering"],
             path: "Tests/AsciiDocCoreTests",
             swiftSettings: [
                 .interoperabilityMode(.Cxx)

README.adoc

@@ -2,6 +2,32 @@
 
 A swift implementation of AsciiDoc
 
+== XAD Overview
+
+XAD is an opt-in set of extensions that adds structured, JSON-like attributes and layout helpers for paged media output.
+Enable it by passing the `--xad` flag or by using a backend that requires XAD.
+
+Current additions include:
+
+* Typed attributes parsed from JSON/JSON5 values (dictionaries and arrays) in header attribute entries.
+* Multi-line JSON/JSON5 attribute values without explicit continuation escapes.
+* Attribute accessors for nested values (e.g. `foo.bar` and bracket indexing).
+* XAD access macros for nested values (`get::path[]` and `set::path[value]`), plus shorthand access with `{foo.bar}`.
+* User-defined macros (block and inline) with parameters, defaults, and `{body}` substitution for block macros.
+* Macro recursion detection (direct and indirect) with warnings.
+* Macro side-effect allow list via `effects="docpush docset docput"` (or `effects=all`).
+* Control directives: `if`/`elif`/`else`/`end` and `for` loops, with expression validation warnings.
+* Document variables (`docset`, `docpush`, `docput`) for building registries under `doc.*`.
+* Layout-oriented attributes intended for paged and PDF-style renderers.
+* Scoped attributes for block- and section-level overrides.
+
+Scoped attributes:
+
+* `attrpush::[]` and `attrpop::[]` push/pop the attribute environment.
+* `blockattr::[foo=bar]` applies attributes to the next block only.
+* `[blockattr]` followed by a listing-style block of `:name:` entries applies to the next block only.
+* `attrs::[foo=bar]` (or `[attrs]` + listing block) immediately after a section title scopes attributes to that section.
+
 == License
 
 Licensed under the Apache License, Version 2.0.