doc/doc.build

   1 <?xml version="1.0"?>
   2 <!--
   3 NAnt build script for the TortoiseGit documentation
   4
   5 All project specific configuration is stored in doc.build.include.
   6 All user/site specific configuration is stored in doc.build.user.
   7
   8 -->
   9
  10 <project name="Documentation" default="all" basedir=".">
  11         <description>
  12                 Builds the Documentation and selected all output formats
  13         </description>
  14
  15         <!-- default: we don't clean first -->
  16         <property name="cleanup" value="" overwrite="false" />
  17
  18         <include buildfile="doc.build.include"/>
  19
  20 <!-- ====================================================================== -->
  21 <!-- Loop over all applications and output formats                          -->
  22 <!-- ====================================================================== -->
  23
  24         <target name="all"
  25                 description="Loop over all output formats and applications and build documentation"
  26                 depends="prepare" >
  27
  28                 <foreach item="String" in="${applications}" delim="," property="app">
  29                         <property name="doc.source.file" value="source/en/${app}.xml"/>
  30                         <property name="doc.base.name" value="${app}_en"/>
  31                         <property name="doc.base.work" value="output/${doc.base.name}"/>
  32
  33                         <property name="doc.target.name" value="${app}_en"/>
  34                         <property name="doc.target.work" value="output/${doc.target.name}"/>
  35                         <property name="doc.target.source" value="source/en/${app}/${app}.xml"/>
  36
  37                         <echo message="------------------------------------------------------------"/>
  38                         <echo message="Creating '${doc.target.name}' documentation"/>
  39
  40                         <delete file="source/en/TortoiseGit/git_doc/git-doc.xml" if="${app=='TortoiseGit'}"/>
  41                         <copy file="source/en/TortoiseGit/git_doc/git-doc.xml.in" tofile="source/en/TortoiseGit/git_doc/git-doc.xml" overwrite="true" if="${app=='TortoiseGit' and external.gitdocs=='0'}"/>
  42
  43                         <!-- update version info in version.xml -->
  44                         <call target="UpdateVersionInfo"/>
  45
  46                         <call target="spellcheck" if="${property::exists('spellcheck') and spellcheck=='true'}"/>
  47
  48                         <property name="xslt.source" value="${doc.target.source}"/>
  49                         <foreach item="String" in="${docformats}" delim="," property="docformat">
  50                                 <call target="copyimages"/>
  51                                 <call target="${docformat}"/>
  52                         </foreach>
  53                 </foreach>
  54         </target>
  55
  56 <!-- ====================================================================== -->
  57 <!-- ====================================================================== -->
  58
  59         <target name="clean" description="remove all generated files">
  60                 <if test="${cleanup == 'yes'}">
  61                         <delete dir="output" failonerror="false"/>
  62                 </if>
  63         </target>
  64
  65 <!-- ====================================================================== -->
  66 <!-- ====================================================================== -->
  67
  68         <target name="prepare" description="Create directories" depends="clean">
  69                 <mkdir dir="output"/>
  70                 <call target="prepare.custom" if="${target::exists('prepare.custom')}"/>
  71
  72                 <property name="fontpath" value="/usr/share/fonts/truetype/" if="${platform::is-unix() and not property::exists('fontpath')}"/>
  73                 <property name="fontpath" value="${string::replace(environment::get-variable('windir'), '\', '/')}/Fonts/" if="${platform::is-windows() and not property::exists('fontpath')}"/>
  74                 <fail unless="${directory::exists(fontpath)}">fontpath '${fontpath}' does not exist</fail>
  75
  76                 <!-- ensure "Version" translation invariant -->
  77                 <copy file="source/en/Version.in" tofile="source/en/version.xml" overwrite="true"/>
  78
  79                 <!-- tune path to xsltproc.exe in aspell.bat -->
  80                 <copy file="Aspell/aspell.bat.in" tofile="Aspell/aspell.bat" overwrite="true" unless="${platform::is-unix()}">
  81                         <filterchain>
  82                                 <replacetokens begintoken="$" endtoken="$">
  83                                         <token key="XSLTProcPath" value="${path.bin}" />
  84                                 </replacetokens>
  85                         </filterchain>
  86                 </copy>
  87
  88         </target>
  89
  90 <!-- ====================================================================== -->
  91 <!-- ====================================================================== -->
  92
  93         <target name="copyimages" description="Copy images">
  94                 <delete dir="${doc.target.work}/images" failonerror="false"/>
  95                 <mkdir dir="${doc.target.work}/images"/>
  96                 <mkdir dir="${doc.target.work}/images/callouts" if="${app=='TortoiseGit' and external.gitdocs=='0'}"/>
  97
  98                 <property name="xslt.params" value="${xsl.pdf.params}"/>
  99                 <property name="xslt.target" value="${path::get-temp-file-name()}"/>
 100                 <exec program="xsltproc"
 101                                         commandline="${xslt.params} --output ${xslt.target} images/extract-images.xsl ${xslt.source}"
 102                                         basedir="${path.bin}"
 103                                         verbose="false"/>
 104                 <foreach item="Line" in="${xslt.target}" property="filename" trim="Both">
 105                         <property name="destname" value="${doc.target.work}/images/${filename}"/>
 106                         <copy file="images/en/${filename}" tofile="${destname}" if="${file::exists(path::combine('images', path::combine('en', filename)))}"/>
 107                         <copy file="images/en/${filename}" tofile="${destname}" unless="${file::exists(destname)}"/>
 108                 </foreach>
 109
 110                 <copy todir="${doc.target.work}/images">
 111                         <fileset basedir="images/en">
 112                                 <include name="caution.png"/>
 113                                 <include name="warning.png"/>
 114                                 <include name="important.png"/>
 115                                 <include name="tip.png"/>
 116                                 <include name="note.png"/>
 117                                 <include name="link.png"/>
 118                         </fileset>
 119                 </copy>
 120
 121                 <copy todir="${doc.target.work}/images/callouts" if="${app=='TortoiseGit' and external.gitdocs=='0'}">
 122                         <fileset basedir="images/en/callouts">
 123                                 <include name="*.svg"/>
 124                         </fileset>
 125                 </copy>
 126         </target>
 127
 128 <!-- ====================================================================== -->
 129 <!-- ====================================================================== -->
 130
 131         <target name="uptodate" description="Check whether the given target is up to date">
 132
 133                 <echo message="Checking if '${file.target}' is up to date"/>
 134                 <uptodate property="file.target.uptodate">
 135                         <sourcefiles>
 136                                 <include name="source/en/${app}/**/*.xml"/>
 137                                 <include name="source/en/glossary.xml"/>
 138                                 <include name="source/en/wishlist.xml"/>
 139                                 <include name="source/en/version.in"/>
 140                         </sourcefiles>
 141                         <targetfiles>
 142                                 <include name="${file.target}"/>
 143                         </targetfiles>
 144                 </uptodate>
 145                 <if test="${file.target.uptodate}">
 146                         <echo message="Up to date"/>
 147                 </if>
 148         </target>
 149
 150 <!-- ====================================================================== -->
 151 <!-- Run xsltproc with the defined parameters                               -->
 152 <!-- ====================================================================== -->
 153
 154         <target name="xsltproc" description="Run xsltproc with the defined parameters">
 155                 <echo message="Processing XML Source" />
 156
 157                 <!-- Check whether a language specific xsl file exists and use it -->
 158                 <!-- if none is found, load XSL file from default location.       -->
 159                 <property name="xslt.file.lang" value="${path.user.xsl}/en/${xslt.file}" />
 160                 <property name="xslt.file" value="${xslt.file.lang}" if="${file::exists(xslt.file.lang)}"/>
 161                 <property name="xslt.file" value="${path.user.xsl}/${xslt.file}" unless="${file::exists(xslt.file.lang)}"/>
 162
 163                 <echo message="Stylesheet: ${xslt.file}" />
 164                 <echo message="Parameters: ${xslt.params}" />
 165                 <property name="xslt.output.file" value="${path::get-temp-file-name()}"/>
 166                 <exec program="xsltproc"
 167                                         commandline="${xslt.params} --output ${xslt.target} ${xslt.file} ${xslt.source}"
 168                                         basedir="${path.bin}"
 169                                         output="${xslt.output.file}"
 170                                         verbose="false"/>
 171                 <loadfile file="${xslt.output.file}" property="xsltproc.output" />
 172                 <fail if="${string::contains(xsltproc.output, ': parser error :')}">"Parser error" found</fail>
 173                 <fail if="${string::contains(xsltproc.output, 'Error: no ID for constraint linkend:')}">"Error: no ID for constraint linkend:" found</fail>
 174                 <fail if="${string::contains(xsltproc.output, 'ERROR: xref linking to ')}">"ERROR: xref linking to" found</fail>
 175                 <fail if="${string::contains(xsltproc.output, ', but no template matches.')}">unknown element found (look for "Element X encountered in Y, but no template matches.")</fail>
 176         </target>
 177
 178 <!-- ====================================================================== -->
 179 <!-- Try to update version info in the version file                         -->
 180 <!-- ====================================================================== -->
 181
 182         <target name="UpdateVersionInfo" description="Updates the version file with version info">
 183
 184                 <copy
 185                         file="source/en/Version.in"
 186                         tofile="source/en/version.xml"
 187                         overwrite="true">
 188
 189                         <filterchain>
 190                                 <replacetokens begintoken="$" endtoken="$">
 191                                         <token key="MajorVersion" value="${environment::get-variable('MajorVersion')}"/>
 192                                         <token key="MinorVersion" value="${environment::get-variable('MinorVersion')}"/>
 193                                         <token key="MicroVersion" value="${environment::get-variable('MicroVersion')}"/>
 194                                 </replacetokens>
 195                         </filterchain>
 196                 </copy>
 197
 198         </target>
 199
 200 <!-- ====================================================================== -->
 201 <!-- Run spellchecker on files                                              -->
 202 <!-- ====================================================================== -->
 203
 204         <target name="spellcheck" description="Run spellchecker on files">
 205                 <echo message="Spellchecking: '${app} en' This may take a few minutes"/>
 206                 <property name="spellcheck.log" value="Aspell/${app}_en.log"/>
 207                 <property name="script.extension" value=".bat" if="${platform::is-windows()}"/>
 208                 <property name="script.extension" value=".sh" if="${platform::is-unix()}"/>
 209                 <mkdir dir="Aspell/${app}_en"/>
 210
 211                 <delete dir="${spellcheck.log}" failonerror="false"/>
 212
 213                 <copy file="Aspell/TortoiseGit.tmpl.pws" tofile="Aspell/Temp.pws" overwrite="true" inputencoding="utf-8" outputencoding="utf-8">
 214                         <filterchain>
 215                                 <replacetokens begintoken="$" endtoken="$">
 216                                         <token key="LANG" value="en" />
 217                                 </replacetokens>
 218                         </filterchain>
 219                 </copy>
 220                 <exec program="sed" commandline=" -i '1s/^\xEF\xBB\xBF//' ./Aspell/Temp.pws" if="${platform::is-unix()}"/> <!-- outputencoding="utf-8" inserts BOM, aspell doesn't like that -->
 221
 222                 <foreach item="File" property="file.base">
 223                         <in>
 224                                 <items>
 225                                         <exclude name="source/en/TortoiseGit/git_doc/*.xml"/>
 226                                         <include name="source/en/${app}/**/*.xml"/>
 227                                         <include name="source/en/glossary.xml"/>
 228                                         <include name="source/en/wishlist.xml"/>
 229                                 </items>
 230                         </in>
 231                         <do>
 232                                 <property name="file.target" value="${file.base}"/>
 233                                 <property name="file.log" value="Aspell/${app}_en/${path::get-file-name(file.target)}.log"/>
 234
 235                                 <uptodate property="file.target.uptodate">
 236                                         <sourcefiles>
 237                                                 <include name="${file.target}"/>
 238                                                 <include name="Aspell/en.pws"/>
 239                                                 <include name="Aspell/TortoiseGit.tmpl.pws"/>
 240                                         </sourcefiles>
 241                                         <targetfiles>
 242                                                 <include name="${file.log}"/>
 243                                         </targetfiles>
 244                                 </uptodate>
 245
 246                                 <if test="${not file.target.uptodate}">
 247                                         <echo message="Checking: ${path::get-file-name(file.target)}"/>
 248                                         <exec program="Aspell/aspell${script.extension}"
 249                                                 commandline="&quot;${path.spellcheck}&quot; &quot;en&quot; &quot;${file.target}&quot; &quot;${file.log}&quot;"
 250                                                 failonerror="false"/>
 251                                 </if>
 252                                 <exec program="Aspell/append${script.extension}"
 253                                         commandline="${file.log} ${spellcheck.log}"/>
 254                         </do>
 255                 </foreach>
 256         </target>
 257
 258 <!-- ====================================================================== -->
 259 <!-- Create PDF documentation                                               -->
 260 <!-- ====================================================================== -->
 261
 262         <target name="pdf" description="Create PDF documentation">
 263
 264                 <property name="file.target" value="output/${app}-${docverstring}-en.pdf"/>
 265                 <call target="uptodate"/>
 266
 267                 <if test="${not file.target.uptodate}">
 268                         <property name="xslt.params" value="${xsl.pdf.params}"/>
 269                         <property name="xslt.file" value="${xsl.pdf.file}"/>
 270                         <property name="xslt.final" value="${doc.target.work}/${doc.target.name}"/>
 271                         <!-- set xslt.target to the name of the temp file -->
 272                         <property name="xslt.target" value="${xslt.final}.tmp"/>
 273
 274                         <call target="xsltproc" />
 275
 276                         <!-- Removes the span="inherit" attribute added by xsltproc, which causes a warning -->
 277                         <move file="${xslt.target}" tofile="${xslt.final}.fo" overwrite="true" inputencoding="utf-8" outputencoding="utf-8">
 278                                 <filterchain>
 279                                         <replacestring from="span=&quot;inherit&quot; " to="" />
 280                                         <replacestring from="width=&quot;auto&quot; height=&quot;auto&quot; content-width=&quot;auto&quot; content-height=&quot;auto&quot;" to="inline-progression-dimension.maximum=&quot;100%&quot; content-width=&quot;scale-down-to-fit&quot; content-height=&quot;scale-down-to-fit&quot;" />
 281                                 </filterchain>
 282                         </move>
 283
 284                         <property name="userconfig.langtemplate" value="${path.user.xsl}/en/userconfig.template.xml" />
 285                         <property name="userconfig.lang" value="${path.user.xsl}/en/userconfig.xml" />
 286
 287                         <if test="${file::exists(userconfig.langtemplate)}">
 288                                 <loadfile file="${userconfig.langtemplate}" property="configfile">
 289                                         <filterchain>
 290                                                 <replacetokens begintoken="%" endtoken="%">
 291                                                         <token key="FONTSDIR" value="${fontpath}" />
 292                                                 </replacetokens>
 293                                         </filterchain>
 294                                 </loadfile>
 295                                 <echo file="${userconfig.lang}" message="${configfile}" />
 296                         </if>
 297                         <property name="commandline" value="-q -fo ${xslt.final}.fo -pdf ${file.target}"/>
 298                         <property name="commandline" value="-c ${userconfig.lang} ${commandline}" if="${file::exists(userconfig.lang)}"/>
 299
 300                         <exec program="${name.fop}"
 301                                                 commandline="${commandline}"
 302                                                 basedir="${path.fop}"
 303                                                 verbose="false"/>
 304                 </if>
 305         </target>
 306
 307 <!-- ====================================================================== -->
 308 <!-- Create HTML multi page documentation                                   -->
 309 <!-- ====================================================================== -->
 310         <target name="html" description="Create HTML documentation" depends="">
 311
 312                 <property name="file.target" value="${doc.target.work}/index.html"/>
 313                 <call target="uptodate"/>
 314
 315                 <if test="${not file.target.uptodate}">
 316                         <property name="xslt.params" value="${xsl.htmlsingle.params}"/>
 317                         <property name="xslt.file" value="${xsl.htmlsingle.file}"/>
 318                         <property name="xslt.target" value="${doc.target.work}/${doc.target.name}"/>
 319
 320                         <copy file="${path.user.css}/styles_html.css" todir="${doc.target.work}"/>
 321
 322                         <call target="xsltproc" />
 323                 </if>
 324                 <if test="${help.mapping=='1'}">
 325                         <call target="helpmapping"/>
 326                         <property name="help.wixfilelist" value="../src/TortoiseGitSetup/HTMLHelpfiles.wxi" unless="${property::exists('help.wixfilelist')}"/>
 327                         <exec program="${name.python}"
 328                                                 commandline="scripts/generate_wix_filelist.py"
 329                                                 output="${help.wixfilelist}"
 330                                                 verbose="false"/>
 331                         <exec program="sed" commandline=" -i 's/$/\r/' ${help.wixfilelist}" if="${platform::is-unix()}"/>
 332                         <echo message="Updated help WiX filelist: '${help.wixfilelist}'"/>
 333                 </if>
 334         </target>
 335
 336 <!-- ====================================================================== -->
 337 <!-- Create HTML single page documentation                                  -->
 338 <!-- ====================================================================== -->
 339
 340         <target name="htmlsingle" description="Create HTML single page documentation" depends="">
 341
 342                 <property name="file.target" value="${doc.target.work}/help-onepage.html"/>
 343                 <call target="uptodate"/>
 344
 345                 <if test="${not file.target.uptodate}">
 346                         <property name="xslt.params" value="${xsl.html.params}"/>
 347                         <property name="xslt.file" value="${xsl.html.file}"/>
 348                         <property name="xslt.target" value="${file.target}"/>
 349
 350                         <copy file="${path.user.css}/styles_html.css" todir="${doc.target.work}"/>
 351
 352                         <call target="xsltproc" />
 353
 354                 </if>
 355         </target>
 356
 357 <!-- ====================================================================== -->
 358 <!-- Create mapping files for TortoiseGit online help                       -->
 359 <!-- ====================================================================== -->
 360
 361         <target name="helpmapping" description="Create help mapping for IDs to filenames">
 362                 <call target="help.prepare.${app}" />
 363                 <exec program="${name.python}"
 364                                         commandline="scripts/create_html_mapping.py ${help.resource} ${doc.target.work}/alias.h"
 365                                         output="${help.mappingfile}"
 366                                         verbose="false"/>
 367                 <exec program="sed" commandline=" -i 's/$/\r/' ${help.mappingfile}" if="${platform::is-unix()}"/>
 368                 <echo message="Updated help mapping: '${help.mappingfile}'"/>
 369         </target>
 370
 371 </project>