Doc release clean up (#1050)

* fix upstream branding and tidy up xref attributes

* restructure and tidy up schema look up strategies

* minor tidy up

docs/modules/ROOT/pages/getting-started/assembly-registry-reference.adoc

@@ -1,7 +1,7 @@
 // Metadata created by nebel
 include::{mod-loc}shared/all-attributes.adoc[]
 
-[id="artifact-and-rule-types"]
+[id="registry-artifact-reference"]
 = {registry} artifact reference
 //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
 

docs/modules/ROOT/partials/getting-started/con-registry-serdes-strategy.adoc

@@ -4,76 +4,75 @@
 [id='registry-serdes-concepts-strategy-{context}']
 = Strategies to look up a schema
 
-The Kafka client serializer uses two lookup _strategies_ to determine the artifact ID and global ID under which the message schema is registered in {registry}.
+The Kafka client serializer uses _lookup strategies_ to determine the artifact ID and the global ID under which the message schema is registered in {registry}.
 
 For a given topic and message, you can use implementations of the following Java interfaces:
 
 * `ArtifactIdStrategy` to return an artifact ID
 * `GlobalIdStrategy` to return a global ID
 
+The classes for each strategy are organized in the `io.apicurio.registry.utils.serde.strategy` package. The default strategy is the artifact ID `TopicIdStrategy`, which looks for {registry} artifacts with the same name as the Kafka topic receiving messages.
+
+.Example
+[source,java,subs="+quotes,attributes"]
+----
+public String artifactId(String topic, boolean isKey, T schema) {
+    return String.format("%s-%s", topic, isKey ? "key" : "value");
+}
+----
+
+* The `topic` parameter is the name of the Kafka topic receiving the message.
+* The `isKey` parameter is `true` when the message key is being serialized, and `false` when the message value is being serialized.
+* The `schema` parameter is the schema of the message being serialized or deserialized.
+* The `artifactID` returned is the artifact ID under which the schema is registered in {registry}.
+
+Which lookup strategy you use depends on how and where you store your schema. For example, you might use a strategy that uses a _record ID_ if you have different Kafka topics with the same Avro message type.
+
 [discrete]
 == Artifact ID strategy
 
-The artifact ID strategy provides a way to map the Kafka topic and message information to the ID of an artifact in {registry}. The common convention for the mapping is to combine the Kafka topic name with either `key` or `value`, depending on whether the serializer is being used for the Kafka message key or value).
+The artifact ID strategy provides a way to map the Kafka topic and message information to an artifact ID in {registry}. The common convention for the mapping is to combine the Kafka topic name with the `key` or `value`, depending on whether the serializer is used for the Kafka message key or value.
 
-However, you can use alternative conventions for the mapping, either by using an alternative strategy provided by {registry} or by creating a custom Java class that implements `io.apicurio.registry.utils.serde.strategy.ArtifactIdStrategy`.
+However, you can use alternative conventions for the mapping by using a strategy provided by {registry}, or by creating a custom Java class that implements `io.apicurio.registry.utils.serde.strategy.ArtifactIdStrategy`.
 
 [discrete]
 [id='service-registry-concepts-artifactid-{context}']
 == Strategies to return an artifact ID
 
-Strategies to return an artifact ID based on an implementation of `ArtifactIdStrategy`:
+{registry} provides the following strategies to return an artifact ID based on an implementation of `ArtifactIdStrategy`:
 
 `RecordIdStrategy`:: Avro-specific strategy that uses the full name of the schema.
 `TopicRecordIdStrategy`:: Avro-specific strategy that uses the topic name and the full name of the schema.
-`TopicIdStrategy`:: (Default) strategy that uses the topic name and `key` or `value` suffix.
+`TopicIdStrategy`:: Default strategy that uses the topic name and `key` or `value` suffix.
 `SimpleTopicIdStrategy`:: Simple strategy that only uses the topic name.
 
 
 [discrete]
 == Global ID strategy
 
-The global ID strategy locates and identifies the specific version of the schema registered under the artifact ID provided by the artifact ID strategy. Every version of every artifact has a single globally unique identifier that can be used to retrieve the content of that artifact. That global ID is what gets included in every Kafka message so that a deserializer can properly fetch the schema from {registry}.  
+The global ID strategy locates and identifies the specific version of the schema registered under the artifact ID provided by the artifact ID strategy. Every version of every artifact has a single globally unique identifier that can be used to retrieve the content of that artifact. This global ID is included in every Kafka message so that a deserializer can properly fetch the schema from {registry}.  
 
-The global ID strategy can either lookup an existing artifact version, or it can register one if not found, depending on which strategy is used.  Additionally, you can provide your own strategy by creating a
+The global ID strategy can look up an existing artifact version, or it can register one if not found, depending on which strategy is used. You can also provide your own strategy by creating a
 custom Java class that implements `io.apicurio.registry.utils.serde.strategy.GlobalIdStrategy`.
 
-The classes for each strategy are organized in the `io.apicurio.registry.utils.serde.strategy` package. The default artifact ID strategy is `TopicIdStrategy`, which looks for {registry} artifacts with the same name as the Kafka topic receiving messages.
-
-.Example
-[source,java,subs="+quotes,attributes"]
-----
-public String artifactId(String topic, boolean isKey, T schema) {
-    return String.format("%s-%s", topic, isKey ? "key" : "value");
-}
-----
-
-* The `topic` parameter is the name of the Kafka topic receiving the message.
-* The `isKey` parameter is _true_ when the message key is being serialized, and _false_ when the message value is being serialized.
-* The `schema` parameter is the schema of the message being serialized/deserialized.
-* The `artifactID` returned is the artifact ID under which the schema is registered in {registry}.
-
-What lookup strategy you use depends on how and where you store your schema.
-For example, you might use a strategy that uses a _record ID_ if you have different Kafka topics with the same Avro message type.
-
 [discrete]
 [id='service-registry-concepts-globalid-{context}']
 == Strategies to return a global ID
 
-Strategies to return a global ID based on an implementation of `GlobalIdStrategy`:
+{registry} provides the following strategies to return a global ID based on an implementation of `GlobalIdStrategy`:
 
 `FindLatestIdStrategy`:: Strategy that returns the global ID of the latest schema version, based on an artifact ID.
 `FindBySchemaIdStrategy`:: Strategy that matches schema content, based on an artifact ID, to return a global ID.
 `CachedSchemaIdStrategy`:: Strategy that caches the schema, and uses the global ID of the cached schema.
-`GetOrCreateIdStrategy`:: Strategy that tries to get the latest schema, based on an artifact ID, and if it does not exist, it creates a new schema.
+`GetOrCreateIdStrategy`:: Strategy that tries to get the latest schema, based on an artifact ID, and if it does not exist, creates a new schema.
 `AutoRegisterIdStrategy`:: Strategy that updates the schema, and uses the global ID of the updated schema.
 
 [discrete]
 [id='configuring-globalid-strategy-{context}']
-== Configuring global ID strategy
-You can configure the following application property:
+== Configuring the global ID strategy
+You can configure the following application property for the global ID strategy:
 
-* apicurio.registry.check-period-ms -- set remote lookup period in milliseconds
+* `apicurio.registry.check-period-ms`: Configures the remote schema lookup period in milliseconds
 
 You can configure application properties as Java system properties or include them in the Quarkus
-application.properties file. For more details, see the https://quarkus.io/guides/config#overriding-properties-at-runtime[Quarkus documentation].
+application.properties file. For more details, see the https://quarkus.io/guides/config#overriding-properties-at-runtime[Quarkus documentation].

docs/modules/ROOT/partials/getting-started/proc-adding-artifacts-using-console.adoc

@@ -4,7 +4,7 @@
 [id="adding-artifacts-using-console"]
 = Adding artifacts using the {registry} web console
 
-You can use the {registry} web console to upload event schema and API design artifacts to the registry. For more details on the artifact types that you can upload, see {registry-artifact-types}. This section shows simple examples of uploading {registry} artifacts, applying artifact rules, and adding new artifact versions.
+You can use the {registry} web console to upload event schema and API design artifacts to the registry. For more details on the artifact types that you can upload, see {registry-reference}. This section shows simple examples of uploading {registry} artifacts, applying artifact rules, and adding new artifact versions.
 
 .Prerequisites
 
@@ -32,7 +32,7 @@ image::images/getting-started/registry-web-console-artifact.png[Artifact Details
 ** *Documentation* (OpenAPI only): Displays automatically-generated REST API documentation.
 ** *Content*: Displays a read-only view of the full artifact content.
 
-. In *Content Rules*, click *Enable* to configure a *Validity Rule* or *Compatibility Rule*, and select the appropriate rule configuration from the drop-down. For more details, see {registry-rule-types}.
+. In *Content Rules*, click *Enable* to configure a *Validity Rule* or *Compatibility Rule*, and select the appropriate rule configuration from the drop-down. For more details, see {registry-reference}.
 
 . Click *Upload new version* to add a new artifact version, and drag and drop or click *Browse* to upload the file, for example, `my-schema.json` or `my-openapi.json`.
 

docs/modules/ROOT/partials/getting-started/proc-browsing-artifacts-using-console.adoc

@@ -4,7 +4,7 @@
 [id="browsing-artifacts-using-console"]
 = Viewing artifacts using the {registry} web console
 
-You can use the {registry} web console to browse the event schema and API design artifacts stored in the registry. This section shows simple examples of viewing {registry} artifacts, versions, and artifact rules. For more details on the artifact types stored in the registry, see {registry-artifact-types}. 
+You can use the {registry} web console to browse the event schema and API design artifacts stored in the registry. This section shows simple examples of viewing {registry} artifacts, versions, and artifact rules. For more details on the artifact types stored in the registry, see {registry-reference}. 
 
 .Prerequisites
 

docs/modules/ROOT/partials/getting-started/proc-configuring-rules-using-console.adoc

@@ -6,7 +6,7 @@
 
 You can use the {registry} web console to configure optional rules to prevent invalid content from being added to the registry. All configured artifact rules or global rules must pass before a new artifact version can be uploaded to the registry. Configured artifact rules override any configured global rules. For more details, see {registry-rules}.
 
-This section shows a simple example of configuring global and artifact rules. For details on the different rule types and associated configuration settings that you can select, see {registry-rule-types}.  
+This section shows a simple example of configuring global and artifact rules. For details on the different rule types and associated configuration settings that you can select, see {registry-reference}.  
 
 .Prerequisites
 
@@ -23,12 +23,12 @@ This section shows a simple example of configuring global and artifact rules. Fo
 
 . Click *View artifact* to view the *Artifact Details*.
 
-. In *Content Rules*, click *Enable* to configure an artifact *Validity Rule* or *Compatibility Rule*, and select the appropriate rule configuration from the drop-down. For more details, see {registry-rule-types}.
+. In *Content Rules*, click *Enable* to configure an artifact *Validity Rule* or *Compatibility Rule*, and select the appropriate rule configuration from the drop-down. For more details, see {registry-reference}.
 +
 .Configure content rules in {registry} web console
 image::images/getting-started/registry-web-console-rules.png[Configure rules in Registry web console]
 +
-. For global rules, click the *Settings* cog icon at the top right of the toolbar, and click *Enable* to configure a global *Validity Rule* or *Compatibility Rule*, and select the appropriate rule configuration from the drop-down. For more details, see {registry-rule-types}.
+. For global rules, click the *Settings* cog icon at the top right of the toolbar, and click *Enable* to configure a global *Validity Rule* or *Compatibility Rule*, and select the appropriate rule configuration from the drop-down. For more details, see {registry-reference}.
 
 . To disable an artifact rule or global rule, click the trash icon next to the rule. 
 

docs/modules/ROOT/partials/getting-started/proc-setting-up-infinispan-storage.adoc

@@ -10,7 +10,7 @@ This section explains how to configure Infinispan cache-based storage for {regis
 
 .Prerequisites
 * You must have an OpenShift cluster with cluster administrator access.
-* You must have already installed {registry}. See xref:installing-registry-operatorhub[].
+* You must have already installed {registry}. See {installing-the-registry-openshift}.
 
 
 .Procedure

docs/modules/ROOT/partials/getting-started/proc-setting-up-kafka-streams-storage.adoc

@@ -9,7 +9,7 @@ This section explains how to configure Kafka-based storage for {registry} using
 
 .Prerequisites
 * You must have an OpenShift cluster with cluster administrator access.
-* You must have already installed {registry}. See xref:installing-registry-operatorhub[].
+* You must have already installed {registry}. See {installing-the-registry-openshift}.
 * You must have already installed {kafka-streams}. See xref:installing-kafka-streams-operatorhub[].
 
 .Procedure

docs/modules/ROOT/partials/getting-started/proc-setting-up-postgresql-storage.adoc

@@ -10,7 +10,7 @@ This section explains how to configure Java Persistence API-based storage for {r
 
 .Prerequisites
 * You must have an OpenShift cluster with cluster administrator access.
-* You must have already installed {registry}. See xref:installing-registry-operatorhub[].
+* You must have already installed {registry}. See {installing-the-registry-openshift}.
 * You must have already installed a PostgreSQL Operator on OpenShift. For example, see xref:installing-postgresql-operatorhub[].
 
 .Procedure

docs/modules/ROOT/partials/getting-started/ref-registry-artifact-metadata.adoc

@@ -55,4 +55,4 @@ a| true
 * You can edit the `state` property only by using the state transition API. For example, you can mark an artifact as `deprecated` or `disabled`.  
 
 .Additional resources
-For more details, see the `/artifacts/{artifactId}/meta` sections in the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation].
+For more details, see the `/artifacts/\{artifactId\}/meta` sections in the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation].

docs/modules/ROOT/partials/shared/attributes.adoc

@@ -8,35 +8,42 @@
 
 // Branding - toggle upstream/downstream content "on/off"
 
-// The following attributes conditionalize content from the Apicurio upstream project:
+// The following attributes conditionalize content from the Apicurio Registry project:
 // * Upstream-only content tagged with ifdef::apicurio-registry[]...endif::[]
-// * Downstream-only content agged with ifdef::rh-service-registry[]...endif::[]
+// * Downstream-only content tagged with ifdef::rh-service-registry[]...endif::[]
 // Untagged content is common
 
+// Upstream condition by default, switch on/off downstream-only
+//:service-registry-downstream:
+
 // upstream
-//:apicurio-registry:
-//:registry: Apicurio Registry
-//:kafka-streams: Strimzi
-//:registry-version: 1.3
+ifndef::service-registry-downstream[]
+:apicurio-registry:
+:registry: Apicurio Registry
+:kafka-streams: Strimzi
+:registry-version: 1.3
+endif::[]
 
 // downstream
+ifdef::service-registry-downstream[]
 :rh-service-registry:
 :registry: Service Registry
 :kafka-streams: AMQ Streams
 :registry-version: 1.1
-:registry-ocp-version: 4.5
+endif::[]
+
+//common
 :version: 2020-Q4
 :attachmentsdir: files
+:registry-ocp-version: 4.5
+:context: registry
+
 
 //integration products
 :fuse-version: 7.7
 :amq-version: 7.7
 :3scale-version: 2.9
 
-//common
-:registry-ocp-version: 4.5
-:context: registry
-
 // Characters
 :copy: ©
 :infin: ∞
@@ -57,11 +64,9 @@ include::attributes-links.adoc[]
 // internal links
 :registry-overview: xref:intro-to-the-registry[]
 :registry-rules: xref:intro-to-registry-rules[] 
-:registry-artifact-types: xref:artifact-and-rule-types[]
-:registry-rule-types: xref:artifact-and-rule-types[]
+:registry-reference: xref:registry-artifact-reference[]
 :managing-registry-artifacts-ui: xref:managing-registry-artifacts-ui[]
 :installing-the-registry-openshift: xref:installing-registry-ocp[]
 :installing-the-registry-storage-openshift: xref:installing-registry-streams-storage[]
-:registry-reference: xref:artifact-and-rule-types[]
 :managing-registry-artifacts-api: xref:managing-registry-artifacts-api[]
 :kafka-client-serdes: xref:using-kafka-client-serdes[]