Merge pull request #2664 from jimklimov/fix-some-asciidoc

Fix some asciidoc cross-file links

INSTALL.nut.adoc

@@ -1,5 +1,175 @@
 Installation instructions
 =========================
+// NOTE: No blank line here, document-header include processing should kick in!
+//GH_MARKUP_1095//ifdef::top_srcdir[]
+//GH_MARKUP_1095//include::{top_srcdir}docs/asciidoc-vars.conf[]
+//GH_MARKUP_1095//endif::top_srcdir[]
+//GH_MARKUP_1095//ifndef::top_srcdir[]
+//GH_MARKUP_1095//include::docs/asciidoc-vars.conf[]
+//GH_MARKUP_1095//endif::top_srcdir[]
+//GH_MARKUP_1095_INCLUDE_BEGIN//7e01bd198 (2024-10-20) docs/asciidoc-vars.conf: try defining linksrcdoc macro
+ifndef::asciidoc-vars-nut-included[]
+:asciidoc-vars-nut-included:	true
+// NOTE: The big block of comments and definitions below comes from
+// NUT::docs/asciidoc-vars.conf and is included into top-level document
+// sources by maintenance recipes directly (`make maintainer-asciidocs`),
+// due to current limitations of the GitHub Web UI asciidoc renderer.
+// Hopefully it can be dropped in favor of compact include definitions
+// (see README.adoc for anticipated example) after this issue is resolved
+// on their side:
+// * https://github.com/github/markup/issues/1095
+//
+// This file should be included into NUT documentation sources to consistently
+// define certain expandable attributes, with contents defined based on the
+// rendition target (e.g. GitHub Web UI, plain text, locally built HTML/PDF...)
+// Note that currently GitHub Web UI references lead to nut-website (as of
+// last built and published revision), not to neighboring documents in the
+// source browser (which would make sense for branch revisions, etc.) due
+// to certain complexity about referencing other-document sections with a
+// partially functional rendering engine there. Exploration and fixes are
+// welcome (actually working links like
+// https://github.com/networkupstools/nut/tree/master#installing or
+// https://github.com/networkupstools/nut/blob/master/UPGRADING.adoc#changes-from-274-to-280
+// do seem promising)!
+//
+// Since the GitHub UI does not allow use of custom asciidoc configuration
+// files, or generally does not process the `include:` requests at this time,
+// clumsy expandable attributes had to be used (usually a set including a
+// prefix with meaningful name, and one or more separators and/or a suffix
+// with shortened names). For our classic documentation renditions, they
+// should resolve to properly defined macros from `docs/asciidoc.conf`
+// (usually named same as the variables defined here, for simplicity):
+// * `linksrcdoc` allows to refer to a source of documentation file
+//   relative to the root of NUT code base.
+// * `linkdoc` allows to refer to a file under `docs/` directory (or
+//   its nut-website rendition).
+// * `xref` substitutes the asciidoc shorthand '<< >>' syntax with
+//   attributes that conditionally expand to:
+//   - links on GitHub (references can point at most to a section of
+//     level docs/common.xsl's <chunk.section.depth>), or
+//   - xref asciidoc macros when generating docs.
+// * `linksingledoc` guarantees that, when chunked HTML is generated,
+//   the link always points to a non-chunked file.
+// * `linkman2` allows to support different names for the manpage and
+//   the command shown. This is also needed to properly display links
+//   to manpages in both GitHub and generated docs without defining an
+//   attribute for each manpage.
+//
+// Optional attributes set by callers:
+// * `website-url` (defaulted below) may be used for "historic website"
+//   snapshot builds... hopefully
+// * `website` is used as a boolean toggle in our recipes for nut-website
+//   vs. offline documentation renditions
+// * `env-github` is used as a boolean toggle, set by GitHub Web-UI renderer
+// * `(top_)srcdir` and `(top_)builddir` can be set by `Makefile.am`
+//   calling the `a2x` tool, since some of the files with the asciidoc
+//   mark-up are only generated or post-processed during build and
+//   (due to `make dist` restrictions) being build products, they may
+//   not reside in same directory as static source text files which
+//   reference or include them. Note that the non-`top` paths would
+//   normally differ based on location of the `Makefile` involved
+//   (e.g. workspace root, or the `docs`, or `docs/man` directories).
+//   These variables are expected to be absolute paths, or ones relative
+//   to asciidoc-selected `:base_dir`, and to end with a relevant path
+//   separator, or be empty -- so in all cases letting the resulting
+//   string resolve meaningfully in the filesystem during docs build.
+//
+// Please keep the remaining comments and definitions as one big block
+// so it does not become a series of empty paragraphs in the rendered
+// documents!
+//
+ifndef::website-url[]
+:website-url:	https://www.networkupstools.org/
+endif::website-url[]
+//
+ifndef::srcdir[]
+:srcdir:
+endif::srcdir[]
+//
+ifndef::builddir[]
+:builddir:
+endif::builddir[]
+//
+ifndef::top_srcdir[]
+:top_srcdir:
+endif::top_srcdir[]
+//
+ifndef::top_builddir[]
+:top_builddir:
+endif::top_builddir[]
+//
+//
+// Address links on GitHub vs docs
+// (note: 'env-github' attribute is set on GitHub)
+//
+// - when generating docs:
+ifndef::env-github[]
+//   * xref -> xref
+//     syntax: {xref}<id>{x-s}[<caption>]
+//     -> xref:<id>[<caption>]
+:xref:		xref:
+:x-s:
+//   * link to doc -> our macro
+//     syntax: {linksrcdoc}<document>
+//     -> linksrcdoc:<document>[]
+:linksrcdoc:	linksrcdoc:
+//   * link to doc -> our macro
+//     syntax: {linkdoc}<document>{ld-s}[<display title>]
+//     -> linkdoc:<document>[<display title>]
+:linkdoc:	linkdoc:
+:ld-s:
+//   * link to single doc -> our macro
+//     syntax: {linksingledoc}<document>{lsd-s}[<display title>]
+//     -> linksingledoc:<document>[<display title>]
+:linksingledoc:	linksingledoc:
+:lsd-s:
+//   * link to manpage -> our macro
+//     syntax: {linkman2}<command-page>{lm-s}<displayed-command>{lm-c}<manpage-section>{lm-e}
+//     -> linkman2:<command-page>[<displayed-command>,<manpage-section>]
+:linkman2:	linkman2:
+:lm-s:		[
+:lm-c:		,
+:lm-e:		]
+endif::env-github[]
+//
+// - on GitHub:
+ifdef::env-github[]
+//     In our normal builds, Makefile variables convey the needed paths
+//     (used relatively below as `image:images/ci/...png` etc.)
+:imagesdir:	docs
+//   * xref -> link
+//     syntax: {xref}<id>{x-s}[<caption>]
+//     In order for it to work, <id> can reference at most a section of
+//     level docs/common.xsl's <chunk.section.depth>
+//     -> {website-url}docs/user-manual.chunked/<id>.html[<caption>]
+:xref:		{website-url}docs/user-manual.chunked/
+:x-s:		.html
+//   * link to doc -> our macro
+//     syntax: {linksrcdoc}<document>
+//     -> link:<document>[]
+:linksrcdoc:	link:{top_srcdir}/
+//   * link to doc -> link
+//     syntax: {linkdoc}<document>{ld-s}[<display title>]
+//     -> {website-url}docs/<document>.chunked/index.html[<display title>]
+:linkdoc:	{website-url}docs/
+:ld-s:		.chunked/index.html
+//   * link to single doc -> link
+//     syntax: {linksingledoc}<document>{lsd-s}[<display title>]
+//     -> {website-url}docs/<document>.html[<display title>]
+:linksingledoc:	{website-url}docs/
+:lsd-s:		.html
+//   * link to manpage -> link
+//     syntax: {linkman2}<command-page>{lm-s}<displayed-command>{lm-c}<manpage-section>{lm-e}
+//     All the fields are mandatory.
+//     -> {website-url}docs/man/<command-page>.html[<displayed-command>(<manpage-section>)]
+:linkman2:	{website-url}docs/man/
+:lm-s:		.html[
+:lm-c:		(
+:lm-e:		)]
+endif::env-github[]
+endif::asciidoc-vars-nut-included[]
+//
+//GH_MARKUP_1095_INCLUDE_END//
 
 This chapter describes the various methods for installing Network UPS Tools.
 
@@ -460,8 +630,9 @@ You can jump directly to the <<Configuration_notes,NUT configuration>>
 if you need to revise the settings for your new NUT version, take advantage
 of new configuration options, etc.
 
-Check the linkdoc:NEWS and linkdoc:UPGRADING[Upgrade Notes] files in your
-Git workspace to review features that should be present in your new build.
+Check the {linksrcdoc}NEWS.adoc[] and {linksrcdoc}UPGRADING.adoc[] files
+in your checked-out Git workspace to review features that should be present
+in your new build.
 
 [[Installing_packages]]
 Installing from packages

Makefile.am

@@ -206,11 +206,36 @@ INSTALL.nut UPGRADING NEWS README:
 # definitions), to apply them into the committed document sources.
 # Not bothering about with "make dist" constraints etc. - changes
 # the contents of srcdir directly and intentionally.
+# NOTE: There is a problem with `printf '%s' "${LINE}"` (double-quoted)
+# that causes backslashes to be treated as escape characters, and
+# shell replacements with `${VAR/pat/sub}` are not really portable.
+# To address this, we use the pure POSIX shell `replace_all()`
+# method suggested at https://stackoverflow.com/a/75037170/4715872
+# WARNING: It may succumb to lines ending with asterisk however!
+MAINTAINER_ASCIIDOCS_RECIPE_DEBUG_STREAM = /dev/null
+#MAINTAINER_ASCIIDOCS_RECIPE_DEBUG_STREAM = &2
+
 maintainer-asciidocs:
 	@USEDREV="`git log -1 --oneline --pretty=format:'%h (%cs) %s' docs/asciidoc-vars.conf`" || exit ; \
 	 USEDREV_NOSUBJ="`git log -1 --oneline --pretty=format:'%h (%cs)' docs/asciidoc-vars.conf`" || exit ; \
 	 echo "$@: Updating asciidoc text sources with docs/asciidoc-vars.conf as of commit: $${USEDREV}"; \
 	 echo "//GH_MARKUP_1095_INCLUDE_BEGIN//$${USEDREV}" > docs/asciidoc-vars.conf.lastrev.tmp || exit ; \
+	 replace_all() { \
+	   case "$$1" in *"$$2"*) ;; *) echo "$$1" ; return ;; esac ; \
+	   RIGHT="$$1" ; R=''; \
+	   while [ -n "$$RIGHT" ]; do \
+	    echo "LEFT='$$LEFT' RIGHT='$$RIGHT' => R='$$R'" >$(MAINTAINER_ASCIIDOCS_RECIPE_DEBUG_STREAM) ; \
+	    LEFT="$${RIGHT%%$$2*}" ; \
+	    echo "=> LEFT='$$LEFT'" >$(MAINTAINER_ASCIIDOCS_RECIPE_DEBUG_STREAM) ; \
+	    if [ x"$$LEFT" = x"$$RIGHT" ]; then \
+	        R="$$R$$RIGHT" ; \
+	        return ; \
+	    fi ; \
+	    R="$$R$$LEFT$$3" ; \
+	    RIGHT="$${RIGHT#*$$2}" ; \
+	  done ; \
+	  echo "$$R" ; \
+	 } ; \
 	 find . -name '*.adoc' -or -name '*.txt' | ( \
 	  FILES=""; \
 	  while read F ; do \
@@ -223,7 +248,7 @@ maintainer-asciidocs:
 	            "//GH_MARKUP_1095_INCLUDE_BEGIN"*) EXT="2.tmp" ; continue ;; \
 	            "//GH_MARKUP_1095_INCLUDE_END"*|"////GH_MARKUP_1095_INCLUDE_END"*) EXT="3.tmp" ; continue ;; \
 	        esac ; \
-	        printf '%s\n' "$${LINE}" >> "$${F}.$${EXT}" || exit ; \
+	        printf '%s\n' "`replace_all "$${LINE}" '\\' '''\\'`" >> "$${F}.$${EXT}" || exit ; \
 	    done < "$$F" || { echo "$@: FAILED injection for $${F}" >&2; exit 1; } ; \
 	    if test -s "$${F}.2.tmp" && test -z "`diff "$${F}.2.tmp" docs/asciidoc-vars.conf | tr -d '\n'`" ; then \
 	        rm -f "$${F}"*.tmp ; \

README.adoc

@@ -7,7 +7,7 @@ Network UPS Tools Overview
 //GH_MARKUP_1095//ifndef::top_srcdir[]
 //GH_MARKUP_1095//include::docs/asciidoc-vars.conf[]
 //GH_MARKUP_1095//endif::top_srcdir[]
-//GH_MARKUP_1095_INCLUDE_BEGIN//7c5e90132 (2023-09-13) docs/asciidoc-vars.conf: fence against re-definitions of website-url and (top_)(src|build)dir attributes
+//GH_MARKUP_1095_INCLUDE_BEGIN//7e01bd198 (2024-10-20) docs/asciidoc-vars.conf: try defining linksrcdoc macro
 ifndef::asciidoc-vars-nut-included[]
 :asciidoc-vars-nut-included:	true
 // NOTE: The big block of comments and definitions below comes from
@@ -39,6 +39,8 @@ ifndef::asciidoc-vars-nut-included[]
 // with shortened names). For our classic documentation renditions, they
 // should resolve to properly defined macros from `docs/asciidoc.conf`
 // (usually named same as the variables defined here, for simplicity):
+// * `linksrcdoc` allows to refer to a source of documentation file
+//   relative to the root of NUT code base.
 // * `linkdoc` allows to refer to a file under `docs/` directory (or
 //   its nut-website rendition).
 // * `xref` substitutes the asciidoc shorthand '<< >>' syntax with
@@ -108,6 +110,10 @@ ifndef::env-github[]
 :xref:		xref:
 :x-s:
 //   * link to doc -> our macro
+//     syntax: {linksrcdoc}<document>
+//     -> linksrcdoc:<document>[]
+:linksrcdoc:	linksrcdoc:
+//   * link to doc -> our macro
 //     syntax: {linkdoc}<document>{ld-s}[<display title>]
 //     -> linkdoc:<document>[<display title>]
 :linkdoc:	linkdoc:
@@ -138,6 +144,10 @@ ifdef::env-github[]
 //     -> {website-url}docs/user-manual.chunked/<id>.html[<caption>]
 :xref:		{website-url}docs/user-manual.chunked/
 :x-s:		.html
+//   * link to doc -> our macro
+//     syntax: {linksrcdoc}<document>
+//     -> link:<document>[]
+:linksrcdoc:	link:{top_srcdir}/
 //   * link to doc -> link
 //     syntax: {linkdoc}<document>{ld-s}[<display title>]
 //     -> {website-url}docs/<document>.chunked/index.html[<display title>]

docs/Makefile.am

@@ -70,6 +70,7 @@ IMAGE_LOGO_FILES = \
 	images/ci/OC_logo_merged_140x26.png
 
 IMAGE_LOGO_FILES_JENKINS_NUT = \
+	images/ci/ci-root.css \
 	images/ci/jenkins-nut-large-256px.png \
 	images/ci/jenkins-nut-large-squared.png \
 	images/ci/jenkins-nut-large.pdn \

docs/acknowledgements.txt

@@ -8,8 +8,14 @@ This project is the result of years of work by many individuals and companies.
 Many people have written or tweaked the software; the drivers, clients, server
 and documentation have all received valuable attention from numerous sources.
 
-Many of them are listed within the source code, AUTHORS file, release notes,
-and mailing list archives, but some prefer to be anonymous.
+Many of them are listed within the source code, linksrcdoc:AUTHORS[] file,
+release notes, and mailing list archives, but some prefer to be anonymous.
+
+Companies and organizations that have helped with various aspects of project
+infrastructure are listed in linksingledoc:user-manual[Acknowledgements of
+organizations which help with NUT CI and other daily
+operations,acknowledgements-ci-ops,README.adoc].
+
 This software would not be possible without their help.
 
 

docs/asciidoc-vars.conf

@@ -29,6 +29,8 @@ ifndef::asciidoc-vars-nut-included[]
 // with shortened names). For our classic documentation renditions, they
 // should resolve to properly defined macros from `docs/asciidoc.conf`
 // (usually named same as the variables defined here, for simplicity):
+// * `linksrcdoc` allows to refer to a source of documentation file
+//   relative to the root of NUT code base.
 // * `linkdoc` allows to refer to a file under `docs/` directory (or
 //   its nut-website rendition).
 // * `xref` substitutes the asciidoc shorthand '<< >>' syntax with
@@ -98,6 +100,10 @@ ifndef::env-github[]
 :xref:		xref:
 :x-s:
 //   * link to doc -> our macro
+//     syntax: {linksrcdoc}<document>
+//     -> linksrcdoc:<document>[]
+:linksrcdoc:	linksrcdoc:
+//   * link to doc -> our macro
 //     syntax: {linkdoc}<document>{ld-s}[<display title>]
 //     -> linkdoc:<document>[<display title>]
 :linkdoc:	linkdoc:
@@ -128,6 +134,10 @@ ifdef::env-github[]
 //     -> {website-url}docs/user-manual.chunked/<id>.html[<caption>]
 :xref:		{website-url}docs/user-manual.chunked/
 :x-s:		.html
+//   * link to doc -> our macro
+//     syntax: {linksrcdoc}<document>
+//     -> link:<document>[]
+:linksrcdoc:	link:{top_srcdir}/
 //   * link to doc -> link
 //     syntax: {linkdoc}<document>{ld-s}[<display title>]
 //     -> {website-url}docs/<document>.chunked/index.html[<display title>]