SOLR-11050: update asciidoc-syntax.adoc meta-docs for how to make links

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

@@ -19,6 +19,11 @@
 
 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
 
 === Bold
@@ -35,22 +40,22 @@ More info: http://asciidoctor.org/docs/user-manual/#bold-and-italic
 
 === Headings
 
-Equal signs (`=`) are used for heading levels. Each equal sign is a level. Each page can *only* have one top level. Levels should be appropriately nested.
+Equal signs (`=`) are used for heading levels. Each equal sign is a level. Each page can *only* have one top level (i.e., only one section with a single `=`).
 
-Validation occurs to ensure that level 3s are preceded by level 2s, level 4s are preceded by level 3s, etc. Including out-of-sequence heading levels (such as a level 3 then a level 5) will not fail the build, but will produce an error.
+Levels should be appropriately nested. During the build, validation occurs to ensure that level 3s are preceded by level 2s, level 4s are preceded by level 3s, etc. Including out-of-sequence heading levels (such as a level 3 then a level 5) will not fail the build, but will produce an error.
 
 More info: http://asciidoctor.org/docs/user-manual/#sections
 
 === Code Examples
 
-Use backticks ``` for text that should be monospaced, such as a code or class name in the body of a paragraph.
+Use backticks ``` for text that should be monospaced, such as code or a class name in the body of a paragraph.
 
 More info: http://asciidoctor.org/docs/user-manual/#mono
 
 Longer code examples can be separated from text with `source` blocks. These allow defining the syntax being used so the code is properly highlighted.
 
-[source]
 .Example Source Block
+[source]
 ----
 [source,xml]
 <field name="id" type="string" indexed="true" stored="true" required="true" multiValued="false" />
@@ -66,8 +71,8 @@ Titles can be added to most blocks (images, source blocks, tables, etc.) by simp
 
 [source]
 ----
-[source,xml]
 .Example ID field
+[source,xml]
 <field name="id" type="string" indexed="true" stored="true" required="true" multiValued="false" />
 ----
 
@@ -82,27 +87,118 @@ However, you can add a name to a link by adding the URI followed by square brack
 http://lucene.apache.org/solr[Solr Website]
 
 === Link to Other Pages/Sections of the Guide
-A warning up front, linking to other pages can be a little bit painful.
+A warning up front, linking to other pages can be a little bit painful. There are slightly different rules depending on the type of link you want to create, and where you are linking from.
 
-To link to an anchor (or heading) on the _same page_, you can simply use double angle brackets (`<< >>`) around the anchor/heading/section name. Note that any heading (aka section title) that starts with equal signs is automatically an anchor.
+The build process includes a validation for internal or inter-page links, so if you can build the docs locally, you can use that to verify you constructed your link properly (or pay attention to the Jenkins build after your commit).
 
-More info: http://asciidoctor.org/docs/user-manual/#internal-cross-references
-
-To link to another page or even a heading on _another page_, you use a similar syntax, but you must refer to the full filename and refer to the section title you want to link to by changing it to lower case and including hyphens between each word.
-
-For example, if I want to link from one page to the Schema API page's section "Modify the Schema", I need to create a link that looks like this:
-
-[source]
-For more information about modifying the schema with the API, see the section <<schema-api.adoc#modify-the-schema>>.
-
-You can add text to appear by adding it after the file name and section reference, as in:
+With all of the below examples, you can add text to display as the link title by adding a comma after the section reference followed by the display text, as in:
 
 [source]
 <<schema-api.adoc#modify-the-schema,Modify the Schema>>
 
+==== Link to a Section on the Same Page
+
+To link to an anchor (or section title) on the _same page_, you can simply use double angle brackets (`<< >>`) around the anchor/heading/section title you want to link to. Any section title (a heading that starts with equal signs) automatically becomes an anchor during conversion and is available for deep linking.
+
+Example::
+If I have a section on a page that looks like this (from `defining-fields.adoc`):
++
+[source]
+----
+== Field Properties
+
+Field definitions can have the following properties:
+----
++
+To link to this section from another part of the same `defining-fields.adoc` page, I simply need to put the section title in double angle brackets, as in:
++
+[source]
+See also the <<Field Properties>> section.
++
+The section title will be used as the display text; to customize that add a comma after the the section title, then the text you want used for display.
+
+More info: http://asciidoctor.org/docs/user-manual/#internal-cross-references
+
+==== Link to a Section with an Anchor ID
+When linking to any section (on the same page or another one), you must also be aware of any pre-defined anchors that may be in use (these will be in double brackets, like `[[ ]]`). When the page is converted, those will be the references your link needs to point to.
+
+Example::
+Take this example from `configsets-api.adoc`:
++
+[source]
+----
+[[configsets-create]]
+== Create a ConfigSet
+----
++
+To link to this section, there are two approaches depending on where you are linking from:
+
+* From the same page, simply use the anchor name: `\<<configsets-create>>`.
+* From another page, use the page name and the anchor name: `\<<configsets-api.adoc#configsets-create>>`.
+
+==== Link to Another Page
+To link to _another page_ or a section on another page, you must refer to the full filename and refer to the section you want to link to.
+
+Unfortunately, when you want to refer the reader to another page without deep-linking to a section, you cannot simply put the other file name in angle brackets and call it a day. This is due to the PDF conversion - once all the pages are combined into one big page for one big PDF, the lack of a specific reference causes inter-page links to fail.
+
+So, *you must always link to a specific section*. If all you want is a reference to the top of another page, you can use the `page-shortname` attribute found at the top of every page as your anchor reference.
+
+Example::
+The file `upgrading-solr.adoc` has a `page-shortname` at the top that looks like this:
++
+[source]
+----
+= Upgrading Solr
+:page-shortname: upgrading-solr
+:page-permalink: upgrading-solr.html
+----
++
+To construct a link to this page, we need to refer to the file name (`upgrading-solr.adoc`), then use the `page-shortname` as our anchor reference. As in:
++
+[source]
+For more information about upgrades, see <<upgrading-solr.adoc#upgrading-solr>>.
+
+TIP: As of July 2017, all pages have a `page-shortname` that is equivalent to the filename (without the `.adoc` part).
+
+==== Link to a Section on Another Page
+Linking to a section is the same conceptually as linking to the top of a page, you just need to take a little extra care to format the anchor ID in your link reference properly.
+
+When you link to a section on another page, you must make a simple conversion of the title into the format the section ID will be created during the conversion. These are the rules that transform the sections:
+--
+* All characters are lower-cased.
+** `Using security.json with Solr` becomes `using security.json with solr`
+* All non-alpha characters are removed, with the exception of hyphens (so all periods, commas, ampersands, parentheses, etc., are stripped).
+** `using security.json with solr` becomes `using security json with solr`
+* All whitespaces are replaced with hyphens.
+** `using security json with solr` becomes `using-security-json-with-solr`
+--
+Example::
+The file `schema-api.adoc` has a section "Modify the Schema" that looks like this:
++
+[source]
+----
+== Modify the Schema
+
+`POST /_collection_/schema`
+----
++
+To link from to this section from another page, you would create a link structured like this:
++
+--
+* the file name of the page with the section (`schema-api.adoc`),
+* then the hash symbol (`#`),
+* then the converted section title (`modify-the-schema`),
+* then a comma and any link title for display.
+--
++
+The link in context would look like this:
++
+[source]
+For more information, see the section <<schema-api.adoc#modify-the-schema,Modify the Schema>>.
+
 More info: http://asciidoctor.org/docs/user-manual/#inter-document-cross-references
 
-== Item Lists
+== Lists
 
 Asciidoc supports three types of lists:
 
@@ -115,11 +211,15 @@ Each type of list can be mixed with the other types. So, you could have an order
 === Unordered Lists
 Simple bulleted lists need each line to start with an asterisk (`*`). It should be the first character of the line, and be followed by a space.
 
+These lists also need to be separated from the
+
 More info: http://asciidoctor.org/docs/user-manual/#unordered-lists
 
 === Ordered Lists
 Numbered lists need each line to start with a period (`.`). It should be the first character of the line, and be followed by a space.
 
+This style is preferred over manually numbering your list.
+
 More info: http://asciidoctor.org/docs/user-manual/#ordered-lists
 
 === Labeled Lists
@@ -127,6 +227,10 @@ These are like question & answer lists or glossary definitions. Each line should
 
 Labeled lists can be nested by adding an additional colon (such as `:::`, etc.).
 
+If your content will span multiple paragraphs or include source blocks, etc., you will want to add a plus sign (`+`) to keep the sections together for your reader.
+
+TIP: We prefer this style of list for parameters because it allows more freedom in how you present the details for each parameter. For example, it supports ordered or unordered lists inside it automatically, and you can include multiple paragraphs and source blocks without trying to cram them into a smaller table cell.
+
 More info: http://asciidoctor.org/docs/user-manual/#labeled-list
 
 == Images
@@ -207,7 +311,9 @@ Many more examples of formatting:
 
 === More Options
 
-Tables can also be given footer rows, borders, and captions. CSV or DSV can be used instead of formatting the data in pipes.
+Tables can also be given footer rows, borders, and captions. You can  determine the width of columns, or the width of the table as a whole.
+
+CSV or DSV can also be used instead of formatting the data in pipes.
 
 More info: http://asciidoctor.org/docs/user-manual/#tables
 
@@ -227,13 +333,13 @@ You can add titles to admonitions by making it an admonition block. The structur
 
 [source]
 ----
-[NOTE]
 .Title of Note
+[NOTE]
 ====
 Text of note
 ====
 ----
 
-In this example, the type of admonition is included in square brackets (`[NOTE]`), and the title is prefixed with a period. Four equal signs give the start and end points of the note text (which can include new lines, lists, etc.).
+In this example, the type of admonition is included in square brackets (`[NOTE]`), and the title is prefixed with a period. Four equal signs give the start and end points of the note text (which can include new lines, lists, code examples, etc.).
 
 More info: http://asciidoctor.org/docs/user-manual/#admonition