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.
// * `linkmanext` and `linkmanext2` macros repeat the behavior of the default ones.
//   These macros are intended for system man pages (e.g. HTML links might lead
//   to a generic internet site, or possibly to a distro-provided library
//   online or locally).
//
// 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 (optional 2/3/4 args)
//     syntax: {linkdoc}<document>{ld-s}[<display title>{,<anchor>{,<srcdoc>{,<chunkname>}}}]
//     -> linkdoc:<document>[<display title>{,<anchor>{,<srcdoc>{,<chunkname>}}}]
: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:		]
:linkmanext:	https://www.die.net/search/?q=
:linkmanext2:	https://www.die.net/search/?q=
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 (FIXME: ignore or use 2/3/4 args; currently they are all pasted as <display title> contents!)
//     syntax: {linkdoc}<document>{ld-s}[<display title>{,<anchor>{,<srcdoc>{,<chunkname>}}}]
//     -> {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:		)]
:linkmanext:	https://www.die.net/search/?q=
:linkmanext2:	https://www.die.net/search/?q=
endif::env-github[]
endif::asciidoc-vars-nut-included[]
//
