Merge pull request #1 from apinnick/troubleshooting

Add troubleshooting section

Author: mmuehlfeldRH

Diff for: docs/assembly_troubleshooting.adoc

@@ -0,0 +1,12 @@
+:_content-type: ASSEMBLY
+
+[id="troubleshooting"]
+= Troubleshooting
+
+:context: troubleshooting
+
+You might run into the following problems if you organize your chapters into subsections.
+
+include::modules/proc_ticket-missing-in-subsection.adoc[leveloffset=+1]
+
+include::modules/proc_chapter-missing-in-build.adoc[leveloffset=+1]

Diff for: docs/main.adoc

@@ -24,6 +24,7 @@ include::modules/proc_publishing-previous-releases-in-one-continuous-document.ad
 
 include::modules/ref_differences-between-acorns-and-corn-3.adoc[leveloffset=+1]
 
+include::assembly_troubleshooting.adoc[leveloffset=+1]
 
 == Known issues and limitations
 

Diff for: docs/modules/proc_chapter-missing-in-build.adoc

@@ -0,0 +1,23 @@
+:_content-type: PROCEDURE
+
+[id="chapter-missing-in-build_{context}"]
+= Chapter does not appear in build
+
+The following error message in an aCoRNs build indicates that the file for a chapter was not generated:
+
+[source,text]
+----
+Unresolved directive in master-template.adoc - include::acorns/generated/internal/assembly_deprecated-functionality.adoc[leveloffset=+1]
+----
+
+aCoRNs generates either an assembly or a reference module for a chapter, depending on the structure:
+
+* If a chapter contains subsections, aCoRNs generates an assembly:
++
+`acorns/generated/internal/assembly_deprecated-functionality.adoc`.
+
+* If a chapter contains no subsections, aCoRNs generates a reference module:
++
+`acorns/generated/internal/ref_deprecated-functionality.adoc`.
+
+If you change a section from _no subsections_ to _subsections_ or vice versa, you must manually update the `master-template.adoc` file so that the included file is correct.

Diff for: docs/modules/proc_ticket-missing-in-subsection.adoc

@@ -0,0 +1,32 @@
+:_content-type: PROCEDURE
+
+[id="ticket-missing-in-subsection_{context}"]
+= Ticket does not appear in subsection
+
+If you created subsections in the `templates.yaml` file and a ticket does not appear in the builds, the most common reason is that the ticket does not match the filter.
+For example, the *Component* field of the ticket might not match the component filter of the subsection.
+
+. Check the ticket to ensure that the value of the *Component* field is correct, for example, `FIPS`.
+. In your repository, check the filter of the subsection in the `acorns/templates.yaml` file:
++
+[source,text]
+----
+  - &security
+    title: "Security and authentication"
+    filter
+      component: ['Security','SCAP Plugin']
+----
+
+. Add the ticket component to the subsection filter:
++
+[source,text]
+----
+      component: ['Security','SCAP Plugin','FIPS']
+----
++
+Alternatively, add a component override to the ticket in the `acorns/tickets.yaml` file:
++
+[source,text]
+----
+  - [Jira, key: PROJECT-12345, { overrides: {components: ['Security']} }]
+----