@dogsbay/dita-ot-plugin 0.0.0-stage → 0.2.0-beta.117

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @dogsbay/dita-ot-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The DITA-OT plugin `com.dogsbay.publish`: publish a DITA map as a dogsbay site with DITA-OT, from a terminal or CI.
+
+| Transtype | Produces |
+| --- | --- |
+| `dogsbay` | A dogsbay site project: `content/*.md`, `content/nav.yml`, `dogsbay.config.yml`, `publish-report.md` |
+| `dogsbay-site` | The same project, then the built site (needs the dogsbay CLI and npm) |
+
+## Requirements
+
+- DITA-OT 4 (tested with 4.3.5), with Java 17 or later
+- Node.js 20 or later
+
+## Install
+
+```bash
+npx -y @dogsbay/dita-ot-plugin@beta install /path/to/dita-ot-4.3.5
+```
+
+This copies the plugin into DITA-OT's `plugins/` folder and runs `dita install`. Other commands:
+
+- `npx -y @dogsbay/dita-ot-plugin@beta zip` prints the path of the plugin zip, for `dita install <zip>`.
+- `npx -y @dogsbay/dita-ot-plugin@beta path` prints the path of the plugin folder.
+
+DITA-OT can also install the zip from npm's CDN: `dita install https://cdn.jsdelivr.net/npm/@dogsbay/dita-ot-plugin@<version>/dist/com.dogsbay.publish-<version>.zip`.
+
+## Publish
+
+```bash
+dita -i guide.ditamap -f dogsbay -o site
+dita -i guide.ditamap -f dogsbay --args.filter=release.ditaval --args.gen.task.lbl=YES -o site
+```
+
+Parameters and details: the plugin's README (`dist/com.dogsbay.publish/README.md`), and "Publishing DITA" in the dogsbay docs.
+
+## Development
+
+- `pnpm turbo build --filter=@dogsbay/dita-ot-plugin...` builds the plugin and the packages its converter comes from (`plugin/` sources, the converter bundled from `packages/dita-publish`) into `dist/`, with the zip and its SHA-256.
+- `pnpm --filter @dogsbay/dita-ot-plugin test` checks the zip and the installer.
+- `scripts/smoke.sh` downloads DITA-OT, installs the plugin (with `dita install <zip>` and with this package's installer) and publishes a sample, as CI would (`--from-npm <version>` tests a release).
+- `tools/` compares the plugin's output with DITA-OT's `html5` output (see `tools/README.md`).
+- Developer notes: `docs-dev/dita-ot-plugin.md`. Plan: `plans/dita-ot-plugin-release.md`.

package/bin/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * dogsbay-dita-ot-plugin: install the DITA-OT plugin com.dogsbay.publish.
+ *
+ *   npx -y @dogsbay/dita-ot-plugin@beta install <dita-ot-dir> [--no-integrate]
+ *   npx -y @dogsbay/dita-ot-plugin@beta zip       prints the plugin zip's path
+ *   npx -y @dogsbay/dita-ot-plugin@beta path      prints the plugin folder's path
+ */
+import { installPlugin, pluginDir, pluginZip, version } from "../lib/index.js";
+
+const [command, ...rest] = process.argv.slice(2);
+const usage = `Usage: dogsbay-dita-ot-plugin <command>
+
+Commands:
+  install <dita-ot-dir> [--no-integrate]  Copy com.dogsbay.publish ${version} into DITA-OT's plugins/
+                                           and run its "dita install"
+  zip                                      Print the path of the plugin zip (for "dita install <zip>")
+  path                                     Print the path of the plugin folder
+`;
+
+try {
+  const unknown = rest.filter((a) => a.startsWith("-") && !(command === "install" && a === "--no-integrate"));
+  if (unknown.length > 0) throw new Error(`Unknown option: ${unknown.join(" ")}\n\n${usage}`);
+  if (command === "install") {
+    const ditaOt = rest.find((a) => !a.startsWith("--"));
+    if (!ditaOt) throw new Error(`install needs the DITA-OT folder\n\n${usage}`);
+    const { target, integrated } = installPlugin(ditaOt, { integrate: !rest.includes("--no-integrate") });
+    console.log(`Installed com.dogsbay.publish ${version} in ${target}${integrated ? "" : " (not integrated: run dita install)"}`);
+  } else if (command === "zip") {
+    console.log(pluginZip);
+  } else if (command === "path") {
+    console.log(pluginDir);
+  } else if (command === undefined || command === "--help" || command === "-h") {
+    console.log(usage);
+  } else {
+    throw new Error(`Unknown command: ${command}\n\n${usage}`);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/dist/com.dogsbay.publish/README.md

@@ -0,0 +1,67 @@
+# com.dogsbay.publish
+
+A DITA-OT plugin that publishes a DITA deliverable as a dogsbay site. DITA stays the source; each publish regenerates the site's `content/` folder (pages of topics removed from the map do not survive), and keeps an existing `dogsbay.config.yml`.
+
+| Transtype | Produces |
+| --- | --- |
+| `dogsbay` | A dogsbay site project: `content/*.md`, `content/nav.yml`, `content/index.md`, `dogsbay.config.yml` (when missing), and `publish-report.md` |
+| `dogsbay-site` | `dogsbay`, then the built site in `astro/dist`: `dogsbay site init --scaffold-only` when the output folder has no Astro project yet, `dogsbay site build`, a package install (unless `dogsbay.site.install=no`), and the Astro build with Pagefind search |
+
+Conditions are resolved by DITA-OT with `--args.filter`, as for any output; each run is one deliverable.
+
+DogsBay XML ships this plugin in its built-in DITA-OT; see the editor's `docs/dita-publishing.md`.
+
+## Requirements
+
+- DITA-OT 4 (tested with 4.3.5)
+- Node.js 20 or later
+- `dogsbay-site` only: the dogsbay CLI and npm (or pnpm or yarn), with network access for the package install
+
+The converter itself is in the plugin: `converter/publish-dita.mjs` is dogsbay's `publish-dita` command bundled into one file, so `dogsbay` needs no dogsbay CLI install. `converter/VERSION` records the dogsbay version and commit it was built from.
+
+## Install
+
+With Node.js (from npm, the same package that builds this plugin):
+
+```bash
+npx -y @dogsbay/dita-ot-plugin@beta install <dita-ot>
+```
+
+With DITA-OT's installer, from the plugin zip:
+
+```bash
+<dita-ot>/bin/dita install https://cdn.jsdelivr.net/npm/@dogsbay/dita-ot-plugin@<version>/dist/com.dogsbay.publish-<version>.zip
+```
+
+The plugin's own version in `plugin.xml` is DITA-OT's form of the dogsbay version: `0.2.0-beta.116` becomes `0.2.0.beta-116`, since DITA-OT allows no dots in a version qualifier.
+
+## Use
+
+```bash
+dita -i guide.ditamap -f dogsbay -o site
+dita -i guide.ditamap -f dogsbay --dogsbay.node=/usr/local/bin/node -o site
+dita -i guide.ditamap -f dogsbay-site --dogsbay.cli=/path/to/dogsbay/packages/cli/bin/cli.js -o site
+dita -i guide.ditamap -f dogsbay --dogsbay.converter=/path/to/dogsbay/packages/dita-publish/bin/cli.js -o site
+```
+
+| Parameter | Default | Meaning |
+| --- | --- | --- |
+| `dogsbay.node` | `node` | The Node.js executable that runs a script converter or `dogsbay.cli`: a command on the PATH or a path |
+| `dogsbay.cli` | `dogsbay` | The dogsbay CLI: a command on the PATH (`dogsbay.cmd` on Windows), or an absolute path to a `.js`, `.mjs` or `.cjs` bin script (run with `dogsbay.node`). `dogsbay-site` uses it for `site init` and `site build` |
+| `dogsbay.converter` | the plugin's `converter/publish-dita.mjs` | The `publish-dita` converter, instead of the plugin's own: a command (`dogsbay-dita`, from `npm i -g @dogsbay/dita-publish`) or a script path, such as the dogsbay repo's `packages/dita-publish/bin/cli.js` |
+| `dogsbay.site.install` | `yes` | `dogsbay-site`: install the site's packages before building |
+| `dogsbay.site.npm` | `npm` | `dogsbay-site`: the package manager that installs and builds the site (`npm`, `pnpm`, `yarn`) |
+| `dogsbay.family.links` | `no` | `yes` adds the parent, previous and next topic links after each topic, as `html5` has them (a dogsbay site has previous/next buttons and a sidebar instead) |
+| `dogsbay.numbering` | `yes` | Number titled tables and figures ("Table 1. ", "Figure 1. ") per topic, as `html5` does, with DITA-OT's localized words |
+| `args.gen.task.lbl` | `NO` | DITA-OT's parameter; `YES` adds task section headings, as in `html5` |
+| `args.rellinks` | all | DITA-OT's parameter; which related links preprocessing keeps |
+
+## How it works
+
+`build_dogsbay.xml` adds the target `dita2dogsbay`, which depends on DITA-OT's `build-init` and `preprocess2` (the same preprocessing as `html5`), then runs the converter, `publish-dita ${dita.temp.dir} -o ${output.dir}`. The converter reads the preprocessed temp files before DITA-OT cleans them up.
+
+The plugin is built and released from the dogsbay repo, `packages/dita-ot-plugin` (`@dogsbay/dita-ot-plugin` on npm). The converter's source is `@dogsbay/dita-publish` (`publishDitaTemp`, over `@dogsbay/format-dita`), bundled with its `bundle:publish-dita`. Developer notes: `docs-dev/dita-ot-plugin.md` and `docs-dev/format-dita-publish.md` in the dogsbay repo.
+
+## Checking the output
+
+`packages/dita-ot-plugin/tools/compare_outputs.py` in the dogsbay repo compares a DITA-OT `html5` build with the built dogsbay site. See the `tools/README.md` next to it.

package/dist/com.dogsbay.publish/build_dogsbay.xml

@@ -0,0 +1,149 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project name="com.dogsbay.publish" xmlns:if="ant:if" xmlns:unless="ant:unless">
+
+  <target name="dogsbay.init">
+    <dirname property="dogsbay.plugin.dir" file="${ant.file.com.dogsbay.publish}"/>
+    <!-- The converter: dogsbay.converter when given (for development, the dogsbay repo's
+         packages/dita-publish/bin/cli.js); otherwise the single-file bundle of `publish-dita`
+         the plugin carries; otherwise `dogsbay-dita` on the PATH. The published dogsbay CLI
+         has no publish-dita. dogsbay-site also needs the dogsbay CLI (dogsbay.cli, default
+         `dogsbay`) for site init and site build. -->
+    <condition property="dogsbay.converter" value="${dogsbay.plugin.dir}/converter/publish-dita.mjs">
+      <available file="${dogsbay.plugin.dir}/converter/publish-dita.mjs"/>
+    </condition>
+    <property name="dogsbay.converter" value="dogsbay-dita"/>
+    <property name="dogsbay.cli" value="dogsbay"/>
+    <property name="dogsbay.node" value="node"/>
+    <property name="dogsbay.site.install" value="yes"/>
+    <property name="dogsbay.site.npm" value="npm"/>
+    <condition property="dogsbay.site.npm.command" value="${dogsbay.site.npm}.cmd" else="${dogsbay.site.npm}">
+      <and>
+        <os family="windows"/>
+        <not><matches string="${dogsbay.site.npm}" pattern="\.(cmd|bat|exe)$"/></not>
+      </and>
+    </condition>
+    <dogsbay-program name="converter"/>
+    <dogsbay-program name="cli"/>
+    <condition property="dogsbay.no.numbering">
+      <equals arg1="${dogsbay.numbering}" arg2="no" casesensitive="false"/>
+    </condition>
+    <condition property="dogsbay.family.links.on">
+      <equals arg1="${dogsbay.family.links}" arg2="yes" casesensitive="false"/>
+    </condition>
+    <condition property="dogsbay.task.labels">
+      <equals arg1="${args.gen.task.lbl}" arg2="YES" casesensitive="false"/>
+    </condition>
+    <condition property="dogsbay.site.do.install">
+      <equals arg1="${dogsbay.site.install}" arg2="yes" casesensitive="false"/>
+    </condition>
+  </target>
+
+  <!-- How to run dogsbay.@{name}: a script (dogsbay.@{name}.is.script, run with dogsbay.node) or a
+       command (dogsbay.@{name}.command) -->
+  <macrodef name="dogsbay-program">
+    <attribute name="name"/>
+    <sequential>
+      <condition property="dogsbay.@{name}.is.script">
+        <matches string="${dogsbay.@{name}}" pattern="\.[cm]?js$"/>
+      </condition>
+      <!-- A relative script path would resolve against DITA-OT's folders, not the directory
+           dita was run from (which Ant cannot see), so it must be absolute -->
+      <fail message="dogsbay.@{name} must be an absolute path to the script: ${dogsbay.@{name}}">
+        <condition>
+          <and>
+            <isset property="dogsbay.@{name}.is.script"/>
+            <not><matches string="${dogsbay.@{name}}" pattern="^(/|[A-Za-z]:[\\/]|\\\\)"/></not>
+          </and>
+        </condition>
+      </fail>
+      <!-- On Windows an npm-installed command is a .cmd shim, which exec does not find by name -->
+      <condition property="dogsbay.@{name}.command" value="${dogsbay.@{name}}.cmd" else="${dogsbay.@{name}}">
+        <and>
+          <os family="windows"/>
+          <not><matches string="${dogsbay.@{name}}" pattern="\.(cmd|bat|exe)$"/></not>
+        </and>
+      </condition>
+    </sequential>
+  </macrodef>
+
+  <!-- Runs dogsbay.@{program} (converter or cli) with the nested args -->
+  <macrodef name="dogsbay-run">
+    <attribute name="program"/>
+    <attribute name="dir" default="${output.dir}"/>
+    <element name="run-args" implicit="true"/>
+    <sequential>
+      <exec executable="${dogsbay.node}" dir="@{dir}" failonerror="true" searchpath="true" if:set="dogsbay.@{program}.is.script">
+        <arg file="${dogsbay.@{program}}"/>
+        <run-args/>
+      </exec>
+      <exec executable="${dogsbay.@{program}.command}" dir="@{dir}" failonerror="true" searchpath="true" unless:set="dogsbay.@{program}.is.script">
+        <run-args/>
+      </exec>
+    </sequential>
+  </macrodef>
+
+  <!-- Site project (Markdown, navigation, config) from DITA-OT's preprocessed temp folder. -->
+  <target name="dita2dogsbay" depends="dogsbay.init, build-init, preprocess2, dogsbay.convert"/>
+
+  <target name="dogsbay.convert">
+    <echo level="info">publish-dita ${dita.temp.dir} -o ${output.dir} (${dogsbay.converter})</echo>
+    <mkdir dir="${output.dir}"/>
+    <dogsbay-run program="converter">
+      <arg value="publish-dita"/>
+      <arg file="${dita.temp.dir}"/>
+      <arg value="-o"/>
+      <arg file="${output.dir}"/>
+      <arg value="--report"/>
+      <arg file="${output.dir}/publish-report.md"/>
+      <arg value="--task-labels" if:set="dogsbay.task.labels"/>
+      <arg value="--family-links" if:set="dogsbay.family.links.on"/>
+      <arg value="--no-numbering" if:set="dogsbay.no.numbering"/>
+      <arg value="--dita-dir"/>
+      <arg file="${dita.dir}"/>
+      <!-- build-init always sets default.language (en); topics' xml:lang still wins -->
+      <arg value="--default-language" if:set="default.language"/>
+      <arg value="${default.language}" if:set="default.language"/>
+    </dogsbay-run>
+  </target>
+
+  <!-- The built site: scaffold when missing, dogsbay site build, then the Astro build with Pagefind. -->
+  <target name="dita2dogsbay-site" depends="dita2dogsbay, dogsbay.site"/>
+
+  <!-- The site steps are separate targets, so a build can time each one -->
+  <target name="dogsbay.site" depends="dogsbay.site.init, dogsbay.site.generate, dogsbay.site.install, dogsbay.site.astro"/>
+
+  <!-- Scaffold the Astro project when the output folder has none yet -->
+  <target name="dogsbay.site.init">
+    <available file="${output.dir}/astro/package.json" property="dogsbay.site.scaffolded"/>
+    <dogsbay-run program="cli" unless:set="dogsbay.site.scaffolded">
+      <arg value="site"/>
+      <arg value="init"/>
+      <arg value="."/>
+      <arg value="--yes"/>
+      <arg value="--scaffold-only"/>
+    </dogsbay-run>
+  </target>
+
+  <!-- dogsbay site build: the Astro source from content/ -->
+  <target name="dogsbay.site.generate">
+    <dogsbay-run program="cli">
+      <arg value="site"/>
+      <arg value="build"/>
+    </dogsbay-run>
+  </target>
+
+  <!-- The site's package install (dogsbay.site.install=yes, the default) -->
+  <target name="dogsbay.site.install" if="dogsbay.site.do.install">
+    <exec executable="${dogsbay.site.npm.command}" dir="${output.dir}/astro" failonerror="true" searchpath="true">
+      <arg value="install"/>
+    </exec>
+  </target>
+
+  <!-- The Astro build and the Pagefind search index -->
+  <target name="dogsbay.site.astro">
+    <exec executable="${dogsbay.site.npm.command}" dir="${output.dir}/astro" failonerror="true" searchpath="true">
+      <arg value="run"/>
+      <arg value="build"/>
+    </exec>
+  </target>
+</project>

package/dist/com.dogsbay.publish/converter/VERSION

@@ -0,0 +1 @@
+0.2.0-beta.117