SOLR-12786: Update Ref Guide build tool versions & fix section links for new format requirements

dev-tools/scripts/jenkins.build.ref.guide.sh

@@ -60,11 +60,10 @@ echoRun "rvm $RUBY_VERSION@$GEMSET"      # Activate this project's gemset
 
 # Install gems in the gemset.  Param --force disables dependency conflict detection.
 echoRun "gem install --force --version 3.5.0 jekyll"
-echoRun "gem uninstall --all --ignore-dependencies asciidoctor"  # Get rid of all versions
+echoRun "gem install --force --version 3.0.0 jekyll-asciidoc"
-echoRun "gem install --force --version 1.5.6.2 asciidoctor"
+echoRun "gem install --force --version 4.0.1 slim"
-echoRun "gem install --force --version 2.1.0 jekyll-asciidoc"
+echoRun "gem install --force --version 2.0.10 tilt"
-echoRun "gem install --force --version 1.1.2 pygments.rb"
+echoRun "gem install --force --version 1.1.5 concurrent-ruby"
-echoRun "gem install --force --version 3.0.9 slim"
 
 cd solr/solr-ref-guide
 

lucene/ivy-versions.properties

@@ -223,9 +223,10 @@ org.apache.zookeeper.version = 3.5.5
 /org.apache.zookeeper/zookeeper = ${org.apache.zookeeper.version}
 /org.apache.zookeeper/zookeeper-jute = ${org.apache.zookeeper.version}
 
-# v1.6.0-alpha.5 of asciidoctor-ant includes asciidoctorj-pdf 1.5.0-alpha.16,
+# v1.6.2 of asciidoctor-ant includes asciidoctorj 1.6.2, which uses
-# which is the same as asciidoctor-pdf 1.5.0-alpha.16
+# asciidoctor 1.5.8, and asciidoctorj-pdf 1.5.0-alpha.16, which is the same
-/org.asciidoctor/asciidoctor-ant = 1.6.0-alpha.5
+# as asciidoctor-pdf 1.5.0-alpha.16
+/org.asciidoctor/asciidoctor-ant = 1.6.2
 
 /org.aspectj/aspectjrt = 1.8.0
 

solr/CHANGES.txt

@@ -364,6 +364,8 @@ Other Changes
 
 * SOLR-13787: An annotation based system to write v2 APIs (noble)
 
+* SOLR-12786: Update Ref Guide build tool versions (Cassandra)
+
 ==================  8.2.0 ==================
 
 Consult the LUCENE_CHANGES.txt file for additional, low level, changes in this release.

solr/licenses/asciidoctor-ant-1.6.0-alpha.5.jar.sha1

@@ -1 +0,0 @@
-741c5e5afd8a2c7d415feb7b9a8d6fe8a6cca57c

solr/licenses/asciidoctor-ant-1.6.2.jar.sha1

@@ -0,0 +1 @@
+c5ba599e3918e7a3316e6bf110cadd5aeb2a026b

solr/solr-ref-guide/README.adoc

@@ -23,17 +23,21 @@ Raw content is stored in Asciidoc (`.adoc`) formatted files in the `src/` direct
 == Prerequisites for Building
 These files are processed with AsciiDoctor in 2 different ways:
 
-* Via Jekyll to build an HTML browsable version of the Ref Guide.
+* HTML version, using Jekyll:
-** Prerequisites: `Ruby` (v2.1 or higher) and the following gems must be installed:
+** `Ruby` (v2.3 or higher)
-*** `jekyll`: v3.5, not v4.x. Use `gem install jekyll --force --version 3.5.0` to force install of Jekyll 3.5.0.
+** The following gems must be installed:
-*** `asciidoctor`: v1.5.6.2, not 1.5.7 or higher. Use `gem install asciidoctor --force --version 1.5.6.2`. NOTE: You must do this before installing `jekyll-asciidoc` or you'll get a version of Asciidoctor that we can't use yet.
+*** `jekyll`: v3.5, not v4.x.
-*** `jekyll-asciidoc`: v2.1 or higher. Use `gem install jekyll-asciidoc` to install.
+Use `gem install jekyll --force --version 3.5.0` to force install of v3.5.0.
-*** `pygments.rb`: v1.1.2 or higher. Use `gem install pygments.rb` to install.
+*** `jekyll-asciidoc`: v2.1 or higher; latest version (3.0.0) is fine.
-// The following is only necessary until we are on Asciidoctor 1.5.8 or higher.
+Use `gem install jekyll-asciidoc` to install.
-// See https://github.com/asciidoctor/asciidoctor/issues/2928 for details of the problem with Slim 4.x and higher.
+*** `slim`: v3.0 or higher; latest version (4.0.1) is fine.
-*** `slim`: v3.0.1 or higher, only to 3.0.9. Do *NOT* use Slim 4.x. Use `gem install slim --force --version 3.0.9` to install.
+Use `gem install slim` to install.
-* Via `asciidoctor-ant` to build the officially released PDF version of the Ref Guide.
+*** `tilt`: v1.0 or higher; latest version (2.0.10) is fine.
-** Prerequisites: None beyond those required to use the main Lucene/Solr build: Java, and Ant.
+Use `gem install tilt` to install.
+*** `concurrent-ruby`: v1.0 or higher; latest version (1.1.5) is fine.
+Use `gem install concurrent-ruby` to install.
+* PDF version, via `asciidoctor-ant`:
+** None beyond those required to use the main Lucene/Solr build: Java, and Ant.
 
 == Building the Guide
 For details on building the ref guide, see `ant -p`.

solr/solr-ref-guide/src/_config.yml.template

@@ -94,7 +94,7 @@ asciidoctor:
     <<: *solr-attributes-ref
     attribute-missing: "warn"
     icons: "font"
-    source-highlighter: "pygments"
+    source-highlighter: "rouge"
-    pygments-css: "style"
+    rouge-theme: "thankful-eyes"
     # NOTE: do *NOT* use an self-empty div tag (ie: <div/>) here - it will break jquery
     section-toc: "<div class=\"toc section-toc\"></div>"

solr/solr-ref-guide/src/basic-authentication-plugin.adoc

@@ -71,7 +71,7 @@ If you are using SolrCloud, you must upload `security.json` to ZooKeeper. You ca
 bin/solr zk cp file:path_to_local_security.json zk:/security.json -z localhost:9983
 ----
 
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
 
 === Caveats
 

solr/solr-ref-guide/src/common-query-parameters.adoc

@@ -102,7 +102,7 @@ fq=+popularity:[10 TO *] +section:0
 ----
 
 * The document sets from each filter query are cached independently. Thus, concerning the previous examples: use a single `fq` containing two mandatory clauses if those clauses appear together often, and use two separate `fq` parameters if they are relatively independent. (To learn about tuning cache sizes and making sure a filter cache actually exists, see <<the-well-configured-solr-instance.adoc#the-well-configured-solr-instance,The Well-Configured Solr Instance>>.)
-* It is also possible to use <<the-standard-query-parser.adoc#differences-between-lucene-s-classic-query-parser-and-solr-s-standard-query-parser,filter(condition) syntax>> inside the `fq` to cache clauses individually and - among other things - to achieve union of cached filter queries.
+* It is also possible to use <<the-standard-query-parser.adoc#differences-between-lucenes-classic-query-parser-and-solrs-standard-query-parser,filter(condition) syntax>> inside the `fq` to cache clauses individually and - among other things - to achieve union of cached filter queries.
 
 * As with all parameters: special characters in an URL need to be properly escaped and encoded as hex values. Online tools are available to help you with URL-encoding. For example: http://meyerweb.com/eric/tools/dencoder/.
 

solr/solr-ref-guide/src/enabling-ssl.adoc

@@ -247,7 +247,7 @@ If you have set up your ZooKeeper cluster to use a <<taking-solr-to-production.a
 
 === Run SolrCloud with SSL
 
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) you can omit `-z <zk host string>` from all of the `bin/solr`/`bin\solr.cmd` commands below.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from all of the `bin/solr`/`bin\solr.cmd` commands below.
 
 ==== Create Solr Home Directories for Two Nodes
 

solr/solr-ref-guide/src/kerberos-authentication-plugin.adoc

@@ -298,7 +298,7 @@ Once the configuration is complete, you can start Solr with the `bin/solr` scrip
 bin/solr -c -z server1:2181,server2:2181,server3:2181/solr
 ----
 
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
 
 === Test the Configuration
 

solr/solr-ref-guide/src/metrics-reporting.adoc

@@ -87,7 +87,7 @@ The metrics available in your system can be customized by modifying the `<metric
 
 TIP: See also the section <<format-of-solr-xml.adoc#format-of-solr-xml,Format of Solr.xml>> for more information about the `solr.xml` file, where to find it, and how to edit it.
 
-=== The <metrics><hiddenSysProps> Element
+=== The <metrics> <hiddenSysProps> Element
 
 This section of `solr.xml` allows you to define the system properties which are considered system-sensitive and should not be exposed via the Metrics API.
 
@@ -106,11 +106,11 @@ If this section is not defined, the following default configuration is used whic
 </metrics>
 ----
 
-=== The <metrics><reporters> Element
+=== The <metrics> <reporters> Element
 
 Reporters consume the metrics data generated by Solr. See the section <<Reporters>> below for more details on how to configure custom reporters.
 
-=== The <metrics><suppliers> Element
+=== The <metrics> <suppliers> Element
 
 Suppliers help Solr generate metrics data. The `<metrics><suppliers>` section of `solr.xml` allows you to define your own implementations of metrics and configure parameters for them.
 

solr/solr-ref-guide/src/resource-and-plugin-loading.adoc

@@ -46,7 +46,7 @@ CAUTION: By default, ZooKeeper's file size limit is 1MB. If your files are large
 
 Under standalone Solr, when looking up a plugin or resource to be loaded, Solr's resource loader will first look under the `<instanceDir>/conf/` directory.  If the plugin or resource is not found, the configured plugin and resource file paths are searched - see the section <<Lib Directives in SolrConfig>> below.
 
-On core load, Solr's resource loader constructs a list of paths (subdirectories and jars), first under <<solr_home-lib,`solr_home/lib`>>, and then under directories pointed to by <<Lib Directives in SolrConfig,`<lib/>` directives in SolrConfig>>.
+On core load, Solr's resource loader constructs a list of paths (subdirectories and jars), first under <<solr_homelib,`solr_home/lib`>>, and then under directories pointed to by <<Lib Directives in SolrConfig,`<lib/>` directives in SolrConfig>>.
 
 When looking up a resource or plugin to be loaded, the paths on the list are searched in the order they were added.
 

solr/solr-ref-guide/src/setting-up-an-external-zookeeper-ensemble.adoc

@@ -201,7 +201,7 @@ And create the `myid` file in the `/var/lib/zookeeper` directory:
 Repeat this for servers 4 and 5 if you are creating a 5-node ensemble (a rare case).
 
 
-===  ZooKeeper Environment Configuration
+=== ZooKeeper Environment Configuration
 
 To ease troubleshooting in case of problems with the ensemble later, it's recommended to run ZooKeeper with logging enabled and with proper JVM garbage collection (GC) settings.
 
@@ -295,9 +295,9 @@ For example, to point the Solr instance to the ZooKeeper you've started on port
 bin/solr start -e cloud -z zk1:2181,zk2:2181,zk3:2181/solr
 ----
 
-=== Updating Solr's Include Files
+=== Updating Solr Include Files
 
-If you update Solr's include file (`solr.in.sh` or `solr.in.cmd`), which overrides defaults used with `bin/solr`, you will not have to use the `-z` parameter with `bin/solr` commands.
+If you update Solr include files (`solr.in.sh` or `solr.in.cmd`), which overrides defaults used with `bin/solr`, you will not have to use the `-z` parameter with `bin/solr` commands.
 
 
 [.dynamic-tabs]

solr/solr-ref-guide/src/solr-control-script-reference.adoc

@@ -60,7 +60,7 @@ Start Solr in SolrCloud mode, which will also launch the embedded ZooKeeper inst
 +
 This option can be shortened to simply `-c`.
 +
-If you are already running a ZooKeeper ensemble that you want to use instead of the embedded (single-node) ZooKeeper, you should also either specify `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) or pass the -z parameter.
+If you are already running a ZooKeeper ensemble that you want to use instead of the embedded (single-node) ZooKeeper, you should also either specify `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) or pass the -z parameter.
 +
 For more details, see the section <<SolrCloud Mode>> below.
 +
@@ -172,7 +172,7 @@ The `-c` and `-cloud` options are equivalent:
 
 If you specify a ZooKeeper connection string, such as `-z 192.168.1.4:2181`, then Solr will connect to ZooKeeper and join the cluster.
 
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) you can omit `-z <zk host string>` from all `bin/solr` commands.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from all `bin/solr` commands.
 
  When starting Solr in SolrCloud mode, if you do not define `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` nor specify the `-z` option, then Solr will launch an embedded ZooKeeper server listening on the Solr port + 1000, i.e., if Solr is running on port 8983, then the embedded ZooKeeper will be listening on port 9983.
 

solr/solr-ref-guide/src/solr-tutorial.adoc

@@ -513,7 +513,7 @@ This starts the first node. When it's done start the second node, and tell it ho
 
 `./bin/solr start -c -p 7574 -s example/cloud/node2/solr -z localhost:9983`
 
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
 
 === Create a New Collection
 

solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc

@@ -676,7 +676,7 @@ The `remove-policy` command accepts a policy name to be removed from Solr. The p
 
 If you attempt to remove a policy that is being used by a collection, this command will fail to delete the policy until the collection itself is deleted.
 
-=== Create/Update Trigger
+=== Create or Update a Trigger
 
 The `set-trigger` command can be used to create a new trigger or overwrite an existing one.
 
@@ -732,7 +732,7 @@ The `remove-trigger` command can be used to remove a trigger. It accepts a singl
 }
 ----
 
-=== Create/Update Trigger Listener
+=== Create or Update a Trigger Listener
 
 The `set-listener` command can be used to create or modify a listener for a trigger.
 

solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc

@@ -55,7 +55,7 @@ generated, which may significantly differ due to the rate limits set by `waitFor
 indicates the nodes that were lost or added.
 
 == Trigger Configuration
-Trigger configurations are managed using the <<solrcloud-autoscaling-api.adoc#write-api,Autoscaling Write API>> with the commands `<<solrcloud-autoscaling-api.adoc#create-update-trigger,set-trigger>>`, `<<solrcloud-autoscaling-api.adoc#remove-trigger,remove-trigger>>`,
+Trigger configurations are managed using the <<solrcloud-autoscaling-api.adoc#write-api,Autoscaling Write API>> with the commands `<<solrcloud-autoscaling-api.adoc#create-or-update-a-trigger,set-trigger>>`, `<<solrcloud-autoscaling-api.adoc#remove-trigger,remove-trigger>>`,
 `suspend-trigger`, and `resume-trigger`.
 
 === Trigger Properties
@@ -606,4 +606,4 @@ old markers for such events so that they don't accumulate over time. This trigge
 === `solr.ExecutePlanAction`
 This action simply executes any collection admin requests generated by other
 actions - in particular, in the default configuration it executes `DELETESHARD` requests produced by
-`solr.InactiveShardPlanAction`, as described above.
+`solr.InactiveShardPlanAction`, as described above.

solr/solr-ref-guide/src/using-zookeeper-to-manage-configuration-files.adoc

@@ -93,4 +93,4 @@ If you for example would like to keep your `solr.xml` in ZooKeeper to avoid havi
 bin/solr zk cp file:local/file/path/to/solr.xml zk:/solr.xml -z localhost:2181
 ----
 
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.