forked from networkupstools/nut
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathasciidoc-vars.conf
151 lines (151 loc) · 6.37 KB
/
asciidoc-vars.conf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
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):
// * `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: {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 -> 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[]
//