summaryrefslogtreecommitdiff
path: root/cli/doc/buildfile
blob: 753b62063053a0dae196b681ed73a84d900ed4e8 (plain)
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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
# file      : doc/buildfile
# license   : MIT; see accompanying LICENSE file

define css: doc
css{*}: extension = css

define xhtml: doc
xhtml{*}: extension = xhtml

define ps: doc
ps{*}: extension = ps

define pdf: doc
pdf{*}: extension = pdf

define html2ps: file
html2ps{*}: extension = html2ps

./: css{default} xhtml{cli-guide}

# Man pages.
#

## Consumption build ($develop == false).
#

# Use pregenerated versions in the consumption build.
#
./: pregenerated/{man1 xhtml}{*}: include = (!$develop)

# Distribute pregenerated versions only in the consumption build.
#
pregenerated/{man1 xhtml}{*}: dist = (!$develop)

#
##

## Development build ($develop == true).
#

./: {man1 xhtml}{cli}: include = $develop

if $develop
{
  doc_version = [string] "$version.major.$version.minor.$version.patch"
  if $version.pre_release
    doc_version += "-$version.pre_release_string"

  # Let's take the last four-digit number to cover 2000-2021,2022.
  #
  doc_year = $regex.replace($copyright, '.+[-, ]([0-9][0-9][0-9][0-9]) .+', '\1')

  man_options = -v project="CLI" -v version="$doc_version" \
                -v copyright="$copyright" --suppress-undocumented

  # We use the cli version we've built to generate the documentation.
  #
  include ../cli/
}

# Note: avoid cleaning exe{cli} through this dependency.
#
{man1 xhtml}{cli}: ../cli/exe{cli}: clean = false

# In the development build distribute regenerated versions, remapping their
# locations to the paths of the pregenerated versions (which are only
# distributed in the consumption build; see above). This way we make sure that
# the distributed files are always up-to-date.
#
{man1 xhtml}{cli}: dist = ($develop ? pregenerated/ : false)

man1{cli}: ../cli/cli{options} file{cli-prologue.1 cli-epilogue.1}
%
if $develop
{{
  diag 'cli --man' ($<[1]) -> $>

  # Use the copyright year to approximate the last authoring date.
  #
  ($<[0]) --generate-man $man_options      \
          -v date="January $doc_year"      \
          --man-prologue-file $path($<[2]) \
          --man-epilogue-file $path($<[3]) \
          --stdout $path($<[1]) >$path($>)

  # If the result differs from the pregenerated version, copy it over. Unlike
  # the bootstrap compiler case, here we don't need to cause a build restart
  # (since nothing depends on it).
  #
  if! diff $src_base/pregenerated/cli.1 $path($>) >-
    cp $path($>) $src_base/pregenerated/cli.1
  end
}}

xhtml{cli}: ../cli/cli{options} file{cli-prologue.xhtml cli-epilogue.xhtml}
%
if $develop
{{
  diag 'cli --html' ($<[1]) -> $>

  ($<[0]) --generate-html $man_options      \
          --html-prologue-file $path($<[2]) \
          --html-epilogue-file $path($<[3]) \
          --stdout $path($<[1]) >$path($>)

  if! diff $src_base/pregenerated/cli.xhtml $path($>) >-
    cp $path($>) $src_base/pregenerated/cli.xhtml
  end
}}

#
##

# Manual.
#
# This case is slightly more involved because we make the generation of the
# manual's ps/pdf optional and also don't keep the result in the repository.
# Specifically:
#
# 1. In the consumption build we will install/redistribute ps/pdf if present.
#
# 2. In the development build we will generate ps/pdf if we are able to import
#    the needed tools, issuing a warning otherwise.

## Consumption build ($develop == false).
#

# Use pregenerated versions, if exist, in the consumption build.
#
./: pregenerated/{ps pdf}{*}: include = (!$develop)

# Distribute pregenerated versions only in the consumption build.
#
pregenerated/{ps pdf}{*}: dist = (!$develop)

#
##

## Development build ($develop == true).
#

html2pdf = false

if $develop
{
  # Import the html2ps and ps2pdf programs from the system, if available.
  #
  import? html2ps = html2ps%exe{html2ps}
  import? ps2pdf  = ps2pdf14%exe{ps2pdf14}

  html2pdf = ($html2ps != [null] && $ps2pdf != [null])

  if! $html2pdf
    warn "html2ps and/or ps2pdf14 are not available, not generating .ps and .pdf documentation"
}

./: {ps pdf}{cli-guide}: include = $html2pdf

# In the development build distribute regenerated versions, remapping their
# locations to the paths of the pregenerated versions (which are only
# distributed in the consumption build; see above). This way we make sure that
# the distributed files are always up-to-date.
#
{ps pdf}{cli-guide}: dist = ($html2pdf ? pregenerated/ : false)

# Note: the pregenerated files may not exist, thus --no-cleanup option is
# required for the cp builtin call. Strictly speaking we don't really need
# to copy them since they are not stored in the repository, but let's do
# that for consistency with the distributed source tree.
#
# @@ TMP Note that cli-guide.xhtml and guide.html2ps still have copyright
#        years hard-coded.
#
ps{cli-guide}: xhtml{cli-guide} html2ps{guide} $html2ps
%
if $html2pdf
{{
  options =

  diag html2ps ($<[0]) -> $>
  $html2ps $options -f $path($<[1]) -o $path($>) $path($<[0])

  cp --no-cleanup $path($>) $src_base/pregenerated/cli-guide.ps
}}

pdf{cli-guide}: ps{cli-guide} $ps2pdf
%
if $html2pdf
{{
  options = -dOptimize=true -dEmbedAllFonts=true

  diag ps2pdf ($<[0]) -> $>
  $ps2pdf $options $path($<[0]) $path($>)

  cp --no-cleanup $path($>) $src_base/pregenerated/cli-guide.pdf
}}

#
##