Add boilerplate product guide

.github/workflows/docs.yaml

@@ -0,0 +1,78 @@
+##
+## Copyright (c) 2023-2025 The Johns Hopkins University Applied Physics
+## Laboratory LLC.
+##
+## This file is part of the Bundle Protocol Security Library (BSL).
+##
+## Licensed under the Apache License, Version 2.0 (the "License");
+## you may not use this file except in compliance with the License.
+## You may obtain a copy of the License at
+##     http://www.apache.org/licenses/LICENSE-2.0
+## Unless required by applicable law or agreed to in writing, software
+## distributed under the License is distributed on an "AS IS" BASIS,
+## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+## See the License for the specific language governing permissions and
+## limitations under the License.
+##
+## This work was performed for the Jet Propulsion Laboratory, California
+## Institute of Technology, sponsored by the United States Government under
+## the prime contract 80NM0018D0004 between the Caltech and NASA under
+## subcontract 1700763.
+##
+
+name: Build documentation
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: dependencies
+        run: |
+          sudo apt-get update && sudo apt-get install -y cmake make coreutils ruby asciidoctor graphviz inkscape dblatex docbook-xsl-ns xsltproc xmlstarlet
+          sudo gem install asciidoctor-diagram
+      - name: build
+        env:
+          DESTDIR: public
+        run: |
+          cmake -S . -B build
+          cmake --build build
+          cmake --install build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: public
+
+  deploy:
+    # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+    # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+    concurrency:
+      group: "pages"
+      cancel-in-progress: false
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs
+          path: public
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: public
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -1,3 +1,10 @@
 # editor files
 *~
-*.bak
+.#*
+.project
+.cproject
+
+# generated files
+build
+*/docinfo.xml
+public

CMakeLists.txt

@@ -0,0 +1,33 @@
+#[[
+Copyright (c) 2023-2025 The Johns Hopkins University Applied Physics
+Laboratory LLC.
+
+This file is part of the Bundle Protocol Security Library (BSL).
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+This work was performed for the Jet Propulsion Laboratory, California
+Institute of Technology, sponsored by the United States Government under
+the prime contract 80NM0018D0004 between the Caltech and NASA under
+subcontract 1700763.
+]]
+cmake_minimum_required(VERSION 3.16)
+# No compiler checks
+project(bsl-docs LANGUAGES )
+set(CMAKE_INSTALL_PREFIX "")
+
+#add_subdirectory(user-guide)
+add_subdirectory(product-guide)
+
+install(
+  FILES index.html
+  DESTINATION .
+)

CODE_OF_CONDUCT.md

@@ -1,8 +1,8 @@
 <!--
-Copyright (c) 2023-2024 The Johns Hopkins University Applied Physics
+Copyright (c) 2023-2025 The Johns Hopkins University Applied Physics
 Laboratory LLC.
 
-This file is part of the BPSec Library (BSL).
+This file is part of the Bundle Protocol Security Library (BSL).
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

CONTRIBUTING.md

@@ -1,8 +1,8 @@
 <!--
-Copyright (c) 2023-2024 The Johns Hopkins University Applied Physics
+Copyright (c) 2023-2025 The Johns Hopkins University Applied Physics
 Laboratory LLC.
 
-This file is part of the BPSec Library (BSL).
+This file is part of the Bundle Protocol Security Library (BSL).
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

README.md

@@ -1,8 +1,8 @@
 <!--
-Copyright (c) 2023-2024 The Johns Hopkins University Applied Physics
+Copyright (c) 2023-2025 The Johns Hopkins University Applied Physics
 Laboratory LLC.
 
-This file is part of the BPSec Library (BSL).
+This file is part of the Bundle Protocol Security Library (BSL).
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -26,6 +26,23 @@ This repository hosts out-of-source documentation related to the AMMOS project t
 Out-of-source documentation includes project background, requirements, and design materials.
 The in-source documentation includes API documentation, development conventions and scripts, build and runtime needs and procedures, and unit test fixtures.
 
+## Design Documentation
+
 The design of the BSL is based on the overall [BSL Requirements](BSL%20Software%20Requirements%20Document.pdf) for the initial release version.
 
 The initial design overview is presented as [Preliminary Design Review (PDR) slides](BSL%20PDR.pdf) with a more detailed description in the [Critical Design Review (CDR) slides](BSL%20CDR.pdf). All of this earlier design material is superseded by any of the in-source documentation, which represents the actual realized library API and how it may change over time in different versions.
+
+## Manuals
+
+This repository contains User and Product Guides for the BSL.
+The User GUide is focused on introducing the API and high-level workflows of the BSL and points to specific parts of the software interface API for lower-level details.
+The Product Guide is focused on how to install the runtime and development packages to make use of the BSL and how to maintain and upgrade a deployment of the BSL.
+
+These are written with [AsciiDoc](https://asciidoc.org/) and intended for PDF and HTML publication formats.
+
+Once tools are installed and available, the following commands will build the guide documents.
+```
+cmake -S . -B build
+cmake --build build
+cmake --install build
+```

apply_license.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+##
+## Copyright (c) 2023-2025 The Johns Hopkins University Applied Physics
+## Laboratory LLC.
+##
+## This file is part of the Bundle Protocol Security Library (BSL).
+##
+## Licensed under the Apache License, Version 2.0 (the "License");
+## you may not use this file except in compliance with the License.
+## You may obtain a copy of the License at
+##     http://www.apache.org/licenses/LICENSE-2.0
+## Unless required by applicable law or agreed to in writing, software
+## distributed under the License is distributed on an "AS IS" BASIS,
+## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+## See the License for the specific language governing permissions and
+## limitations under the License.
+##
+## This work was performed for the Jet Propulsion Laboratory, California
+## Institute of Technology, sponsored by the United States Government under
+## the prime contract 80NM0018D0004 between the Caltech and NASA under
+## subcontract 1700763.
+##
+
+# Apply copyright and license markings to source files.
+#
+# Requires installation of:
+#  pip3 install licenseheaders
+# Run as:
+#  ./apply_license.sh {specific dir}
+#
+set -e
+
+SELFDIR=$(realpath $(dirname "${BASH_SOURCE[0]}"))
+
+LICENSEOPTS="${LICENSEOPTS} --tmpl ${SELFDIR}/apply_license.tmpl"
+LICENSEOPTS="${LICENSEOPTS} --years 2023-$(date +%Y)"
+# Excludes only apply to directory (--dir) mode and not file mode
+#LICENSEOPTS="${LICENSEOPTS} --exclude *.yml "
+
+
+# Specific paths
+if [[ $# -gt 0 ]]
+then
+    echo "Applying markings to selected $@ ..."
+    licenseheaders ${LICENSEOPTS} --dir $@
+    exit 0
+fi
+
+
+echo "Applying markings to source..."
+# Directory trees
+for DIRNAME in product-guide user-guide .github
+do
+    licenseheaders ${LICENSEOPTS} --dir ${SELFDIR}/${DIRNAME}
+done
+# Specific top-level files
+for FILEPATH in $(find "${SELFDIR}" -maxdepth 1 -type f)
+do
+    licenseheaders ${LICENSEOPTS} --file ${FILEPATH}
+done

apply_license.tmpl

@@ -0,0 +1,19 @@
+Copyright (c) ${years} The Johns Hopkins University Applied Physics
+Laboratory LLC.
+
+This file is part of the Bundle Protocol Security Library (BSL).
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+This work was performed for the Jet Propulsion Laboratory, California
+Institute of Technology, sponsored by the United States Government under
+the prime contract 80NM0018D0004 between the Caltech and NASA under
+subcontract 1700763.

product-guide/CMakeLists.txt

@@ -0,0 +1,101 @@
+#[[
+Copyright (c) 2023-2025 The Johns Hopkins University Applied Physics
+Laboratory LLC.
+
+This file is part of the Bundle Protocol Security Library (BSL).
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+This work was performed for the Jet Propulsion Laboratory, California
+Institute of Technology, sponsored by the United States Government under
+the prime contract 80NM0018D0004 between the Caltech and NASA under
+subcontract 1700763.
+]]
+cmake_minimum_required(VERSION 3.16)
+get_filename_component(DIRNAME ${CMAKE_CURRENT_LIST_DIR} NAME)
+# No compiler checks
+project(${DIRNAME} VERSION 0 LANGUAGES )
+
+
+# File paths
+set(ADOC_SOURCE "${CMAKE_CURRENT_SOURCE_DIR}/manual.adoc")
+
+
+find_program(ASCIIDOC asciidoctor REQUIRED)
+set(OUT_DOCINFO "docinfo.xml")
+configure_file(
+  "${CMAKE_CURRENT_SOURCE_DIR}/${OUT_DOCINFO}.in"
+  "${CMAKE_CURRENT_SOURCE_DIR}/${OUT_DOCINFO}"
+  @ONLY
+)
+set(OUT_DBOOK "manual.docbook.xml")
+add_custom_command(
+  OUTPUT ${OUT_DBOOK}
+  DEPENDS ${ADOC_SOURCE} ${OUT_DOCINFO}
+  COMMAND
+    ${ASCIIDOC} -v -r asciidoctor-diagram
+    --base-dir ${CMAKE_CURRENT_SOURCE_DIR}
+    --destination-dir ${CMAKE_CURRENT_BINARY_DIR}
+    -o ${OUT_DBOOK}
+    ${ADOC_SOURCE}
+)
+# Place source images into build directory
+set(INSTALL_IMGS ${CMAKE_CURRENT_SOURCE_DIR}/install_imgs.sh)
+add_custom_target(
+  ${PROJECT_NAME}-img-bin
+  DEPENDS ${INSTALL_IMGS} ${OUT_DBOOK}
+  COMMAND ${INSTALL_IMGS} ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR} ${OUT_DBOOK}
+)
+
+find_program(XSLTPROC xsltproc REQUIRED)
+set(HTML_XSLT "${CMAKE_CURRENT_SOURCE_DIR}/xhtml-opts.xsl")
+find_program(XMLSTARLET xmlstarlet REQUIRED)
+set(OUT_HTML "html/index.html")
+set(OUT_CSS "html/docbook.css")
+add_custom_command(
+  OUTPUT ${OUT_HTML}
+  BYPRODUCTS ${OUT_CSS}
+  DEPENDS ${OUT_DBOOK} ${HTML_XSLT}
+  COMMAND ${XSLTPROC} -o ${OUT_HTML} ${HTML_XSLT} ${OUT_DBOOK}
+)
+# Place needed images into HTML tree
+add_custom_target(
+  ${PROJECT_NAME}-img-html
+  DEPENDS ${INSTALL_IMGS} ${OUT_HTML} ${PROJECT_NAME}-img-bin
+  COMMAND ${INSTALL_IMGS} ${CMAKE_CURRENT_BINARY_DIR} "${CMAKE_CURRENT_BINARY_DIR}/html"
+)
+add_custom_target(
+  ${PROJECT_NAME}-html ALL
+  DEPENDS ${OUT_HTML} ${PROJECT_NAME}-img-html
+)
+install(
+  DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html"
+  DESTINATION ${PROJECT_NAME}
+)
+
+
+find_program(DBLATEX dblatex REQUIRED)
+set(PDF_XSLT "${CMAKE_CURRENT_SOURCE_DIR}/pdf-opts.xsl")
+set(OUT_PDF "manual.pdf")
+add_custom_command(
+  OUTPUT ${OUT_PDF}
+  DEPENDS ${OUT_DBOOK} ${PDF_XSLT} ${PROJECT_NAME}-img-bin
+  COMMAND ${DBLATEX} -o ${OUT_PDF} --xsl-user=${PDF_XSLT} ${OUT_DBOOK}
+)
+add_custom_target(
+  ${PROJECT_NAME}-pdf ALL
+  DEPENDS ${OUT_PDF}
+)
+install(
+  FILES "${CMAKE_CURRENT_BINARY_DIR}/${OUT_PDF}"
+  DESTINATION ${PROJECT_NAME}
+#  RENAME "ANMS Product Guide v${PROJECT_VERSION}.pdf"
+)