Project

Profile

Help

How to connect?
Download (19.5 KB) Statistics
| Branch: | Tag: | Revision:

he / tags / 9.7.0.1 / build / documentation.xml @ 02f8308b

1
<?xml version="1.0" encoding="UTF-8"?>
2

    
3
<project basedir="." default="all" name="Documentation"
4
    xmlns:dn="antlib:org.apache.ant.dotnet" xmlns:if="ant:if" xmlns:unless="ant:unless">
5

    
6
    <!-- note : Ant 1.9.1 is needed for this script -->
7

    
8
    <!-- Ant 1.9.1 supports the use of @ant:if and @ant:unless conditional attributes
9
         which are used for alternatives, currently in ICU building and documentation generation -->
10

    
11
    <!-- The use of ant:if and ant:unless requires Ant 1.9.1 -
12
        for IntelliJ the built-in is 1.8.2, but an external Ant can be configured on the Ant menu  -->
13

    
14
    <!-- note : Ant 1.7 is needed for this script -->
15

    
16
    <!-- Ant 1.7 introduces a <service> element to allow META-INF/services
17
         directories to be created in JAR files. Unfortunately it is broken,
18
         see http://issues.apache.org/bugzilla/show_bug.cgi?id=41201. The relevant
19
         code here is retained in the form of comments, and can be reinstated
20
         when the bug is fixed. Meanwhile the directories are created manually -->
21

    
22
    <!-- Build file for Saxon documentation. -->
23

    
24
    <import file="build-constants.xml"/>
25

    
26
    <!-- Location of userdoc source -->
27
    <property name="userdoc.uri" value="${repository.uri}/userdoc"
28
              description="Userdoc directory in development repository"/>
29

    
30
    <!-- Location of viewer_app output directory -  development userdoc directory -->
31
    <property name="viewer_app.dir" value="${repository.uri}/userdoc/saxon9/viewer_app"
32
              description="Viewer app built in userdoc directory in development repository"/>
33

    
34

    
35
    <!-- Full URI for viewer_app output directory (supplied to stylesheets as parameter) -->
36
    <property name="viewer_app.full-uri" value="${viewer_app.dir}"
37
              description="Full URI for viewer app in userdoc directory in development repository"/>
38

    
39
    <!-- Location of Feature Keys Tools directory -->
40
    <property name="featureKeys.dir" value="${repository}/tools/featureKeys"
41
              description="Feature Keys directory in development repository"/>
42

    
43

    
44
    <!-- Saxon used for some late-stage operations, notably documentation generation -->
45
    <property name="use.EE" value="true" description="Use -EE for documentation, otherwise PE"/>
46
    <property if:true="${use.EE}" name="saxon.edition" value="Enterprise"
47
        description="Enterprise Saxon"/>
48
    <property unless:true="${use.EE}" name="saxon.edition" value="Professional"
49
        description="Professional Saxon"/>
50

    
51

    
52
    <path id="saxon.class.path">
53
        <fileset if:true="${use.EE}" dir="${product.dir}/eej">
54
            <include name="*.jar"/>
55
        </fileset>
56
        <fileset unless:true="${use.EE}" dir="${product.dir}/pej">
57
            <include name="*.jar"/>
58
        </fileset>
59
        <!-- <pathelement path="${lib.dir}"/>-->
60
        <!--<pathelement path="${product.dir}/eej"/>-->
61
    </path>
62

    
63
    <path id="saxonee.class.path">
64
        <!-- <pathelement path="${lib.dir}"/>-->
65
        <pathelement path="${product.dir}/eej"/>
66
    </path>
67

    
68

    
69

    
70
    <!-- Documentation generation -->
71

    
72
    <macrodef name="EXPath-doc"
73
        description="Expand EXPath functional documentation. This links to GitHub">
74
        <attribute name="target"/>
75
        <sequential>
76
            <xslt in="${userdoc.uri}/saxon9/src/functions/EXPath/functions-@{target}.xml"
77
                out="${userdoc.uri}/saxon9/src/functions/EXPath/functions-@{target}-expanded.xml"
78
                style="${userdoc.uri}/saxon9/style/genFunctionDoc.xsl" classpathref="saxon.class.path">
79
                <param name="GitHub" expression="${GitHub.dir}"/>
80
                <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
81
                    <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
82
                        value="${saxon.license}"/>
83
                    <attribute name="http://saxon.sf.net/feature/xinclude-aware" value="true"/>
84
                    <!-- Bug 2126 may require byte code suppression - remove this when fixed -->
85
                    <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
86
                </factory>
87
            </xslt>
88
        </sequential>
89
    </macrodef>
90

    
91
    <macrodef name="Element-doc"
92
              description="Expand XSLT Element Reference and Extensions documentation">
93
        <attribute name="target"/>
94
        <sequential>
95
            <xslt in="${userdoc.uri}/saxon9/src/extensions/@{target}-src.xml"
96
                  out="${userdoc.uri}/saxon9/src/extensions/@{target}-expanded.xml"
97
                  style="${userdoc.uri}/saxon9/style/elements-body.xsl" classpathref="saxon.class.path">
98
                <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
99
                    <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
100
                               value="${saxon.license}"/>
101
                    <!-- Bug 2126 may require byte code suppression - remove this when fixed -->
102
                    <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
103
                </factory>
104
            </xslt>
105
        </sequential>
106
    </macrodef>
107

    
108
    <target name="gen-doc"
109
        description="Collects up, generates and copies the documentation source into the canonical location">
110
        <!--<diagnostics/>-->
111
        <echo message="Using Saxon ${saxon.edition} Edition"/>
112
        <echo message="License file: ${saxon.license}"/>
113
        <echo message="userdoc.uri is: ${userdoc.uri}"/>
114
        <echo message="Using output parameter ${viewer_app.full-uri}"/>
115

    
116
        <!-- Generate the ICU/UCA documentation which involves self-inspection extension functions -->
117
        <xslt in="${userdoc.uri}/saxon9/src/catalog.xml" out="${userdoc.uri}/saxon9/src/extensibility/temp.xml"
118
            style="${userdoc.uri}/saxon9/style/document-ICU.xsl" classpathref="saxon.class.path">
119
            <param name="output" expression="extensibility/catalog.xml"/>
120
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
121
                <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
122
                    value="${saxon.license}"/>
123
                <attribute name="http://saxon.sf.net/feature/initialTemplate" value="go"/>
124
                <!--<attribute if:true="${use.EE}" name="http://saxon.sf.net/feature/trace-external-functions" value="true"/>-->
125
                <!-- Bug 2126 may require byte code suppression - remove this when fixed -->
126
                <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
127
                <attribute name="http://saxon.sf.net/feature/xsltVersion" value="3.0"/>
128
            </factory>
129
        </xslt>
130

    
131
        <!-- Generate the XSLT Element reference documentation -->
132
        <xslt in="${userdoc.uri}/saxon9/src/elements/xsl-elements-src.xml" out="${userdoc.uri}/saxon9/src/elements/xsl-elements-expanded.xml"
133
              style="${userdoc.uri}/saxon9/style/genElementDoc.xsl" classpathref="saxon.class.path">
134
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
135
                <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
136
                           value="${saxon.license}"/>
137
                <!-- Bug 2126 may require byte code suppression - remove this when fixed -->
138
                <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
139
            </factory>
140
        </xslt>
141

    
142
        <xslt in="${userdoc.uri}/saxon9/src/elements/xsl-elements-expanded.xml" out="${userdoc.uri}/saxon9/src/xsl-elements.xml"
143
              style="${userdoc.uri}/saxon9/style/elements-body.xsl" classpathref="saxon.class.path">
144
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
145
                <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
146
                           value="${saxon.license}"/>
147
                <!-- Bug 2126 may require byte code suppression - remove this when fixed -->
148
                <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
149
            </factory>
150
        </xslt>
151

    
152
        <!-- Generate the Extensions documentation: instructions, serialization parameters, Saxon SQL Extension -->
153
        <Element-doc target="instructions"/>
154
        <Element-doc target="serialization-params"/>
155
        <Element-doc target="sql-extension"/>
156
        <copy file="${userdoc.uri}/saxon9/src/extensions/sql-extension-expanded.xml"
157
                tofile="${userdoc.uri}/saxon9/src/sql-extension.xml">
158
        </copy>
159

    
160
        <!-- Expand the EXPath documentation -->
161
        <EXPath-doc target="binary"/>
162
        <EXPath-doc target="archive"/>
163
        <EXPath-doc target="file"/>
164
        <!-- Generate feature keys documentation, to be included in the Configuration section (configuration.xml) -->
165
        <xslt in="${featureKeys.dir}/FeatureKeys.xml" out="${userdoc.uri}/saxon9/src/featureKeys/FeatureKeysDoc.xml"
166
              style="${featureKeys.dir}/FeatureKeysToDoc.xsl" classpathref="saxon.class.path">
167
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
168
                <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
169
                           value="${saxon.license}"/>
170
                <!-- Bug 2126 may require byte code suppression - remove this when fixed -->
171
                <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
172
            </factory>
173
        </xslt>
174

    
175
        <!-- Generate configuration file documentation (one result document per configuration file element,
176
        containing a table of its attributes/child elements), to be included in the Configuration section (configuration.xml) -->
177
        <xslt in="${featureKeys.dir}/AdditionalFeatures.xml" out="${userdoc.uri}/saxon9/src/featureKeys/ConfigFileDoc.xml"
178
              style="${featureKeys.dir}/ToConfigFileDoc.xsl" classpathref="saxon.class.path">
179
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
180
                <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
181
                           value="${saxon.license}"/>
182
                <!-- Bug 2126 may require byte code suppression - remove this when fixed -->
183
                <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
184
            </factory>
185
        </xslt>
186

    
187

    
188
        <!-- Expand the documentation sections from inclusions.
189
        2014-11-12 param 'output-uri' now replaces param 'output', to supply full uri of output location
190
        (the stylesheet has been updated: there is no longer any resolving of the output uri).
191
    Note that the 'output' parameter is important - this stylesheet produces result documents
192
    which Ant DOES NOT automatically place relative to the 'out' location - that appears to be a pipe
193
    outside XSLT.
194
     Also note of course that the main catalog.xml file is 'touched' to make sure that a re-run will be forced -->
195

    
196
        <xslt in="${userdoc.uri}/saxon9/src/catalog.xml" out="${viewer_app.dir}/doc/catalog.xml"
197
            style="${userdoc.uri}/saxon9/style/doc-include.xsl" classpathref="saxon.class.path">
198
            <!--<param name="output" expression="${viewer_app.full-uri}/doc/catalog.xml"/>-->
199
            <param name="output-uri" expression="${viewer_app.full-uri}/doc"/>
200
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
201
                <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
202
                    value="${saxon.license}"/>
203
                <attribute name="http://saxon.sf.net/feature/xinclude-aware" value="true"/>
204
                <!-- Bug 2126 may require byte code suppression - remove this when fixed -->
205
                <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
206
            </factory>
207
        </xslt>
208

    
209
        <!-- This touch ensures that gen-doc will run again on a subsequent invocation
210
            even if the catalog itself hasn't been modified, which is the normal case.
211
            It's the resources that it points to that are much more likely to change -->
212
        <touch file="${userdoc.uri}/saxon9/src/catalog.xml"/>
213

    
214
    </target>
215

    
216

    
217
    <!-- Generate static HTML version of user documentation -->
218

    
219
    <target name="userdoc-html"
220
        description="Creates the static HTML version of the user documentation" depends="gen-doc">
221
        <echo message="Using Saxon ${saxon.edition} Edition"/>
222
        <echo message="License file: ${saxon.license}"/>
223

    
224
        <!-- Preprocess the changes.xml file to turn it into a standard article -->
225

    
226
        <xslt in="${viewer_app.dir}/doc/changes.xml"
227
            out="${viewer_app.dir}/doc/changes-article.xml"
228
            style="${userdoc.uri}/saxon9/to-static/c-changes.xsl">
229
            <classpath refid="saxon.class.path"/>
230

    
231
            <factory name="com.saxonica.config.EnterpriseTransformerFactory"/>
232

    
233
        </xslt>
234

    
235
        <!-- Preprocess the functions.xml file to turn it into a standard article -->
236

    
237
        <xslt in="${viewer_app.dir}/doc/functions.xml"
238
            out="${viewer_app.dir}/doc/functions-article.xml"
239
            style="${userdoc.uri}/saxon9/to-static/c-functions.xsl"  >
240
            <classpath refid="saxon.class.path"/>
241

    
242
            <factory name="com.saxonica.config.EnterpriseTransformerFactory"/>
243

    
244
        </xslt>
245

    
246
        <!-- Now process all the articles -->
247

    
248
       <xslt in="${viewer_app.dir}/doc/catalog.xml" out="${viewer_app.dir}/dummy.xml"
249
            style="${userdoc.uri}/saxon9/to-static/s-cetree.xsl" >
250
            <classpath refid="saxon.class.path"/>
251

    
252
            <factory name="com.saxonica.config.EnterpriseTransformerFactory"/>
253
            <param name="changes-article" expression="${viewer_app.full-uri}/doc/changes-article.xml"/>
254
            <param name="functions-article" expression="${viewer_app.full-uri}/doc/functions-article.xml"/>
255
            <param name="base-uri" expression="${viewer_app.full-uri}/html/documentation"/>
256
        </xslt>
257

    
258
        <!-- Copy other important resources -->
259

    
260
        <copy file="${viewer_app.dir}/cetree.css" tofile="${viewer_app.dir}/html/documentation/cetree.css"/>
261
        <copy file="${viewer_app.dir}/cetree.css" tofile="${viewer_app.dir}/html/documentation/cetree.css"/>
262
        <copy todir="${viewer_app.dir}/html/documentation/image">
263
            <fileset dir="${viewer_app.dir}/image"/>
264
        </copy>
265

    
266
        <!-- remove empty output file and intermediate processing files -->
267
        <delete file="${viewer_app.dir}/dummy.xml"/>
268
        <delete file="${viewer_app.dir}/doc/changes-article.xml"/>
269
        <delete file="${viewer_app.dir}/doc/functions-article.xml"/>
270
    </target>
271

    
272

    
273

    
274

    
275

    
276
    <!-- Generate User Documentation for release -->
277

    
278
    <target name="release-userdoc" description="Generate User Documentation" depends="copy-notices, userdoc-html">
279
        <!-- Update the archive viewer app content -->
280
        <copy todir="${userdoc.uri}/saxon9/viewer_app">
281
            <fileset dir="${viewer_app.dir}"/>
282
        </copy>
283

    
284
        <copy todir="${build-resources.dir}/doc">
285
            <fileset dir="${userdoc.uri}/saxon9/fixed"/>
286
        </copy>
287
        <copy todir="${build-resources.dir}/doc">
288
            <fileset dir="${userdoc.uri}/saxon9/style">
289
                <include name="make-menu.xsl"/>
290
            </fileset>
291
        </copy>
292

    
293
        <zip zipfile="${build-resources.dir}/source-userdoc.zip">
294
            <fileset dir="${userdoc.uri}/saxon9">
295
                <include name="**/*.xml"/>
296
                <include name="**/*.xsl"/>
297
                <include name="**/*.xsd"/>
298
                <include name="**/*.css"/>
299
                <include name="fixed/**"/>
300
                <include name="welcome/**"/>
301
                <include name="viewer_app/Saxonce/**"/>
302
                <include name="viewer_app/index.html"/>
303
                <include name="viewer_app/readme.txt"/>
304
                <include name="viewer_app/cetree.js"/>
305
                <include name="viewer_app/image/**"/>
306
                <include name="viewer_app/docimg/**"/>
307
                <exclude name="xslt30-status.xml"/>
308
            </fileset>
309
        </zip>
310
    </target>
311

    
312

    
313
    <target name="copy-notices" description="Copy notice files">
314
        <copy todir="${product.dir}/hej">
315
            <fileset dir="${userdoc.uri}/saxon9/welcome">
316
                <include name="doc/**"/>
317
                <include name="notices/CERN.txt"/>
318
                <include name="notices/JAMESCLARK.txt"/>
319
                <include name="notices/LICENSE.txt"/>
320
                <include name="notices/THAI.txt"/>
321
                <include name="notices/UNICODE.txt"/>
322
            </fileset>
323
        </copy>
324
        <copy todir="${product.dir}/pej">
325
            <fileset dir="${userdoc.uri}/saxon9/welcome">
326
                <include name="doc/**"/>
327
                <include name="notices/CERN.txt"/>
328
                <include name="notices/ICU-J.txt"/>
329
                <include name="notices/JAMESCLARK.txt"/>
330
                <include name="notices/LICENSE.txt"/>
331
                <include name="notices/THAI.txt"/>
332
                <include name="notices/UNICODE.txt"/>
333
            </fileset>
334
        </copy>
335
        <copy todir="${product.dir}/eej">
336
            <fileset dir="${userdoc.uri}/saxon9/welcome">
337
                <include name="doc/**"/>
338
                <include name="notices/ASM.txt"/>
339
                <include name="notices/CERN.txt"/>
340
                <include name="notices/ICU-J.txt"/>
341
                <include name="notices/JAMESCLARK.txt"/>
342
                <include name="notices/LICENSE.txt"/>
343
                <include name="notices/THAI.txt"/>
344
                <include name="notices/UNICODE.txt"/>
345
            </fileset>
346
        </copy>
347
        <copy todir="${product.dir}/hen">
348
            <fileset dir="${userdoc.uri}/saxon9/welcome">
349
                <include name="doc/**"/>
350
                <include name="notices/CERN.txt"/>
351
                <include name="notices/JAMESCLARK.txt"/>
352
                <include name="notices/LICENSE.txt"/>
353
                <include name="notices/THAI.txt"/>
354
                <include name="notices/UNICODE.txt"/>
355
                <include name="notices/APACHE-XERCES.txt"/>
356
                <include name="notices/APACHE-RESOLVER.txt"/>
357
                <include name="notices/FRIJTERS.txt"/>
358
                <include name="notices/GPL+CLASSPATH.txt"/>
359
            </fileset>
360
        </copy>
361
        <copy todir="${product.dir}/pen">
362
            <fileset dir="${userdoc.uri}/saxon9/welcome">
363
                <include name="doc/**"/>
364
                <include name="notices/CERN.txt"/>
365
                <include name="notices/ICU-J.txt"/>
366
                <include name="notices/JAMESCLARK.txt"/>
367
                <include name="notices/LICENSE.txt"/>
368
                <include name="notices/THAI.txt"/>
369
                <include name="notices/UNICODE.txt"/>
370
                <include name="notices/APACHE-XERCES.txt"/>
371
                <include name="notices/APACHE-RESOLVER.txt"/>
372
                <include name="notices/FRIJTERS.txt"/>
373
                <include name="notices/GPL+CLASSPATH.txt"/>
374
            </fileset>
375
        </copy>
376
        <copy todir="${product.dir}/een">
377
            <fileset dir="${userdoc.uri}/saxon9/welcome">
378
                <include name="doc/**"/>
379
                <include name="notices/ASM.txt"/>
380
                <include name="notices/CERN.txt"/>
381
                <include name="notices/ICU-J.txt"/>
382
                <include name="notices/JAMESCLARK.txt"/>
383
                <include name="notices/LICENSE.txt"/>
384
                <include name="notices/THAI.txt"/>
385
                <include name="notices/UNICODE.txt"/>
386
                <include name="notices/APACHE-XERCES.txt"/>
387
                <include name="notices/APACHE-RESOLVER.txt"/>
388
                <include name="notices/FRIJTERS.txt"/>
389
                <include name="notices/GPL+CLASSPATH.txt"/>
390
            </fileset>
391
        </copy>
392
    </target>
393

    
394

    
395
</project>
(5-5/7)