Project

Profile

Help

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

he / latest9.6 / 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
    <!-- Saxon used for some late-stage operations, noteably documentation generation -->
27
    <property name="use.EE" value="true" description="Use -EE for documentation, otherwise PE"/>
28
    <property if:true="${use.EE}" name="saxon.edition" value="Enterprise"
29
        description="Enterprise Saxon"/>
30
    <property unless:true="${use.EE}" name="saxon.edition" value="Professional"
31
        description="Professional Saxon"/>
32

    
33

    
34
    <path id="saxon.class.path">
35
        <fileset if:true="${use.EE}" dir="${product.dir}/eej">
36
            <include name="*.jar"/>
37
        </fileset>
38
        <fileset unless:true="${use.EE}" dir="${product.dir}/pej">
39
            <include name="*.jar"/>
40
        </fileset>
41
        <!-- <pathelement path="${lib.dir}"/>-->
42
        <!--<pathelement path="${product.dir}/eej"/>-->
43
    </path>
44

    
45
    <path id="saxonee.class.path">
46
        <!-- <pathelement path="${lib.dir}"/>-->
47
        <pathelement path="${product.dir}/eej"/>
48
    </path>
49

    
50

    
51

    
52
    <!-- Expand the documentation sections from inclusions
53
    Note that the 'output' parameter is important - this stylesheet produces result documents
54
    which Ant DOES NOT automatically place relative to the 'out' location - that appears to be a pipe
55
    outside XSLT.
56
     Also note of course that the main catalog.xml file is 'touched' to make sure that a re-run will be forced -->
57

    
58
    <macrodef name="EXPath-doc"
59
        description="Expand EXPath functional documentation. This links to GitHub">
60
        <attribute name="target"/>
61
        <sequential>
62
            <xslt in="${userdoc.dir}/src/functions/EXPath/functions-@{target}.xml"
63
                out="${userdoc.dir}/src/functions/EXPath/functions-@{target}-expanded.xml"
64
                style="${userdoc.dir}/style/genFunctionDoc.xsl" classpathref="saxon.class.path">
65
                <param name="GitHub" expression="${GitHub.dir}"/>
66
                <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
67
                    <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
68
                        value="${saxon.license}"/>
69
                    <attribute name="http://saxon.sf.net/feature/xinclude-aware" value="true"/>
70
                </factory>
71
            </xslt>
72
        </sequential>
73
    </macrodef>
74

    
75
    <macrodef name="Element-doc"
76
              description="Expand XSLT Element Reference and Extensions documentation">
77
        <attribute name="target"/>
78
        <sequential>
79
            <xslt in="${userdoc.dir}/src/extensions/@{target}-src.xml"
80
                  out="${userdoc.dir}/src/extensions/@{target}-expanded.xml"
81
                  style="${userdoc.dir}/style/elements-body.xsl" classpathref="saxon.class.path">
82
                <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
83
                    <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
84
                               value="${saxon.license}"/>
85
                    <!-- Bug 2126 may require byte code suppression - remove this when fixed -->
86
                    <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
87
                </factory>
88
            </xslt>
89
        </sequential>
90
    </macrodef>
91

    
92
    <target name="gen-doc"
93
        description="Collects up, generates and copies the documentation source into the canonical location">
94
        <!--<diagnostics/>-->
95
        <echo message="Using Saxon ${saxon.edition} Edition"/>
96
        <echo message="License file: ${saxon.license}"/>
97

    
98
        <!-- Generate the ICU/UCA documentation which involves self-inspection extension functions -->
99
        <xslt in="${userdoc.dir}/src/catalog.xml" out="${userdoc.dir}/src/extensibility/temp.xml"
100
            style="${userdoc.dir}/style/document-ICU.xsl" classpathref="saxon.class.path">
101
            <param name="output" expression="extensibility/catalog.xml"/>
102
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
103
                <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
104
                    value="${saxon.license}"/>
105
                <attribute name="http://saxon.sf.net/feature/initialTemplate" value="go"/>
106
                <!--<attribute if:true="${use.EE}" name="http://saxon.sf.net/feature/trace-external-functions" value="true"/>-->
107
                <!-- Bug 2126 may require byte code suppression - remove this when fixed -->
108
                <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
109
            </factory>
110
        </xslt>
111

    
112
        <!-- Generate the XSLT Element reference documentation -->
113
        <xslt in="${userdoc.dir}/src/elements/xsl-elements-src.xml" out="${userdoc.dir}/src/elements/xsl-elements-expanded.xml"
114
              style="${userdoc.dir}/style/genElementDoc.xsl" classpathref="saxon.class.path">
115
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
116
                <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
117
                           value="${saxon.license}"/>
118
                <!-- Bug 2126 may require byte code suppression - remove this when fixed -->
119
                <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
120
            </factory>
121
        </xslt>
122

    
123
        <xslt in="${userdoc.dir}/src/elements/xsl-elements-expanded.xml" out="${userdoc.dir}/src/xsl-elements.xml"
124
              style="${userdoc.dir}/style/elements-body.xsl" classpathref="saxon.class.path">
125
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
126
                <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
127
                           value="${saxon.license}"/>
128
                <!-- Bug 2126 may require byte code suppression - remove this when fixed -->
129
                <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
130
            </factory>
131
        </xslt>
132

    
133
        <!-- Generate the Extensions documentation: instructions, serialization parameters, Saxon SQL Extension -->
134
        <Element-doc target="instructions"/>
135
        <Element-doc target="serialization-params"/>
136
        <Element-doc target="sql-extension"/>
137
        <copy file="${userdoc.dir}/src/extensions/sql-extension-expanded.xml"
138
                tofile="${userdoc.dir}/src/sql-extension.xml">
139
        </copy>
140

    
141
        <!-- Expand the EXPath documentation -->
142
        <EXPath-doc target="binary"/>
143
        <EXPath-doc target="archive"/>
144
        <EXPath-doc target="file"/>
145

    
146
        <!-- Expand the documentation sections from inclusions
147
    Note that the 'output' parameter is important - this stylesheet produces result documents
148
    which Ant DOES NOT automatically place relative to the 'out' location - that appears to be a pipe
149
    outside XSLT.
150
     Also note of course that the main catalog.xml file is 'touched' to make sure that a re-run will be forced -->
151

    
152

    
153
        <xslt in="${userdoc.dir}/src/catalog.xml" out="${userdoc.dir}/viewer_app/doc/catalog.xml"
154
            style="${userdoc.dir}/style/doc-include.xsl" classpathref="saxon.class.path">
155
            <param name="output" expression="../viewer_app/doc/catalog.xml"/>
156
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
157
                <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
158
                    value="${saxon.license}"/>
159
                <attribute name="http://saxon.sf.net/feature/xinclude-aware" value="true"/>
160
            </factory>
161
        </xslt>
162

    
163
        <!-- This touch ensures that gen-doc will run again on a subsequent invocation 
164
            even if the catalog itself hasn't been modified, which is the normal case. 
165
            It's the resources that it points to that are much more likely to change -->
166
        <touch file="${userdoc.dir}/src/catalog.xml"/>
167
    </target>
168

    
169
    <!-- Generate documentation contents pages for website:
170
    both XML version for dynamic site & 'base' HTML version for static site
171
    (the output contents-page-static.html gets menus added later in doc-contents-html target) -->
172

    
173
    <target name="contents-pages"
174
            description="Creates the contents for the user documentation">
175
        <!-- depends="gen-doc" : only add this back in when you really want to generate all documentation -->
176
        <echo message="Using Saxon ${saxon.edition} Edition"/>
177
        <echo message="License file: ${saxon.license}"/>
178

    
179
        <!-- Generate contents reference file -->
180

    
181
        <xslt in="${userdoc.dir}/viewer_app/doc/catalog.xml" out="${userdoc.dir}/viewer_app/doc/contents.xml"
182
              style="${userdoc.dir}/style/contents-builder.xsl" classpathref="saxon.class.path">
183
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
184
                <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
185
                           value="${saxon.license}"/>
186
                <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
187
            </factory>
188
        </xslt>
189

    
190
        <!-- Generate contents pages in XML (for dynamic website) and 'base' HTML (for static website) -->
191

    
192
        <xslt in="${userdoc.dir}/viewer_app/doc/contents.xml"
193
              out="${userdoc.dir}/viewer_app/dummy.xml"
194
              style="${userdoc.dir}/style/contentsDoc.xsl" classpathref="saxon.class.path">
195
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
196
                <attribute name="http://saxon.sf.net/feature/licenseFileLocation"
197
                           value="${saxon.license}"/>
198
                <attribute name="http://saxon.sf.net/feature/optimizationLevel" value="0"/>
199
            </factory>
200
            <param name="base-uri" expression="${userdoc.dir}/viewer_app"/>
201
        </xslt>
202
        <delete file="${userdoc.dir}/viewer_app/dummy.xml"/>
203
    </target>
204

    
205

    
206
    <!-- Generate static version of documentation main page and contents page -->
207

    
208
    <target name="doc-contents-html" description="Build the static documentation main page and contents page"
209
            depends="contents-pages">
210

    
211
        <xslt in="${userdoc.dir}/viewer_app/contents-page-static.html" out="${userdoc.dir}/viewer_app/html/documentation/contents-page.html"
212
              style="${userdoc.dir}/to-static/docmake-menu-static.xsl" classpathref="saxon.class.path">
213
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
214
                <attribute name="http://saxon.sf.net/feature/xsltSchemaAware" value="false"/>
215
            </factory>
216
        </xslt>
217
        <xslt in="${userdoc.dir}/viewer_app/documentation-static.html" out="${userdoc.dir}/viewer_app/html/documentation/documentation.html"
218
              style="${userdoc.dir}/to-static/docmake-menu-static.xsl" classpathref="saxon.class.path">
219
            <factory name="com.saxonica.config.${saxon.edition}TransformerFactory">
220
                <attribute name="http://saxon.sf.net/feature/xsltSchemaAware" value="false"/>
221
            </factory>
222
        </xslt>
223
    </target>
224

    
225

    
226
    <!-- Generate static HTML version of user documentation -->
227

    
228
    <target name="userdoc-html"
229
        description="Creates the static HTML version of the user documentation">
230
        <mkdir dir="${temp.dir}/tempdoc"/>
231
        <echo message="Using Saxon ${saxon.edition} Edition"/>
232
        <echo message="License file: ${saxon.license}"/>
233

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

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

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

    
243
        </xslt>
244

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

    
247
        <xslt in="${userdoc.dir}/viewer_app/doc/functions.xml"
248
            out="${userdoc.dir}/viewer_app/doc/functions-article.xml"
249
            style="${userdoc.dir}/to-static/c-functions.xsl" destdir="${temp.dir}/tempdoc" >
250
            <classpath refid="saxon.class.path"/>
251

    
252
            <factory name="com.saxonica.config.EnterpriseTransformerFactory"/>
253

    
254
        </xslt>
255

    
256
        <!-- Now process all the articles -->
257

    
258
       <xslt in="${userdoc.dir}/viewer_app/doc/catalog.xml" out="${userdoc.dir}/out/dummy.xml"
259
            style="${userdoc.dir}/to-static/s-cetree.xsl" destdir="${temp.dir}/tempdoc">
260
            <classpath refid="saxon.class.path"/>
261

    
262
            <factory name="com.saxonica.config.EnterpriseTransformerFactory"/>
263
            <param name="changes-article" expression="../viewer_app/doc/changes-article.xml"/>
264
            <param name="functions-article" expression="../viewer_app/doc/functions-article.xml"/>
265
           <param name="base-uri" expression="${userdoc.dir}/viewer_app/html/documentation"/>
266
        </xslt>
267
        <copy file="${userdoc.dir}/viewer_app/cetree.css" tofile="${userdoc.dir}/viewer_app/html/cetree.css"/>
268

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

    
275

    
276
    <target name="release-userdoc" description="Generate User Documentation" depends="userdoc-html">
277
        <copy todir="${build-resources.dir}/doc">
278
            <fileset dir="${userdoc.dir}/fixed"/>
279
        </copy>
280
        <copy todir="${build-resources.dir}/doc">
281
            <fileset dir="${userdoc.dir}/style">
282
                <include name="make-menu.xsl"/>
283
            </fileset>
284
        </copy>
285
        <copy todir="${product.dir}/hej">
286
            <fileset dir="${userdoc.dir}/welcome">
287
                <include name="doc/**"/>
288
                <include name="notices/CERN.txt"/>
289
                <include name="notices/JAMESCLARK.txt"/>
290
                <include name="notices/LICENSE.txt"/>
291
                <include name="notices/THAI.txt"/>
292
                <include name="notices/UNICODE.txt"/>
293
            </fileset>
294
        </copy>
295
        <copy todir="${product.dir}/pej">
296
            <fileset dir="${userdoc.dir}/welcome">
297
                <include name="doc/**"/>
298
                <include name="notices/CERN.txt"/>
299
                <include name="notices/ICU-J.txt"/>
300
                <include name="notices/JAMESCLARK.txt"/>
301
                <include name="notices/LICENSE.txt"/>
302
                <include name="notices/THAI.txt"/>
303
                <include name="notices/UNICODE.txt"/>
304
            </fileset>
305
        </copy>
306
        <copy todir="${product.dir}/eej">
307
            <fileset dir="${userdoc.dir}/welcome">
308
                <include name="doc/**"/>
309
                <include name="notices/ASM.txt"/>
310
                <include name="notices/CERN.txt"/>
311
                <include name="notices/ICU-J.txt"/>
312
                <include name="notices/JAMESCLARK.txt"/>
313
                <include name="notices/LICENSE.txt"/>
314
                <include name="notices/THAI.txt"/>
315
                <include name="notices/UNICODE.txt"/>
316
            </fileset>
317
        </copy>
318
        <copy todir="${product.dir}/hen">
319
            <fileset dir="${userdoc.dir}/welcome">
320
                <include name="doc/**"/>
321
                <include name="notices/CERN.txt"/>
322
                <include name="notices/JAMESCLARK.txt"/>
323
                <include name="notices/LICENSE.txt"/>
324
                <include name="notices/THAI.txt"/>
325
                <include name="notices/UNICODE.txt"/>
326
                <include name="notices/APACHE-XERCES.txt"/>
327
                <include name="notices/APACHE-RESOLVER.txt"/>
328
                <include name="notices/FRIJTERS.txt"/>
329
                <include name="notices/GPL+CLASSPATH.txt"/>
330
            </fileset>
331
        </copy>
332
        <copy todir="${product.dir}/pen">
333
            <fileset dir="${userdoc.dir}/welcome">
334
                <include name="doc/**"/>
335
                <include name="notices/CERN.txt"/>
336
                <include name="notices/ICU-J.txt"/>
337
                <include name="notices/JAMESCLARK.txt"/>
338
                <include name="notices/LICENSE.txt"/>
339
                <include name="notices/THAI.txt"/>
340
                <include name="notices/UNICODE.txt"/>
341
                <include name="notices/APACHE-XERCES.txt"/>
342
                <include name="notices/APACHE-RESOLVER.txt"/>
343
                <include name="notices/FRIJTERS.txt"/>
344
                <include name="notices/GPL+CLASSPATH.txt"/>
345
            </fileset>
346
        </copy>
347
        <copy todir="${product.dir}/een">
348
            <fileset dir="${userdoc.dir}/welcome">
349
                <include name="doc/**"/>
350
                <include name="notices/ASM.txt"/>
351
                <include name="notices/CERN.txt"/>
352
                <include name="notices/ICU-J.txt"/>
353
                <include name="notices/JAMESCLARK.txt"/>
354
                <include name="notices/LICENSE.txt"/>
355
                <include name="notices/THAI.txt"/>
356
                <include name="notices/UNICODE.txt"/>
357
                <include name="notices/APACHE-XERCES.txt"/>
358
                <include name="notices/APACHE-RESOLVER.txt"/>
359
                <include name="notices/FRIJTERS.txt"/>
360
                <include name="notices/GPL+CLASSPATH.txt"/>
361
            </fileset>
362
        </copy>
363
        <!--<dependset>
364
          <! rerun the XSLT transformations if any input files have changed >
365
          <srcfilelist
366
             dir   = "${userdoc.dir}/src/"
367
             files = "*.xml"/>
368
          <srcfilelist
369
             dir   = "${userdoc.dir}/style/"
370
             files = "*.xsl"/>
371
          <targetfileset
372
             dir      = "${product.dir}/resources/doc/"
373
             includes = "dummy.html"/>
374
          <targetfileset
375
             dir      = "${userdoc.dir}/src/"
376
             includes = "functions.xml"/>
377
          <targetfileset
378
             dir      = "${userdoc.dir}/src/"
379
             includes = "index-entries.xml, FeatureKeysDoc.xml"/>
380
      </dependset>
381
        <xslt in="${userdoc.dir}/src/function-data2.xml"
382
              style="${userdoc.dir}/style/preprocess-functions2.xsl"
383
              out="${userdoc.dir}/src/functions.xml"
384
              >
385
              <factory name="com.saxonica.config.EnterpriseTransformerFactory">
386
                  <attribute name="http://saxon.sf.net/feature/timing" value="true"/>
387
                  <attribute name="http://saxon.sf.net/feature/xsltSchemaAware" value="true"/>
388
                  <attribute name="http://saxon.sf.net/feature/schema-validation-mode" value="strict"/>
389
                  <attribute name="http://saxon.sf.net/feature/xsd-version" value="1.1"/>
390
              </factory>
391
        </xslt>
392
        <xslt in="${userdoc.dir}/src/catalog.xml"
393
              style="${userdoc.dir}/style/index-builder.xsl"
394
              out="${userdoc.dir}/src/index-entries.xml"
395
              >
396
              <factory name="com.saxonica.config.EnterpriseTransformerFactory">
397
                  <attribute name="http://saxon.sf.net/feature/xsltSchemaAware" value="true"/>
398
                  <attribute name="http://saxon.sf.net/feature/schema-validation-mode" value="strict"/>
399
                  <attribute name="http://saxon.sf.net/feature/xsd-version" value="1.1"/>
400
              </factory>
401
        </xslt><!-\-classpath=".;../output/saxon-build/9.3.0.6/eej/saxon9ee.jar;../saxon-licenses"-\->
402
        <xslt in="${userdoc.dir}/src/FeatureKeys.xml"
403
              style="${userdoc.dir}/style/FeatureKeysToDoc.xsl"
404
              out="${userdoc.dir}/src/FeatureKeysDoc.xml"
405
              >
406
              <factory name="com.saxonica.config.EnterpriseTransformerFactory">
407
                  <attribute name="http://saxon.sf.net/feature/xsltSchemaAware" value="true"/>
408
                  <attribute name="http://saxon.sf.net/feature/schema-validation-mode" value="lax"/>
409
                  <attribute name="http://saxon.sf.net/feature/xsd-version" value="1.1"/>
410
              </factory>
411
        </xslt>
412
        <xslt in="${userdoc.dir}/src/catalog.xml"
413
              style="${userdoc.dir}/style/page-splitter.xsl"
414
              out="${product.dir}/resources/doc/dummy.html"
415
              >
416
              <factory name="com.saxonica.config.EnterpriseTransformerFactory">
417
                  <attribute name="http://saxon.sf.net/feature/xsltSchemaAware" value="true"/>
418
                  <attribute name="http://saxon.sf.net/feature/timing" value="true"/>
419
                  <attribute name="http://saxon.sf.net/feature/schema-validation-mode" value="lax"/>
420
                  <attribute name="http://saxon.sf.net/feature/xsd-version" value="1.1"/>
421
                  <attribute name="http://saxon.sf.net/feature/recognize-uri-query-parameters" value="true"/>
422
              </factory>
423
        </xslt>-->
424

    
425
        <zip zipfile="${build-resources.dir}/source-userdoc.zip">
426
            <fileset dir="${userdoc.dir}">
427
                <include name="**/*.xml"/>
428
                <include name="**/*.xsl"/>
429
                <include name="**/*.xsd"/>
430
                <include name="**/*.css"/>
431
                <include name="fixed/**"/>
432
                <include name="welcome/**"/>
433
            </fileset>
434
        </zip>
435
    </target>
436

    
437

    
438
</project>
(5-5/9)