SOLR-10301: Publish How to Contribute to the Ref Guide with the HTML version

solr/solr-ref-guide/src/how-to-contribute.adoc

@@ -0,0 +1,33 @@
+= How to Contribute to Solr Documentation
+:page-tocclass: right
+:page-toclevels: 2
+:page-shortname: how-to-contribute
+:page-permalink: how-to-contribute.html
+
+The Lucene/Solr project has made it easy for anyone to contribute to the Solr Reference Guide with a patch.
+
+The Guide is written in simple AsciiDoc-formatted files, and the source lives in the main Lucene/Solr source repository, right alongside the code.
+
+ifdef::backend-pdf[]
+See the latest information on how to contribute to documentation online at https://lucene.apache.org/solr/guide/meta-docs.html.
+endif::[]
+
+ifdef::backend-html5[]
+The following sections give an overview of how to work with AsciiDoc-format files, how our documentation is generated, and how to do a Ref Guide release.
+
+Once you have a patch you'd like to contribute, you can submit it with a JIRA issue, the same as any other patch. See also the Solr wiki section on https://wiki.apache.org/solr/HowToContribute[How To Contribute] for information on submitting patches.
+
+== Working with AsciiDoc Files
+include::meta-docs/asciidoc-syntax.adoc[leveloffset=+2]
+
+include::meta-docs/editing-tools.adoc[leveloffset=+2]
+
+== Modifying the Output Formats
+The Solr Reference Guide is published in two formats, HTML and PDF. Different tools are used for each.
+include::meta-docs/jekyll.adoc[leveloffset=+2]
+
+include::meta-docs/pdf.adoc[leveloffset=+2]
+
+== Building & Publishing the Guide
+include::meta-docs/publish.adoc[leveloffset=+2]
+endif::[]

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

@@ -1,7 +1,7 @@
 = Apache Solr Reference Guide
 :page-shortname: index
 :page-permalink: index.html
-:page-children: about-this-guide, getting-started, upgrading-solr, using-the-solr-administration-user-interface, documents-fields-and-schema-design, understanding-analyzers-tokenizers-and-filters, indexing-and-basic-data-operations, searching, the-well-configured-solr-instance, managing-solr, solrcloud, legacy-scaling-and-distribution, client-apis, major-changes-from-solr-5-to-solr-6, upgrading-a-solr-cluster, further-assistance, solr-glossary, errata
+:page-children: about-this-guide, getting-started, upgrading-solr, using-the-solr-administration-user-interface, documents-fields-and-schema-design, understanding-analyzers-tokenizers-and-filters, indexing-and-basic-data-operations, searching, the-well-configured-solr-instance, managing-solr, solrcloud, legacy-scaling-and-distribution, client-apis, major-changes-from-solr-5-to-solr-6, upgrading-a-solr-cluster, further-assistance, solr-glossary, errata, how-to-contribute
 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information

solr/solr-ref-guide/src/meta-docs/asciidoc-syntax.adoc

@@ -1,4 +1,4 @@
-= Asciidoc syntax
+= AsciiDoc Syntax Cheatsheet
 :toc:
 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
@@ -17,14 +17,14 @@
 // specific language governing permissions and limitations
 // under the License.
 
-The definitive manual on Asciidoc syntax is in the http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]. To help people get started, however, here is a simpler cheat sheet.
+The definitive manual on AsciiDoc syntax is in the http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]. To help people get started, however, here is a simpler cheat sheet.
 
 == AsciiDoc vs Asciidoctor Syntax
 We use tools from the Asciidoctor project to build the HTML and PDF versions of the Ref Guide. Asciidoctor is a Ruby port of the original AsciiDoc project, which was mostly abandoned several years ago.
 
 While much of the syntax between the two is the same, there are many conventions supported by Asciidoctor that did not exist in AsciiDoc. While the Asciidoctor project has tried to provide back-compatibility with the older project, that may not be true forever. For this reason, it's strongly recommended to only use the Asciidoctor User Manual as a reference for any syntax that's not described here.
 
-== Basic syntax
+== Basic AsciiDoc Syntax
 
 === Bold
 
@@ -200,7 +200,7 @@ More info: http://asciidoctor.org/docs/user-manual/#inter-document-cross-referen
 
 == Lists
 
-Asciidoc supports three types of lists:
+AsciiDoc supports three types of lists:
 
 * Unordered lists
 * Ordered lists
@@ -319,7 +319,7 @@ More info: http://asciidoctor.org/docs/user-manual/#tables
 
 == Admonitions (Notes, Warnings)
 
-Asciidoc supports several types of callout boxes, called "admonitions":
+AsciiDoc supports several types of callout boxes, called "admonitions":
 
 * NOTE
 * TIP

solr/solr-ref-guide/src/meta-docs/editing-tools.adoc

@@ -1,4 +1,4 @@
-= Tools for Working with Asciidoc Format
+= Tools for Working with AsciiDoc Files
 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information
@@ -16,15 +16,15 @@
 // specific language governing permissions and limitations
 // under the License.
 
-== Asciidoc vs Asciidoctor
+== AsciiDoc vs Asciidoctor
 
-The Solr Ref Guide is written in _Asciidoc_ format. This format is generally considered an extension of Markdown, because it has support for tables of contents, better table support, and other features that make it more appropriate for writing technical documentation.
+The Solr Ref Guide is written in _AsciiDoc_ format. This format is generally considered an extension of Markdown, because it has support for tables of contents, better table support, and other features that make it more appropriate for writing technical documentation.
 
-We are using a version of the Asciidoc syntax along with tools from an open source project called https://asciidoctor.org[Asciidoctor]. This provides full support for the Asciidoc syntax, but replaces the original Python processor with one written in Ruby. There is a Java implementation, known as https://github.com/asciidoctor/asciidoctorj[AsciidoctorJ]. Further extensions from the original Asciidoc project include support for font-based icons and UI elements.
+We are using a version of the AsciiDoc syntax along with tools from an open source project called https://asciidoctor.org[Asciidoctor]. This provides full support for the AsciiDoc syntax, but replaces the original Python processor with one written in Ruby. There is a Java implementation, known as https://github.com/asciidoctor/asciidoctorj[AsciidoctorJ]. Further extensions from the original AsciiDoc project include support for font-based icons and UI elements.
 
 == Helpful Tools
 
-You can write Asciidoc without any special tools. It's simply text, with familiar syntax for bold (`*`) and italics (`_`).
+You can write AsciiDoc without any special tools. It's simply text, with familiar syntax for bold (`*`) and italics (`_`).
 
 Having some tools in your editor is helpful, though.
 
@@ -34,6 +34,6 @@ This allows you to see your document in something close to what it might appear
 
 The following information is from http://asciidoctor.org/docs/editing-asciidoc-with-live-preview.
 
-* Atom has AsciiDoc Preview, which gives you a panel that updates as you type. There are also a couple of other plugins to support Asciidoc format and auto-complete.
-* There is a Live Preview browser plugin for Chrome, Firefox and Opera which allow you to open your Asciidoc page in the browser. It will also update as you type.
-* There is also an Intellij IDEA plugin to support Asciidoc format.
+* Atom has AsciiDoc Preview, which gives you a panel that updates as you type. There are also a couple of other plugins to support AsciiDoc format and auto-complete.
+* There is a Live Preview browser plugin for Chrome, Firefox and Opera which allow you to open your AsciiDoc page in the browser. It will also update as you type.
+* There is also an Intellij IDEA plugin to support AsciiDoc format.

solr/solr-ref-guide/src/meta-docs/jekyll.adoc

@@ -1,4 +1,4 @@
-= Working with Jekyll
+= Making Changes to HTML Version
 :toc:
 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file

solr/solr-ref-guide/src/meta-docs/pdf.adoc

@@ -1,4 +1,4 @@
-= Generating PDF
+= Making Changes to the PDF Version
 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information
@@ -111,7 +111,7 @@ There are a lot of options here. Note that some include the `<attribute>` tag an
 === Asciidoctor Ant Attributes
 
 `sourceDirectory="${build.content.dir}/pdf"`:: Defines where to find the source file to build the PDF. The variable is declared earlier in `build.xml`.
-`sourceDocumentName="SolrRefGuide-all.adoc"`:: The source file name, which in our case will be built as described in the section <<Creating the Uber-Document>>.
+`sourceDocumentName="SolrRefGuide-all.adoc"`:: The source file name, which in our case will be built as described in the section <<About the Uber-Document>>.
 `baseDir="${build.content.dir}"`:: The root path for any included files.
 `outputDirectory="${build.dir}"`:: Defines where the resulting PDF file should go. In this case, the
 `backend="pdf"`:: The output format. The `asciidoctor-ant` jar is also capable of outputting DocBook format, so we must declare we want a PDF.

solr/solr-ref-guide/src/meta-docs/publish.adoc

@@ -30,6 +30,12 @@ It's strongly preferred that both PDF and HTML versions are available during the
 == Publishing PDF Version
 The PDF version of the Solr Reference Guide is the *official* version. As such, it is voted on by the community before release, and is treated as an official artifact of the Lucene/Solr project.
 
+=== Prerequisites
+
+* You have checked out the Lucene/Solr source code on the machine you will be doing the release from. You will need scripts in the `dev-tools` directory.
+* You have generated a GPG key. See the Apache documentation on https://www.apache.org/dev/release-signing.html#generate[generating a code signing key].
+* You have Python 3 installed. This is needed to poll the mirrors after release to be sure it's propagated enough to make the announcement.
+
 === Generate the PDF
 
 No local dependencies are required to build the PDF. The Ant target will download the jars and other items it requires.
@@ -41,16 +47,7 @@ To build the PDF:
 . Run `ant build-pdf -Dsolr-guide-version=X.Y`
 . The resulting PDF will be in `solr/build/solr-ref-guide`.
 
-Important::
-+
-The `-Dsolr-guide-version` system property is optional.  By default the build system uses the `version.properties` of the current branch and assumes this is a `DRAFT` build.
-+
-
-=== Prerequisites
-
-* You have checked out the Lucene/Solr source code on the machine you will be doing the release from. You will need scripts in the `dev-tools` directory.
-* You have generated a GPG key. See the Apache documentation on https://www.apache.org/dev/release-signing.html#generate[generating a code signing key].
-* You have Python 3 installed. This is needed to poll the mirrors after release to be sure it's propagated enough to make the announcement.
+IMPORTANT: The `-Dsolr-guide-version` system property is optional.  By default the build system uses the `version.properties` of the current branch and assumes this is a `DRAFT` build.
 
 === Prepare and Upload Release Candidate