From 7d3d9a02f211eeeb9a3d55b0e044fb878cde80c4 Mon Sep 17 00:00:00 2001
From: David Jencks <djencks@apache.org>
Date: Thu, 21 May 2020 14:23:58 -0700
Subject: [PATCH] Document how to compile a local asciidoctor ruby code base

---
 CONTRIBUTING-CODE.adoc                 | 26 ++++++++++++++++++++++++++
 packages/core/tasks/module/compiler.js |  2 +-
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING-CODE.adoc b/CONTRIBUTING-CODE.adoc
index f14090238..19a753bfb 100644
--- a/CONTRIBUTING-CODE.adoc
+++ b/CONTRIBUTING-CODE.adoc
@@ -54,6 +54,9 @@ To build Asciidoctor.js, simply run the npm `build` script from the root of the
 
  $ npm run build --prefix packages/core
 
+WARNING: The build system does not automate updating the dependency on ruby asciidoctor.
+If there is any chance the asciidoctor.js copy of the asciidoctor ruby code is out of date, run `npm clean --prefix packages/core`.
+
 NOTE: The build task will make some minor code changes on Asciidoctor Ruby code.
 As you may know, {uri-mdn-string}[strings are immutable] in JavaScript, so we need to replace the `gsub!` and `sub!` methods.
 These changes are made at build time to keep the Ruby code as fast as possible.
@@ -77,6 +80,29 @@ For instance to build against Asciidoctor (Ruby) v2.0.10 use:
 
  $ ASCIIDOCTOR_CORE_VERSION=v2.0.10 npm run build --prefix packages/core
 
+==== Building against a local copy of Ruby Asciidoctor
+
+The transpilation relies on a copy of the Ruby source in `packages/core/build/asciidoctor`.
+The build instructions above supply this by unpacking a tar.gz of the repository constructed by GitHub.
+Alternatively, you can supply this copy yourself.
+For the following posix-centric suggestions, assume `ASCIIDOCTOR_RB` is the local location of your Asciidoctor Ruby project.
+
+* Remove the current (contents of the) Ruby source directory: `rm -rf packages/core/build/asciidoctor`
+* Choose a method:
+** Using a symlink: `ln -s $ASCIIDOCTOR_RB packages/core/build/asciidoctor`
+** Copying: `cp -r $ASCIIDOCTOR_RB packages/core/build/`
+** Unpacking a gem:
+----
+mkdir packages/core/build/asciidoctor
+tar -xf $ASCIIDOCTOR_RB/pkg/asciidoctor-*.gem -C packages/core/build --include data.tar.gz
+tar -xzf packages/core/build/data.tar.gz -C packages/core/build/asciidoctor
+----
+* For all of these, `touch packages/core/build/asciidoctor.tar.gz` will prevent `npm build --prefix packages/core` from overwriting your copy with a downloaded one.
+* To actually use your local source you'll need to force recompile by:
+----
+npm run clean:core --prefix packages/core
+----
+
 ==== Using "quick" mode
 
 By default the build will run the whole tests suite but if you want to quickly iterate on your code, we recommend to use the task `build:quick`:
diff --git a/packages/core/tasks/module/compiler.js b/packages/core/tasks/module/compiler.js
index 78e7d84b5..301a166ea 100644
--- a/packages/core/tasks/module/compiler.js
+++ b/packages/core/tasks/module/compiler.js
@@ -40,7 +40,7 @@ const compileRuntimeEnvironments = (environments) => {
     compileExt('asciidoctor', environment, skipped)
   })
   if (skipped.length > 0) {
-    log.info(`${skipped.join(', ')} files already exist, skipping "compile" task.\nTIP: Use "npm run clean:ext" to compile again from Ruby sources.`)
+    log.info(`${skipped.join(', ')} files already exist, skipping "compile" task.\nTIP: Use "npm run clean:patch" to compile again from Ruby sources.`)
   }
 }