diff --git a/Handbook/GNUmakefile b/Handbook/GNUmakefile index 4052688d..2abe480f 100644 --- a/Handbook/GNUmakefile +++ b/Handbook/GNUmakefile @@ -41,10 +41,12 @@ SG_PLUGIN_DIR := $(realpath $(SG_HANDBOOK_DIR)/..) SG_PLUGIN_RESOURCES_DIR := $(SG_PLUGIN_DIR)/Resources SG_PLUGIN_FILE := $(SG_PLUGIN_DIR)/SenseGlove.uplugin +SG_DOCUMENTATION_URL := https://unreal.docs.senseglove.com SG_DOCUMENTATION_DIR := $(SG_PLUGIN_DIR)/Documentation SG_DOCUMENTATION_EPUB_DIR := $(SG_DOCUMENTATION_DIR)/epub SG_DOCUMENTATION_HTML_DIR := $(SG_DOCUMENTATION_DIR)/html SG_DOCUMENTATION_PDF_DIR := $(SG_DOCUMENTATION_DIR)/pdf-outline +SG_DOCUMENTATION_PDF_FILE := $(SG_DOCUMENTATION_PDF_DIR)/output.pdf SG_BROWSER_BINARY_PATH_LINUX := $(shell which brave-bin 2>/dev/null) SG_BROWSER_BINARY_PATH_WINDOWS := C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe @@ -178,6 +180,12 @@ ifeq ($(strip $(SG_HANDBOOK_REVISION)),) SG_HANDBOOK_REVISION := mismatched endif # ($(strip $(SG_HANDBOOK_REVISION)),) +ifneq ($(strip $(SG_HANDBOOK_REVISION)),mismatched) +SG_HANDBOOK_REVISION_URL := $(SG_DOCUMENTATION_URL)/$(SG_HANDBOOK_REVISION) +SG_HANDBOOK_ESCAPED_NAME := $(shell echo $(SG_PROJECT_NAME)-$(SG_HANDBOOK_REVISION) | tr '[:upper:]' '[:lower:]' | sed 's/ /-/g') +SG_HANDBOOK_PDF_URL := $(SG_HANDBOOK_REVISION_URL)/$(SG_HANDBOOK_ESCAPED_NAME).pdf +endif + ################################################################################ # mdbook-pdf Configuration ################################################################################ @@ -227,8 +235,11 @@ $(info Setting up a deployment temporary directory '$(SG_HANDBOOK_DEPLOY_TEMP_DI SG_HANDBOOK_DEPLOY_TEMP_DIR := $(shell mktemp -d -t $(SG_HANDBOOK_DEPLOY_TEMP_DIR_NAME)) $(info Temporary directory has been set up at '$(SG_HANDBOOK_DEPLOY_TEMP_DIR)') +SG_HANDBOOK_DEPLOY_GENERATED_PDF_FILE := $(SG_HANDBOOK_DEPLOY_TEMP_DIR)/$(SG_HANDBOOK_ESCAPED_NAME).pdf + SG_HANDBOOK_DEPLOY_REVISION_LIST_FILE := $(SG_HANDBOOK_DEPLOY_TEMP_DIR)/revisions.txt -SG_HANDBOOK_DEPLOY_GENERATED_INDEX_FILE := $(SG_HANDBOOK_DEPLOY_TEMP_DIR)/index.html + +SG_HANDBOOK_DEPLOY_GENERATED_HOME_INDEX_FILE := $(SG_HANDBOOK_DEPLOY_TEMP_DIR)/index.html ################################################################################ # Env Configuration Functions @@ -271,6 +282,8 @@ info: @echo "$(SG_PROJECT_NAME) build information:" @echo "" @echo " - Handbook Revision : $(SG_HANDBOOK_REVISION)" + @echo " - Handbook Revision URL : $(SG_HANDBOOK_REVISION_URL)" + @echo " - Handbook PDF URL : $(SG_HANDBOOK_PDF_URL)" @echo " - Git Branch : $(SG_GIT_BRANCH)" @echo " - Git Tag : $(SG_GIT_TAG)" @echo " - Git Commit : $(SG_GIT_COMMIT)" @@ -378,6 +391,8 @@ _mdbook_serve: @echo "Serving $(SG_HANDBOOK_DIR)..." @env SG_PROJECT_NAME='$(SG_PROJECT_NAME)' \ SG_HANDBOOK_REVISION='$(SG_HANDBOOK_REVISION)' \ + SG_HANDBOOK_REVISION_URL='$(SG_HANDBOOK_REVISION_URL)' \ + SG_HANDBOOK_PDF_URL='$(SG_HANDBOOK_PDF_URL)' \ SG_GIT_BRANCH='$(SG_GIT_BRANCH)' \ SG_GIT_TAG='$(SG_GIT_TAG)' \ SG_GIT_COMMIT='$(SG_GIT_COMMIT)' \ @@ -405,6 +420,8 @@ _mdbook_build: @echo "Building $(SG_HANDBOOK_DIR)..." @env SG_PROJECT_NAME='$(SG_PROJECT_NAME)' \ SG_HANDBOOK_REVISION='$(SG_HANDBOOK_REVISION)' \ + SG_HANDBOOK_REVISION_URL='$(SG_HANDBOOK_REVISION_URL)' \ + SG_HANDBOOK_PDF_URL='$(SG_HANDBOOK_PDF_URL)' \ SG_GIT_BRANCH='$(SG_GIT_BRANCH)' \ SG_GIT_TAG='$(SG_GIT_TAG)' \ SG_GIT_COMMIT='$(SG_GIT_COMMIT)' \ @@ -432,6 +449,14 @@ _deploy: @echo "Deploying '$(SG_HANDBOOK_DIR)' to '$(SG_HANDBOOK_SSH_USER)@$(SG_HANDBOOK_SSH_HOST):$(SG_HANDBOOK_SSH_REMOTE_DIR)/$(SG_HANDBOOK_REVISION)'..." @rsync -avze "ssh -p $(SG_HANDBOOK_SSH_PORT)" --perms --chmod=u+rwx,g+rx,o+rx,g-w,o-wx\ --delete $(SG_DOCUMENTATION_HTML_DIR)/ $(SG_HANDBOOK_SSH_USER)@$(SG_HANDBOOK_SSH_HOST):$(SG_HANDBOOK_SSH_REMOTE_DIR)/$(SG_HANDBOOK_REVISION) + @echo "Copying '$(SG_DOCUMENTATION_PDF_FILE)' to '$(SG_HANDBOOK_DEPLOY_GENERATED_PDF_FILE)'..." + @cp -vr $(SG_DOCUMENTATION_PDF_FILE) $(SG_HANDBOOK_DEPLOY_GENERATED_PDF_FILE) + @echo "Uploading '$(SG_HANDBOOK_DEPLOY_GENERATED_PDF_FILE)' to '$(SG_HANDBOOK_SSH_USER)@$(SG_HANDBOOK_SSH_HOST):$(SG_HANDBOOK_SSH_REMOTE_DIR)/$(SG_HANDBOOK_REVISION)'..." + @scp \ + -P $(SG_HANDBOOK_SSH_PORT) \ + $(SG_HANDBOOK_DEPLOY_GENERATED_PDF_FILE) \ + $(SG_HANDBOOK_SSH_USER)@$(SG_HANDBOOK_SSH_HOST):$(SG_HANDBOOK_SSH_REMOTE_DIR)/$(SG_HANDBOOK_REVISION) + @cp -vr $(SG_DOCUMENTATION_PDF_FILE) $(SG_HANDBOOK_DEPLOY_GENERATED_PDF_FILE) @echo "Retrieving the list of deployed handbook revisions from '$(SG_HANDBOOK_SSH_USER)@$(SG_HANDBOOK_SSH_HOST):$(SG_HANDBOOK_SSH_PORT)/$(SG_HANDBOOK_SSH_REMOTE_DIR)'..." @ssh \ -p $(SG_HANDBOOK_SSH_PORT) $(SG_HANDBOOK_SSH_USER)@$(SG_HANDBOOK_SSH_HOST) \ @@ -449,22 +474,22 @@ _deploy: @echo "Revisions list saved to '$(SG_HANDBOOK_DEPLOY_REVISION_LIST_FILE)'!" @echo "Current revisions:" @sed 's/^/ - /' $(SG_HANDBOOK_DEPLOY_REVISION_LIST_FILE) - @echo "Generating '$(SG_HANDBOOK_DEPLOY_GENERATED_INDEX_FILE)'..." - @echo "

Welcome to the SenseGlove Unreal Engine Handbook

Please choose a revision to continue!

* Please note that the next revision is the documentation for the unstable next release of the plugin and subject to change!
" >> $(SG_HANDBOOK_DEPLOY_GENERATED_INDEX_FILE) + @echo "Generating '$(SG_HANDBOOK_DEPLOY_GENERATED_HOME_INDEX_FILE)'..." + @echo "

Welcome to the SenseGlove Unreal Engine Handbook

Please choose a revision to continue!

* Please note that the next revision is the documentation for the unstable next release of the plugin and subject to change!
" >> $(SG_HANDBOOK_DEPLOY_GENERATED_HOME_INDEX_FILE) @while read dir; \ do \ echo ""; \ - done < $(SG_HANDBOOK_DEPLOY_REVISION_LIST_FILE) >> $(SG_HANDBOOK_DEPLOY_GENERATED_INDEX_FILE) - @echo "
" >> $(SG_HANDBOOK_DEPLOY_GENERATED_INDEX_FILE) - @echo "Uploading '$(SG_HANDBOOK_DEPLOY_GENERATED_INDEX_FILE)' to '$(SG_HANDBOOK_SSH_USER)@$(SG_HANDBOOK_SSH_HOST):$(SG_HANDBOOK_SSH_REMOTE_DIR)'" + done < $(SG_HANDBOOK_DEPLOY_REVISION_LIST_FILE) >> $(SG_HANDBOOK_DEPLOY_GENERATED_HOME_INDEX_FILE) + @echo "
" >> $(SG_HANDBOOK_DEPLOY_GENERATED_HOME_INDEX_FILE) + @echo "Uploading '$(SG_HANDBOOK_DEPLOY_GENERATED_HOME_INDEX_FILE)' to '$(SG_HANDBOOK_SSH_USER)@$(SG_HANDBOOK_SSH_HOST):$(SG_HANDBOOK_SSH_REMOTE_DIR)'" @scp \ -P $(SG_HANDBOOK_SSH_PORT) \ - $(SG_HANDBOOK_DEPLOY_GENERATED_INDEX_FILE) \ - $(SG_HANDBOOK_SSH_USER)@$(SG_HANDBOOK_SSH_HOST):$(SG_HANDBOOK_SSH_REMOTE_DIR) + $(SG_HANDBOOK_DEPLOY_GENERATED_HOME_INDEX_FILE) \ + $(SG_HANDBOOK_SSH_USER)@$(SG_HANDBOOK_SSH_HOST):$(SG_HANDBOOK_SSH_REMOTE_DIR) \ No newline at end of file diff --git a/Handbook/bin/sg-preprocessor.sh b/Handbook/bin/sg-preprocessor.sh index d6925839..b1236883 100644 --- a/Handbook/bin/sg-preprocessor.sh +++ b/Handbook/bin/sg-preprocessor.sh @@ -42,6 +42,8 @@ escape_string() { SG_PROJECT_NAME_ESCAPED=$(escape_string "${SG_PROJECT_NAME}") SG_HANDBOOK_REVISION_ESCAPED=$(escape_string "${SG_HANDBOOK_REVISION}") +SG_HANDBOOK_REVISION_URL_ESCAPED=$(escape_string "${SG_HANDBOOK_REVISION_URL}") +SG_HANDBOOK_PDF_URL_ESCAPED=$(escape_string "${SG_HANDBOOK_PDF_URL}") SG_GIT_BRANCH_ESCAPED=$(escape_string "${SG_GIT_BRANCH}") SG_GIT_TAG_ESCAPED=$(escape_string "${SG_GIT_TAG}") SG_GIT_COMMIT_ESCAPED=$(escape_string "${SG_GIT_COMMIT}") @@ -58,27 +60,41 @@ SG_PLUGIN_VERSION_PATCH_ESCAPED=$(escape_string "${SG_PLUGIN_VERSION_PATCH}") SG_BUILD_HOST_ESCAPED=$(escape_string "${SG_BUILD_HOST}") SG_BUILD_TIME_ESCAPED=$(escape_string "${SG_BUILD_TIME}") -PARSED_BOOK=$(echo "${BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-project-name }}\"; \"${SG_PROJECT_NAME_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-handbook-revision }}\"; \"${SG_HANDBOOK_REVISION_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-git-branch }}\"; \"${SG_GIT_BRANCH_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-git-tag }}\"; \"${SG_GIT_TAG_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-git-commit }}\"; \"${SG_GIT_COMMIT_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-git-commit-nums-since-tag }}\"; \"${SG_GIT_COMMIT_NUMS_SINCE_TAG_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-git-tree-state }}\"; \"${SG_GIT_TREE_STATE_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-git-version }}\"; \"${SG_GIT_VERSION_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-git-version-major }}\"; \"${SG_GIT_VERSION_MAJOR_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-git-version-minor }}\"; \"${SG_GIT_VERSION_MINOR_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-git-version-patch }}\"; \"${SG_GIT_VERSION_PATCH_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-plugin-version }}\"; \"${SG_PLUGIN_VERSION_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-plugin-version-major }}\"; \"${SG_PLUGIN_VERSION_MAJOR_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-plugin-version-minor }}\"; \"${SG_PLUGIN_VERSION_MINOR_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-plugin-version-patch }}\"; \"${SG_PLUGIN_VERSION_PATCH_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-build-host }}\"; \"${SG_BUILD_HOST_ESCAPED}\")") -PARSED_BOOK=$(echo "${PARSED_BOOK}" | xq "(.sections[] | select(has(\"Chapter\")) | .Chapter.content) |= sub(\"{{ #sg-build-time }}\"; \"${SG_BUILD_TIME_ESCAPED}\")") +PARSED_BOOK=$(echo "${BOOK}" | xq " + .sections[] |= ( + if has(\"Chapter\") then + .Chapter.content |= + walk(if type == \"string\" then + . | gsub(\"{{ #sg-project-name }}\"; \"${SG_PROJECT_NAME_ESCAPED}\") | + gsub(\"{{ #sg-handbook-revision }}\"; \"${SG_HANDBOOK_REVISION_ESCAPED}\") | + gsub(\"{{ #sg-handbook-revision-url }}\"; \"${SG_HANDBOOK_REVISION_URL_ESCAPED}\") | + gsub(\"{{ #sg-handbook-pdf-url }}\"; \"${SG_HANDBOOK_PDF_URL_ESCAPED}\") | + gsub(\"{{ #sg-git-branch }}\"; \"${SG_GIT_BRANCH_ESCAPED}\") | + gsub(\"{{ #sg-git-tag }}\"; \"${SG_GIT_TAG_ESCAPED}\") | + gsub(\"{{ #sg-git-commit }}\"; \"${SG_GIT_COMMIT_ESCAPED}\") | + gsub(\"{{ #sg-git-commit-nums-since-tag }}\"; \"${SG_GIT_COMMIT_NUMS_SINCE_TAG_ESCAPED}\") | + gsub(\"{{ #sg-git-tree-state }}\"; \"${SG_GIT_TREE_STATE_ESCAPED}\") | + gsub(\"{{ #sg-git-version }}\"; \"${SG_GIT_VERSION_ESCAPED}\") | + gsub(\"{{ #sg-git-version-major }}\"; \"${SG_GIT_VERSION_MAJOR_ESCAPED}\") | + gsub(\"{{ #sg-git-version-minor }}\"; \"${SG_GIT_VERSION_MINOR_ESCAPED}\") | + gsub(\"{{ #sg-git-version-patch }}\"; \"${SG_GIT_VERSION_PATCH_ESCAPED}\") | + gsub(\"{{ #sg-plugin-version }}\"; \"${SG_PLUGIN_VERSION_ESCAPED}\") | + gsub(\"{{ #sg-plugin-version-major }}\"; \"${SG_PLUGIN_VERSION_MAJOR_ESCAPED}\") | + gsub(\"{{ #sg-plugin-version-minor }}\"; \"${SG_PLUGIN_VERSION_MINOR_ESCAPED}\") | + gsub(\"{{ #sg-plugin-version-patch }}\"; \"${SG_PLUGIN_VERSION_PATCH_ESCAPED}\") | + gsub(\"{{ #sg-build-host }}\"; \"${SG_BUILD_HOST_ESCAPED}\") | + gsub(\"{{ #sg-build-time }}\"; \"${SG_BUILD_TIME_ESCAPED}\") + else + . + end) + else + . + end + )") # For debugging purpose only! #echo "CONTEXT: ${CONTEXT}" >&2 #echo "BOOK: ${BOOK}" >&2 #echo "PARSED_BOOK: ${PARSED_BOOK}" >&2 -echo "${PARSED_BOOK}" | xq '.' \ No newline at end of file +echo "${PARSED_BOOK}" | xq '.' diff --git a/Handbook/src/README.md b/Handbook/src/README.md index 04a68bd7..b103196c 100644 --- a/Handbook/src/README.md +++ b/Handbook/src/README.md @@ -4,7 +4,7 @@ Welcome to the documentation for the SenseGlove Unreal Engine Plugin (a.k.a. The This handbook is an ongoing effort and a work in progress to document the SenseGlove Unreal Engine Plugin. Feel free to visit this handbook on a regular basis. -Due to superior formatting and frequent updates, we recommend [the online version of the handbook](); nonetheless, it's available in [PDF](pdf/output.pdf) format as well. +Due to superior formatting and frequent updates, we recommend [the online version of the handbook]({{ #sg-handbook-revision-url }}); nonetheless, it's available in [PDF]({{ #sg-handbook-pdf-url }}) format as well. > [!TIP] > Feel free to check out [the SenseGlove Unreal Engine Plugin landing page on the UE Marketplace](https://www.unrealengine.com/marketplace/en-US/product/the-senseglove-unreal-engine-plugin) as well diff --git a/Handbook/src/misc/build-information.md b/Handbook/src/misc/build-information.md index 6fb0193c..146ae203 100644 --- a/Handbook/src/misc/build-information.md +++ b/Handbook/src/misc/build-information.md @@ -2,7 +2,9 @@ | | {{ #sg-project-name }} | |-----------------------|-------------------------------------| -| Handbook Revision | {{ #sg-handbook-revision }} | +| Handbook Revision | {{ #sg-handbook-revision }} | +| Handbook Revision URL | [{{ #sg-handbook-revision-url }}]({{ #sg-handbook-revision-url }}) | +| Handbook PDF URL | [{{ #sg-handbook-pdf-url }}]({{ #sg-handbook-pdf-url }}) | | Git Branch | {{ #sg-git-branch }} | | Git Tag | {{ #sg-git-tag }} | | Git Commit | {{ #sg-git-commit }} | @@ -17,4 +19,4 @@ | Plugin Version Minor | {{ #sg-plugin-version-minor }} | | Plugin Version Patch | {{ #sg-plugin-version-patch }} | | Build Host | {{ #sg-build-host }} | -| Build Time | {{ #sg-build-time }} | \ No newline at end of file +| Build Time | {{ #sg-build-time }} |