[lucene-solr] branch branch_8_6 updated: Found that asciidoctor 1.5.6.2 cause build-site to fail on long anchors (#1700) (#1704)

[gu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

gus pushed a commit to branch branch_8_6
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git


The following commit(s) were added to refs/heads/branch_8_6 by this push:
     new 7bc6726  Found that asciidoctor 1.5.6.2 cause build-site to fail on long anchors (#1700) (#1704)
7bc6726 is described below

commit 7bc6726c69220eca22e7d2b49e7b62cc50811969
Author: Gus Heck <46...@users.noreply.github.com>
AuthorDate: Wed Jul 29 20:17:52 2020 -0400

    Found that asciidoctor 1.5.6.2 cause build-site to fail on long anchors (#1700) (#1704)
    
    * Found that asciidoctor 1.5.6.2 cause build-site to fail on long anchors, 2.0.10 definitely works.
    * Clarity on when an upgrade is required, also fix obsolete wording from when PDFs were generated.
---
 solr/solr-ref-guide/README.adoc | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/solr/solr-ref-guide/README.adoc b/solr/solr-ref-guide/README.adoc
index b8112c1..84b130e 100644
--- a/solr/solr-ref-guide/README.adoc
+++ b/solr/solr-ref-guide/README.adoc
@@ -21,9 +21,9 @@ This is the source for the Solr Reference Guide.
 Raw content is stored in Asciidoc (`.adoc`) formatted files in the `src/` directory.
 
 == Prerequisites for Building
-These files are processed with AsciiDoctor in 2 different ways:
+These files are processed with AsciiDoctor.
 
-* HTML version, using Jekyll:
+* HTML is generated using Jekyll with these key dependencies:
 ** `Ruby` (v2.3 or higher)
 ** The following gems must be installed:
 *** `jekyll`: v3.5, not v4.x.
@@ -37,6 +37,11 @@ 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.
 
+NOTE: The above should install the correct version of the asciidoctor gem implicitly on a new system, but will not upgrade an existing version.
+If you experience problems building that seem unrelated to your changes, check that asciidoctor is at least v2.0.10 or higher.
+This is usually only a problem if you have previously built the ref guide prior to October 2019 or used asciidoctor for some other reason.
+`gem info asciidoctor` will show you what version(s) you have installed.
+
 
 == Building the Guide
 For details on building the ref guide, see `ant -p`.