DOCS

distribution/docs/README.md

@@ -2,11 +2,138 @@
 
 Documentation is made available in a single document, or individual sections can be accessed based on audience need.
 
-## Managing DDF
-How to install and configure DDF, targeted for system administrators.
+## Documentation Library
 
-## Integrating DDF
-How to connect to and from DDF using service interfaces, targeted for system integrators.
+### DDF Introduction
+Overview of what DDF is and what DDF does
 
-## Extending DDF
-How to add and modify system behaviors, targeted for developers.
+### DDF: Quick Start Guide
+Set up a test, demonstration, or evaluation instance of DDF 
+
+### Managing DDF
+How to install, configure, and maintain DDF
+
+### DDF User's Guide
+Learn your way around the DDF documentation
+
+### Integrating with DDF
+How to connect to and from DDF using service interfaces
+
+### Developing DDF Components: Developer's Guide
+Create custom implementations of DDF interfaces
+
+### DDF Architecture
+Learn about how the components of DDF work together
+
+### DDF Reference Guide
+Complete list of possible configurations
+
+### DDF Metadata Reference Guide
+Schemas and attributes used by DDF
+
+### DDF Documentation: Complete Documentation
+All of the above, compliled into a single document
+
+## Documentation Module
+
+### Build Commands
+
+#### Build HTML documentation
+`mvn clean install`
+
+#### Build HTML and PDF documentation
+`mvn clean install -Prelease`
+
+#### Build Results
+
+These artifacts are produced by the standard build
+- `target/docs/html`: Rendered Content
+- `target/export-docs/` Zip of raw source files to use in downstream project
+- `target/export-templates/` Zip of template files to optionally use in downstream projects
+
+### plugins
+
+- `<maven-dependency-plugin>` This plugin retrieves any content from upstream projects. 
+- `<maven-resources-plugin>` copies all of the content, images, scripts, and configuration files to the target directory. During this process, the text files are filtered to replace placeholders with the configured values.
+- `<jbake-maven-plugin>` takes the filtered content pages and applies freemarker tempates to determine the order of the documents.
+  - The asciidoc files (`.adoc`) have assigned `type`, `order` and `parent` properties in their headers that determine placement within larger sections.
+
+_Asciidoctor header example_
+```
+:title: Configuring HTTP(S) Ports
+:type: configuration
+:status: published
+:parent: Configuring Federation
+:summary: Configure HTTP(S) Ports.
+:order: 01
+```
+
+  - The freemarker templates (`*.ftl`) iterate on the `type` properties to determine the document placement. Types are defined in the `jbake.properties` file.
+
+_jbake.properties excerpt_
+```
+output.extension=.adoc
+template.documentation.file=documentation.ftl
+template.introduction.file=overview.ftl
+template.coreConcept.file=overview.ftl
+template.subCoreConcept.file=overview.ftl
+template.quickStart.file=quickstart.ftl
+```
+  - The `order` property of each `adoc` file sorts the sections and `parent` property matches subsections to their larger placement. The templates can also adjust the outline level of a subsection within the document. I use a nested loop to get a three-level outline structure.
+
+_Freemarker (`*.ftl`) example_
+```
+<#list configuringIntros?sort_by("order") as ci>
+<#if (ci.status == "published")>
+
+\include::${ci.file}[leveloffset=+1]
+
+<#list configurations?sort_by("order") as configuration>
+<#if (configuration.parent == ci.title)>
+
+\include::${configuration.file}[leveloffset=+2]
+
+<#if (configuration.title == "Connecting to Sources")>
+
+<#include "sources.ftl">
+</#if>
+<#list subConfigurations?sort_by("order") as subConfiguration>
+<#if (subConfiguration.parent == configuration.title)>
+
+\include::${subConfiguration.file}[leveloffset=+3]
+
+</#if>
+</#list>
+</#if>
+</#list>
+</#if>
+</#list>
+```
+
+- `<asciidoctor-maven-plugin>` compiles the newly-created asciidoc content into the final, publishable form.
+  - `HTML` pages are run by default, `PDF` generation is optional in a development environment by creating a `<profile>` for PDF output.
+- `<maven-assembly>` files package the raw adocs, and completed versions in zip files for deployment.
+
+_asciidocs.xml excerpt_
+```
+<fileSet>
+    <fileMode>0644</fileMode>
+    <directoryMode>0755</directoryMode>
+    <directory>src/main/resources/content</directory>
+    <includes>
+        <include>**</include>
+    </includes>
+    <outputDirectory></outputDirectory>
+</fileSet>
+```
+
+- `<build-helper-maven-plugin>` deploys the published HTML and PDF files to the server for end-users to view.
+
+_pom.xml excerpt_
+```
+<artifact>
+    <file>${project.build.directory}/docs/html/documentation.html</file>
+    <type>html</type>
+    <classifier>documentation</classifier>
+</artifact>
+```

distribution/docs/src/main/resources/content/_architectures/_actionFramework/action-framework-intro.adoc

@@ -5,7 +5,7 @@
 :order: 05
 :summary: Introduction to the Action Framework.
 
-The Action Framework was designed as a way to limit dependencies between applications (apps) in a system.
+The ((Action Framework)) was designed as a way to limit dependencies between applications (apps) in a system.
 For instance, a feature in an app, such as an Atom feed generator, might want to include an external link as part of its feed's entries.
 That feature does not have to be coupled to a REST endpoint to work, nor does it have to depend on a specific implementation to get a link.
 In reality, the feature does not identify how the link is generated, but it does identify whether the link works or does not work when retrieving the intended entry's metadata.
@@ -17,6 +17,6 @@ The Action Framework consists of two major Java interfaces in its API:
 . `ddf.action.Action`
 . `ddf.action.ActionProvider`
 
-Actions:: Specific tasks that can be performed as services.
+((Actions)):: Specific tasks that can be performed as services.
 
-Action Providers:: Lists of related actions that a service is capable of performing.
+((Action Providers)):: Lists of related actions that a service is capable of performing.

distribution/docs/src/main/resources/content/_architectures/_actionFramework/action-providers.adoc

@@ -7,10 +7,10 @@
 :summary: Action Providers.
 
 .[[_included_action_providers]]Included Action Providers
-Download Resource ActionProvider:: Downloads a resource to the local product cache.
-IdP Logout Action Provider:: Identity Provider Logout.
-Karaf Logout Action:: Local Logout.
-LDAP Logout Action:: Ldap Logout.
-Overlay ActionProvider:: Provides a metacard URL that transforms the metacard into a geographically aligned image (suitable for overlaying on a map).
-View Metacard ActionProvider:: Provides a URL to a metacard.
-Metacard Transformer ActionProvider:: Provides a URL to a metacard that has been transformed into a specified format.
+((Download Resource ActionProvider)):: Downloads a resource to the local product cache.
+((IdP Logout Action Provider)):: Identity Provider Logout.
+((Karaf Logout Action)):: Local Logout.
+((LDAP Logout Action)):: Ldap Logout.
+((Overlay ActionProvider)):: Provides a metacard URL that transforms the metacard into a geographically aligned image (suitable for overlaying on a map).
+((View Metacard ActionProvider)):: Provides a URL to a metacard.
+((Metacard Transformer ActionProvider)):: Provides a URL to a metacard that has been transformed into a specified format.

distribution/docs/src/main/resources/content/_architectures/_asyncFramework/processing-framework-intro.adoc

@@ -10,7 +10,7 @@
 This code is experimental. While this interface is functional and tested, it may change or be removed in a future version of the library.
 ====
 
-The *Asynchronous Processing Framework* is a way to run plugins asynchronously. Generally, plugins that take a significant amount of processing time and whose
+The ((Asynchronous Processing Framework)) is a way to run plugins asynchronously. Generally, plugins that take a significant amount of processing time and whose
 results are not immediately required are good candidates for being asynchronously processed. A *Processing Framework* can either be run on the local or
 remote system. Once the *Processing Framework* finishes processing incoming requests, it may submit ``(Create|Update|Delete)Request``s to the Catalog. The type of plugins that a *Processing Framework*
 runs are the *Post-Process Plugins*. The *Post-Process Plugins* are triggered by the *Processing Post Ingest Plugin*, which is a *Post-Ingest Plugin*. *Post-Ingest Plugins* are run after the metacard
@@ -19,7 +19,7 @@ has been ingested into the Catalog. This feature is uninstalled by default.
 [WARNING]
 ====
 The *Processing Framework* does not support partial updates to the Catalog. This means that if any changes are made to a metacard in the Catalog between the time
-asynchronous processing starts and ends, those changes will be overwritten by the *ProcessingFramework* updates sent back to the Catalog. This feature should be used with caution.
+asynchronous processing starts and ends, those changes are overwritten by the *ProcessingFramework* updates sent back to the Catalog. This feature should be used with caution.
 ====
 
 .Processing Framework Architecture
@@ -141,7 +141,7 @@ A `ProcessRequest` contains a list of ``ProcessItem``s for the `ProcessingFramew
 should mark the `ProcessRequest` as already been processed, so that it does not process it again.
 
 .PostProcessPlugin
-The `PostProcessPlugin` is a plugin that will be run by the `ProcessingFramework`. It is capable of processing ``ProcessCreateItem``s, ``ProcessUpdateItem``s, and ``ProcessDeleteItem``s.
+The `PostProcessPlugin` is a plugin that is run by the `ProcessingFramework`. It is capable of processing ``ProcessCreateItem``s, ``ProcessUpdateItem``s, and ``ProcessDeleteItem``s.
 
 .ProcessItem
 [WARNING]

distribution/docs/src/main/resources/content/_architectures/_catalogFrameworks/catalog-api.adoc

@@ -6,15 +6,15 @@
 
 ==== Catalog API
 
-The Catalog API is an OSGi bundle (`catalog-core-api`) that contains the Java interfaces for the Catalog components and implementation classes for the Catalog Framework, Operations, and Data components.
+The ((Catalog API)) is an OSGi bundle (`catalog-core-api`) that contains the Java interfaces for the Catalog components and implementation classes for the Catalog Framework, Operations, and Data components.
 
 ===== Catalog API Search Interfaces
 
 The Catalog API includes two different search interfaces.
 
 ${ddf-ui} Application Search Interface:: The ${branding} Search UI application provides a graphic interface to return results and locate them on an interactive globe or map.
 
-SSH Search Interface:: Additionally, it is possible to use a client script to remotely access ${branding} via SSH and send console commands to search and ingest data.
+((SSH Search Interface)):: Additionally, it is possible to use a client script to remotely access ${branding} via SSH and send console commands to search and ingest data.
 
 ===== Catalog Search Result Objects
 
@@ -36,8 +36,8 @@ Searching the catalog involves three basic steps:
 .. For contextual search, optionally set the `fuzzy` flag to `true` or `false` (the default value for the `Metadata Catalog` `fuzzy` flag is `true`, while the `portal` default value is `false`).
 .. For contextual search, optionally set the `caseSensitive` flag to true (the default is that `caseSensitive` flag is NOT set and queries are not case sensitive).
 Doing so enables case sensitive matching on the search criteria.
-For example, if `caseSensitive` is set to true and the phrase is “Baghdad” then only metadata containing “Baghdad” with the same matching case will be returned.
-Words such as “baghdad”, “BAGHDAD”,  and “baghDad” will not be returned because they do not match the exact case of the search term.
+For example, if `caseSensitive` is set to true and the phrase is “Baghdad” then only metadata containing “Baghdad” with the same matching case is returned.
+Words such as “baghdad”, “BAGHDAD”,  and “baghDad” are not returned because they do not match the exact case of the search term.
 . Issue a search.
 . Examine the results.
 
@@ -76,7 +76,7 @@ There are three policies available.
 
 |===
 
-If no sort policy is defined for a particular search, the temporal policy will automatically be applied.
+If no sort policy is defined for a particular search, the temporal policy is automatically applied.
 
 
 ===== Product Retrieval
@@ -105,7 +105,7 @@ The Endpoint bundle contains a Web service that exposes the interface to retriev
 The Endpoint calls the `CatalogFramework` to execute the operations of its specification.
 The `CatalogFramework` relies on the Sources to execute the actual resource retrieval.
 Optional `PreResource` and `PostResource` Catalog Plugins may be invoked by the `CatalogFramework` to modify the resource retrieval request/response prior to the Catalog Provider processing the request and providing the response.
-It is possible to retrieve resources from specific remote Sources by specifying the site name(s) in the request.
+It is possible to retrieve resources from specific remote Sources by specifying the site names in the request.
 
 .Product Caching
 Product Caching is enabled by default.

distribution/docs/src/main/resources/content/_architectures/_catalogFrameworks/catalog-framework-camel-component.adoc

@@ -1,11 +1,11 @@
 :title: Catalog Framework Camel Component
 :type: catalogFramework
 :status: published
-:summary: Supports creating, updating, and deleting metacards using the Catalog Framework from a Camel route.
+:summary: Supports creating, updating, and deleting metacards using the Catalog Framework from a Camel route.
 :link: _catalog_framework_camel_component
 :order: 01
 
-The Catalog Framework Camel Component supports creating, updating, and deleting metacards using the Catalog Framework from a Camel route.
+The ((Catalog Framework Camel Component)) supports creating, updating, and deleting metacards using the Catalog Framework from a Camel route.
 
 .URI Format
 ----
@@ -22,18 +22,18 @@ catalog:framework
 |the operation to perform using the Catalog Framework (possible values are CREATE \| UPDATE \| DELETE)
 |===
 
-===== Sending Messages to Catalog Framework Endpoint
+== Sending Messages to Catalog Framework Endpoint
 
 .Catalog Framework Producer
-In Producer mode, the component provides the ability to supply different inputs and have the Catalog Framework perform different operations based upon the header values.  
+In Producer mode, the component provides the ability to supply different inputs and have the Catalog Framework perform different operations based upon the header values.
 
-For the CREATE and UPDATE operation, the message body can contain a list of metacards or a single metacard object. 
+For the CREATE and UPDATE operation, the message body can contain a list of metacards or a single metacard object.
 
 For the DELETE operation, the message body can contain a list of strings or a single string object.
-The string objects represent the IDs of metacards to be deleted. 
-The exchange's "in" message will be set with the affected metacards.
-In the case of a CREATE, it will be updated with the created metacards.
-In the case of the UPDATE, it will be updated with the updated metacards and with the DELETE it will contain the deleted metacards.
+The string objects represent the IDs of metacards to be deleted.
+The exchange's "in" message is set with the affected metacards.
+In the case of a CREATE, it is updated with the created metacards.
+In the case of the UPDATE, it is updated with the updated metacards and with the DELETE it contains the deleted metacards.
 
 .Catalog Framework Camel Component Operations
 [cols="2,2,3" options="header"]
@@ -60,7 +60,7 @@ In the case of the UPDATE, it will be updated with the updated metacards and wit
 [NOTE]
 ====
 If there is an exception thrown while the route is being executed, a
-FrameworkProducerException will be thrown causing the route to fail
+`FrameworkProducerException` is thrown causing the route to fail
 with a CamelExecutionException.
 ====