aboutsummaryrefslogtreecommitdiff
path: root/doc/buildfile
blob: 88f30fc676a25ed0dc99a0557dbc655ceda2bf81 (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
# file      : doc/buildfile
# license   : GNU GPL v3; 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{manual} doc{*.png} file{*.svg}

# 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}{odb}: 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="ODB" -v version="$doc_version" \
                -v copyright="$copyright" --suppress-undocumented

  import! [metadata] cli = cli%exe{cli}
}

# 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}{odb}: dist = ($develop ? pregenerated/ : false)

# @@ TMP Note that the project, version, and date variables we are passing to
#        cli are currently unused since the respective values are hard-coded
#        in the odb-prologue.* files.
#
man1{odb}: ../odb/cli{options} file{odb-prologue.1 odb-epilogue.1} $cli
%
if $develop
{{
  # Use the copyright year to approximate the last authoring date.
  #
  $cli --generate-man $man_options      \
       -v date="January $doc_year"      \
       --man-prologue-file $path($<[1]) \
       --man-epilogue-file $path($<[2]) \
       --stdout $path($<[0]) >$path($>)

  # If the result differs from the pregenerated version, copy it over.
  #
  if! diff $src_base/pregenerated/odb.1 $path($>) >-
    cp $path($>) $src_base/pregenerated/odb.1
  end
}}

xhtml{odb}: ../odb/cli{options} file{odb-prologue.xhtml odb-epilogue.xhtml} $cli
%
if $develop
{{
  $cli --generate-html $man_options      \
       --html-prologue-file $path($<[1]) \
       --html-epilogue-file $path($<[2]) \
       --stdout $path($<[0]) >$path($>)

  if! diff $src_base/pregenerated/odb.xhtml $path($>) >-
    cp $path($>) $src_base/pregenerated/odb.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}{odb-manual}: 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}{odb-manual}: dist = ($html2pdf ? pregenerated/ : false)

# Note: the pregenerated file 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 manual.{xhtml,html2ps} still have copyright years, ODB
#        version, document revision/date, etc hard-coded.
#
ps{odb-manual}: {xhtml html2ps}{manual} $html2ps
%
if $html2pdf
{{
  options =

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

  cp --no-cleanup $path($>) $src_base/pregenerated/odb-manual.ps
}}

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

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

  cp --no-cleanup $path($>) $src_base/pregenerated/odb-manual.pdf
}}

#
##