SOLR-18494: Document one block style for commands in the Ref Guide

dev-docs/ref-guide/asciidoc-syntax.adoc

@@ -79,15 +79,38 @@ More info: https://docs.asciidoctor.org/asciidoc/latest/verbatim/source-blocks/
 
 === Source Block Syntax Highlighting
 
-The HTML output uses Rouge to add syntax highlighting to code examples.
+The HTML output uses https://highlightjs.org/[highlight.js] to add syntax highlighting to code examples.
 This is done by adding the language of the code block after the `source`, as shown in the above example source block (`xml` in that case).
 
-Rouge has a long selection of lexers available.
-You can see the full list at https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers.
-Use one of the valid short names to get syntax highlighting for that language.
+Only the languages in the highlight.js build of the Guide's UI bundle are highlighted.
+A block with any other language name is shown without highlighting, and the browser console logs a warning.
+Adding a language is a change to the UI bundle, not to the pages.
 
-Ideally, we will have an appropriate lexer to use for all source blocks, but that's not possible.
+Use `text` for output and for anything that needs no highlighting; `plain` and `nohighlight` behave the same.
 When in doubt, choose `text`, or leave it blank.
+Commands are the exception: see <<Command Blocks>>.
+
+=== Command Blocks
+
+Use the same block style for every `curl`, `bin/solr` or other shell command, so readers see one convention across the Guide:
+
+* A block with commands only uses `bash` and no prompt, so it can be copied as is.
+* A block that also shows the output of the commands uses `console`, with `$` at the start of each command line, so the commands stand out from the output.
+The copy button of the Guide copies only the `$` lines of such a block, so a command whose argument continues on the next lines without a trailing `\` (a multi-line JSON body) belongs in a `bash` block instead.
+* A block that shows output alone uses `text`.
+* The Windows variant of a command uses `powershell`, which the highlight.js build does not include yet, so it is shown without highlighting.
+
+.Example Command Blocks
+[source]
+----
+[source,bash]
+curl "http://localhost:8983/solr/films/select?q=*:*"
+
+[,console]
+$ bin/solr create -c films --shards 2 --replication-factor 2
+Creating new collection 'films' using command:
+http://localhost:7574/solr/admin/collections?action=CREATE&name=films&numShards=2&replicationFactor=2&collection.configName=films
+----
 
 === Importing Code Snippets from Other Files
 

solr/solr-ref-guide/modules/configuration-guide/pages/configsets-api.adoc

@@ -178,7 +178,7 @@ With the v1 API, the `upload` command must be capitalized as `UPLOAD`:
 
 [source,bash]
 ----
-$ (cd solr/server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) > myconfigset.zip
+(cd solr/server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) > myconfigset.zip
 
 curl "http://localhost:8983/solr/admin/configs?action=UPLOAD&name=myConfigSet" --header "Content-Type:application/octet-stream" --data-binary @myconfigset.zip
 ----
@@ -187,7 +187,7 @@ The same can be achieved using a Unix pipe with a single request as follows:
 
 [source,bash]
 ----
-$ (cd server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) | curl "http://localhost:8983/solr/admin/configs?action=UPLOAD&name=myConfigSet" --header "Content-Type:application/octet-stream" --data-binary @-
+(cd server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) | curl "http://localhost:8983/solr/admin/configs?action=UPLOAD&name=myConfigSet" --header "Content-Type:application/octet-stream" --data-binary @-
 ----
 ====
 
@@ -198,7 +198,7 @@ With the v2 API, the name of the configset to upload is provided as a path param
 
 [source,bash]
 ----
-$ (cd solr/server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) > myconfigset.zip
+(cd solr/server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) > myconfigset.zip
 
 curl -X PUT --header "Content-Type:application/octet-stream" --data-binary @myconfigset.zip
     "http://localhost:8983/api/configsets/myConfigSet"

solr/solr-ref-guide/modules/configuration-guide/pages/package-manager.adoc

@@ -46,7 +46,7 @@ To enable it, start all Solr nodes with the `-Dsolr.packages.enabled=true` param
 
 [source,bash]
 ----
-$ bin/solr start -Dsolr.packages.enabled=true
+bin/solr start -Dsolr.packages.enabled=true
 ----
 
 WARNING: There are security consequences to enabling the package manager.
@@ -62,7 +62,7 @@ In order to install packages into Solr, one has to add a repository hosting the
 
 [source,bash]
 ----
-$ bin/solr package add-repo <repository-name> <repository-url>
+bin/solr package add-repo <repository-name> <repository-url>
 ----
 
 NOTE: Do not add repositories that you don't trust or control.
@@ -74,21 +74,21 @@ To list installed packages:
 
 [source,bash]
 ----
-$ bin/solr package list-installed
+bin/solr package list-installed
 ----
 
 To list packages available for installation from added repositories:
 
 [source,bash]
 ----
-$ bin/solr package list-available
+bin/solr package list-available
 ----
 
 To install a package, coping over the artifacts from the repository into Solr's internal package store and setting up classloader for this package to be used:
 
 [source,bash]
 ----
-$ bin/solr package install <package-name>[:<version>]
+bin/solr package install <package-name>[:<version>]
 ----
 
 === Deploy a Package
@@ -102,21 +102,21 @@ There are two ways to do this: either use the CLI's `deploy` command or manually
 If the package author states support for it, the package can be deployed with the CLI's `deploy` command.
 [source,bash]
 ----
-$ bin/solr package deploy <package-name>:[version] --collections <collection1>[,<collection2>,...] [--param <param1>=<val1> --param <param2>=<val2> ...
+bin/solr package deploy <package-name>:[version] --collections <collection1>[,<collection2>,...] [--param <param1>=<val1> --param <param2>=<val2> ...
 ----
 
 or
 
 [source,bash]
 ----
-$ bin/solr package deploy <package-name>:[version] --cluster
+bin/solr package deploy <package-name>:[version] --cluster
 ----
 
 If the package accepts parameters for its setup commands, they can be specified (as per package documentation):
 
 [source,bash]
 ----
-$ bin/solr package deploy <snipped...> --param <param1>=<val1> --param <param2>=<val2>
+bin/solr package deploy <snipped...> --param <param1>=<val1> --param <param2>=<val2>
 ----
 
 The author may want you to confirm deployment of a package via a prompt.
@@ -151,7 +151,7 @@ After deploying, verify that the collection is using the package:
 
 [source,bash]
 ----
-$ bin/solr package list-deployed -c <collection>
+bin/solr package list-deployed -c <collection>
 ----
 
 === Updating Packages
@@ -162,20 +162,20 @@ Next, install the new version of the package from the repositories.
 
 [source,bash]
 ----
-$ bin/solr package install <package-name>:<version>
+bin/solr package install <package-name>:<version>
 ----
 
 Once you have installed the new version, you can selectively update each of your collections or the cluster level plugins.
 Assuming the old version is `1.0.0` of the package `mypackage`, and the new version is `2.0.0`, the command would be as follows:
 
 [source,bash]
 ----
-$ bin/solr package deploy mypackage:2.0.0 --update --collections mycollection
+bin/solr package deploy mypackage:2.0.0 --update --collections mycollection
 ----
 or
 [source,bash]
 ----
-$ bin/solr package deploy mypackage:2.0.0 --update --cluster
+bin/solr package deploy mypackage:2.0.0 --update --cluster
 ----
 
 You can run the `list-deployed` command to verify that this collection is using the newly added version.
@@ -186,7 +186,7 @@ If a package supports undeploying the plugins it contains (check package author'
 
 [source,bash]
 ----
-$ bin/solr package undeploy <package-name> --collections <collection1>[,<collection2>,...]
+bin/solr package undeploy <package-name> --collections <collection1>[,<collection2>,...]
 ----
 
 === Uninstall a Package
@@ -195,14 +195,14 @@ If a package has been undeployed or was never deployed, then it can be uninstall
 
 [source,bash]
 ----
-$ bin/solr package uninstall <package-name>:<package-version>
+bin/solr package uninstall <package-name>:<package-version>
 ----
 
 or
 
 [source,bash]
 ----
-$ bin/solr package deploy <package-name>:<package-version> --cluster
+bin/solr package deploy <package-name>:<package-version> --cluster
 ----
 
 Both package name and version are required.

solr/solr-ref-guide/modules/deployment-guide/pages/enabling-ssl.adoc

@@ -39,9 +39,9 @@ The `-ext SAN=...` `keytool` option allows you to specify all the DNS names and/
 
 In addition to `localhost` and `127.0.0.1`, this example includes a LAN IP address `192.168.1.3` for the machine the Solr nodes will be running on:
 
-[source,terminal]
+[source,bash]
 ----
-$ keytool -genkeypair -alias solr-ssl -keyalg RSA -keysize 2048 -keypass secret -storepass secret -validity 9999 -keystore solr-ssl.keystore.p12 -storetype PKCS12 -ext SAN=DNS:localhost,IP:192.168.1.3,IP:127.0.0.1 -dname "CN=localhost, OU=Organizational Unit, O=Organization, L=Location, ST=State, C=Country"
+keytool -genkeypair -alias solr-ssl -keyalg RSA -keysize 2048 -keypass secret -storepass secret -validity 9999 -keystore solr-ssl.keystore.p12 -storetype PKCS12 -ext SAN=DNS:localhost,IP:192.168.1.3,IP:127.0.0.1 -dname "CN=localhost, OU=Organizational Unit, O=Organization, L=Location, ST=State, C=Country"
 ----
 
 The above command will create a keystore file named `solr-ssl.keystore.p12` in the current directory.
@@ -50,16 +50,16 @@ The above command will create a keystore file named `solr-ssl.keystore.p12` in t
 
 Convert the PKCS12 format keystore, including both the certificate and the key, into PEM format using the http://www.openssl.org[`openssl`] command:
 
-[source,terminal]
+[source,bash]
 ----
-$ openssl pkcs12 -in solr-ssl.keystore.p12 -out solr-ssl.pem
+openssl pkcs12 -in solr-ssl.keystore.p12 -out solr-ssl.pem
 ----
 
 If you want to use curl on OS X Yosemite (10.10), you'll need to create a certificate-only version of the PEM format, as follows:
 
-[source,terminal]
+[source,bash]
 ----
-$ openssl pkcs12 -nokeys -in solr-ssl.keystore.p12 -out solr-ssl.cacert.pem
+openssl pkcs12 -nokeys -in solr-ssl.keystore.p12 -out solr-ssl.cacert.pem
 ----
 
 === Set Common SSL-Related Environment Variables
@@ -148,9 +148,9 @@ If you created the SSL key without all DNS names or IP addresses on which Solr n
 *nix::
 +
 ====
-[source,terminal]
+[source,bash]
 ----
-$ bin/solr start --solr-home cloud/node1 -z server1:2181,server2:2181,server3:2181 -p 8984
+bin/solr start --solr-home cloud/node1 -z server1:2181,server2:2181,server3:2181 -p 8984
 ----
 ====
 
@@ -159,7 +159,7 @@ Windows::
 ====
 [source,powershell]
 ----
-C:\> bin\solr.cmd --solr-home cloud\node1 -z server1:2181,server2:2181,server3:2181
+bin\solr.cmd --solr-home cloud\node1 -z server1:2181,server2:2181,server3:2181
 
 ----
 ====
@@ -175,9 +175,9 @@ Customize the values for the parameters shown as needed and add any used in your
 *nix::
 +
 ====
-[source,terminal]
+[source,bash]
 ----
-$ bin/solr start -p 8984
+bin/solr start -p 8984
 ----
 ====
 
@@ -186,7 +186,7 @@ Windows::
 ====
 [source,powershell]
 ----
-C:\> bin\solr.cmd -p 8984
+bin\solr.cmd -p 8984
 ----
 ====
 ======
@@ -244,7 +244,7 @@ bin/solr create -c mycollection --shards 2
 Windows::
 +
 ====
-[source,text]
+[source,powershell]
 ----
 bin\solr.cmd create -c mycollection --shards 2
 ----
@@ -257,7 +257,7 @@ The `create` action will pass the `SOLR_SSL_*` properties set in your include fi
 
 To get the resulting cluster status (again, if you have not enabled client authentication, remove the `-E solr-ssl.pem:secret` option):
 
-[source,terminal]
+[source,bash]
 ----
 curl -E solr-ssl.pem:secret --cacert solr-ssl.pem "https://localhost:8984/solr/admin/collections?action=CLUSTERSTATUS&indent=on"
 ----
@@ -301,17 +301,17 @@ You should get a response that looks like this:
 
 Use `bin/solr post` to index some example documents to the SolrCloud collection created above:
 
-[source,console]
+[source,bash]
 ----
-$ bin/solr post --solr-url https://localhost:8984 --name mycollection example/exampledocs/*.xml
+bin/solr post --solr-url https://localhost:8984 --name mycollection example/exampledocs/*.xml
 ----
 
 === Query Using curl
 
 Use curl to query the SolrCloud collection created above, from a directory containing the PEM formatted certificate and key created above (e.g., `example/etc/`).
 If you have not enabled client authentication (system property `-Djetty.ssl.clientAuth=true)`, then you can remove the `-E solr-ssl.pem:secret` option:
 
-[source,console]
+[source,bash]
 ----
 curl -E solr-ssl.pem:secret --cacert solr-ssl.pem "https://localhost:8984/solr/mycollection/select?q=*:*"
 ----

solr/solr-ref-guide/modules/deployment-guide/pages/installing-solr.adoc

@@ -171,7 +171,7 @@ bin/solr start
 
 If you are running Windows, you can start Solr by running `bin\solr.cmd` instead.
 
-[source,plain]
+[source,powershell]
 ----
 bin\solr.cmd start
 ----

solr/solr-ref-guide/modules/deployment-guide/pages/node-roles.adoc

@@ -107,7 +107,7 @@ Dedicated *`coordinator`* nodes can be provisioned with enough memory but very l
 Fetches the list of supported roles and their supported modes for this cluster.
 
 *Input*
-[source,text]
+[source,bash]
 ----
 curl http://localhost:8983/api/cluster/node-roles/supported
 ----
@@ -135,7 +135,7 @@ curl http://localhost:8983/api/cluster/node-roles/supported
 Fetches the current node roles assignment for all the nodes in the cluster.
 
 *Input*
-[source,text]
+[source,bash]
 ----
 curl http://localhost:8983/api/cluster/node-roles
 ----
@@ -206,7 +206,7 @@ http://localhost:8983/api/cluster/node-roles/role/data/off
 Fetches the current node roles assignment for the specified node.
 
 *Input*
-[source,text]
+[source,bash]
 ----
 curl http://localhost:8983/api/cluster/node-roles/node/solr1:8983_solr
 ----