## NUT macros: linkman, linkman2, linkdoc, linksingledoc
#
# Usage: linkman:command[manpage-section]
#   This macro allows to handle variable manpage location, depending on the
#   document type
# Usage: linkman2:command-page[displayed-command,manpage-section]
#   Just like linkman macro, but supports different names for the page and the
#   command shown.
#
# Note:
# - in linkman, {0} is the manpage section, while {target} is the command.
# - in linkman2, {0} is the whole list of attributes, {1} is the command to be
#   shown, {2} is the manpage section, while {target} is the command page.
# - 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).
#
# Example:
#   linkman:ups.conf[5]
#   linkman2:ups_conf[ups.conf,5]
#   linkmanext:chroot[2]
#
# Show NUT link as: <command>(<section>); if section is defined, else just show
#   the command.
#
################################################################################
#
# Usage: linksrcdoc:document[]
#   Mark-up a reference to a document source file in NUT code base;
#   NOTE: its "document" path is assumed to be relative to source root!
# Usage: suggestsrcdoc:document[]
#   This macro allows to recommend a document in NUT source code base
#   to consult the most up-to-date version of a quickly evolving text.
#   It wraps the above into a prepared message, to name the source file
#   as an "up-to-date" alternative to a link generated by other macros.
#
# Usage: linkdoc:document[display title[,anchor[,source path[,chunk name]]]]
#   This macro allows to handle variable NUT documentation location, depending
#   on the document type. NOTE: its "document" path is assumed to be relative to
#   the rendered (HTML, PDF) document location; adding "../" for chunked HTML.
# Usage: linksingledoc:document[display title[,anchor[,source path]]]
#   Just like linkdoc macro, but, when chunked HTML is generated, this one always
#   points to a non-chunked file
#
# Note, {1} is the display title, {2} is the optional anchor name,
#   {3} is an optional path to source document in NUT code base
#   (recommended for parts of documentation which expect significant
#   change over time, so a reference can be provided to current text),
#   {4} is an optional name of the HTML Chunk (typically anchor name in the
#   root document text file, e.g. "[[Overview]]" section of "user-manual.txt"),
#   (ignored in non-chunked formats),
#   {0} is the whole set of args ({1}...{n}) and {target} is the
#   base document name.
# Example:
#   linkdoc:user-manual[user manual,NUT_Security]
#   linkdoc:qa-guide[Prerequisites for building NUT on different OSes,NUT_Config_Prereqs,docs/config-prereqs.txt]
#   linkdoc:developer-guide[developer guide,_status_data]
#   linksingledoc:FAQ[shopping tips,_which_ups_should_i_buy]

[macros]
# From asciidoc-py docs at https://asciidoc-py.github.io/chunked/ch21.html :
#    <pattern>=<name>[<subslist]
#      Inline macro definition.
#    <pattern>=#<name>[<subslist]
#      Block macro definition.
#    <pattern>=+<name>[<subslist]
#      System macro definition.
#    <pattern>
#      Delete the existing macro with this <pattern>.
# * <pattern> is a Python regular expression and <name> is the name of
#   a markup template.
# * If <name> is omitted then it is the value of the regular expression
#   match group named "name".
# * The optional [<subslist] is a comma-separated list of substitution
#   names enclosed in [] brackets, it sets the default substitutions
#   for passthrough text, if omitted then no passthrough substitutions
#   are performed.
(?su)[\\]?(?P<name>linkman):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
(?su)[\\]?(?P<name>linkman2):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
(?su)[\\]?(?P<name>linkmanext):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
(?su)[\\]?(?P<name>linkmanext2):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
(?su)[\\]?(?P<name>linkdoc):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
(?su)[\\]?(?P<name>linksingledoc):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
(?su)[\\]?(?P<name>suggestsrcdoc):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
# FIXME: find a way to use "link:" or xref, at least for GitHub renders.
(?su)[\\]?(?P<name>linksrcdoc):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=

ifdef::basebackend-docbook[]
# AsciiDoc <= ~8.6.9 tests the wrong attribute and, as a consequence
# of that, it produces both <link> and <xref>.
# To workaround this issue, implement the xref macro by ourselves.
[xref-inlinemacro]
<link linkend="{target}">{0}</link>
{0%}<xref linkend="{target}"/>

[suggestsrcdoc-inlinemacro]
 (or linksrcdoc:{target}[] in NUT sources for up-to-date information)

ifdef::xhtml11_format[]
[linkman-inlinemacro]
<ulink url="man/{target}.html">{target}{0?({0})}</ulink>
[linkman2-inlinemacro]
<ulink url="man/{target}.html">{1={target}}{2?({2})}</ulink>
# FIXME: Allow to define external man page URL structure and whether
#  sections should change via configure script options:
[linkmanext-inlinemacro]
<ulink url="https://linux.die.net/man/{0}/{target}">{target}{0?({0})}</ulink>
[linkmanext2-inlinemacro]
<ulink url="https://linux.die.net/man/{2}/{target}">{1={target}}{2?({2})}</ulink>
[linkdoc-inlinemacro]
<ulink url="{target}.html{2?#{2}}">{1}</ulink>{3?suggestsrcdoc:{3}[]}
[linksingledoc-inlinemacro]
<ulink url="{target}.html{2?#{2}}">{1}</ulink>{3?suggestsrcdoc:{3}[]}
[linksrcdoc-inlinemacro]
<code>{target}</code>
endif::xhtml11_format[]

# NOTE: linkdoc does not support 'anchor' if generating with classic
# asciidoc numbered chapters, but it is not a problem when the anchor
# value becomes the file name (allowing for persistent links unless
# the chapter is renamed - but surviving reshuffled ordering)
ifdef::chunked_format[]
[linkman-inlinemacro]
<ulink url="../man/{target}.html">{target}{0?({0})}</ulink>
[linkman2-inlinemacro]
<ulink url="../man/{target}.html">{1={target}}{2?({2})}</ulink>
# FIXME: Allow to define external man page URL structure and whether
#  sections should change via configure script options:
[linkmanext-inlinemacro]
<ulink url="https://linux.die.net/man/{0}/{target}">{target}{0?({0})}</ulink>
[linkmanext2-inlinemacro]
<ulink url="https://linux.die.net/man/{2}/{target}">{1={target}}{2?({2})}</ulink>
[linkdoc-inlinemacro]
<ulink url="../{target}.chunked/{4=index}.html{2?#{2}}">{1}</ulink>{3?suggestsrcdoc:{3}[]}
[linksingledoc-inlinemacro]
<ulink url="../{target}.html{2?#{2}}">{1}</ulink>{3?suggestsrcdoc:{3}[]}
[linksrcdoc-inlinemacro]
<code>{target}</code>
endif::chunked_format[]

# PDF output points online versions
ifdef::pdf_format[]
[linkman-inlinemacro]
<ulink url="https://www.networkupstools.org/docs/man/{target}.html">{target}{0?({0})}</ulink>
[linkman2-inlinemacro]
<ulink url="https://www.networkupstools.org/docs/man/{target}.html">{1={target}}{2?({2})}</ulink>
# FIXME: Allow to define external man page URL structure and whether
#  sections should change via configure script options:
[linkmanext-inlinemacro]
<ulink url="https://linux.die.net/man/{0}/{target}">{target}{0?({0})}</ulink>
[linkmanext2-inlinemacro]
<ulink url="https://linux.die.net/man/{2}/{target}">{1={target}}{2?({2})}</ulink>
[linkdoc-inlinemacro]
<ulink url="{target}.pdf{2?#{2}}">{1}</ulink>{3?suggestsrcdoc:{3}[]}
[linksingledoc-inlinemacro]
<ulink url="{target}.pdf{2?#{2}}">{1}</ulink>{3?suggestsrcdoc:{3}[]}
[linksrcdoc-inlinemacro]
<code>{target}</code>
endif::pdf_format[]
endif::basebackend-docbook[]
