doc/ale-doc.xsl

   1 <!--
   2   -  Copyright 2006 David Hilvert
   3   -
   4   -  ALE documentation stylesheet definition.
   5   -
   6   -  This file is part of the Anti-Lamenessing Engine documentation.
   7   -
   8   -  The Anti-Lamenessing Engine is free software; you can redistribute it and/or modify
   9   -  it under the terms of the GNU General Public License as published by
  10   -  the Free Software Foundation; either version 2 of the License, or
  11   -  (at your option) any later version.
  12   -
  13   -  The Anti-Lamenessing Engine is distributed in the hope that it will be useful,
  14   -  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   -  GNU General Public License for more details.
  17   -
  18   -  You should have received a copy of the GNU General Public License
  19   -  along with Anti-Lamenessing Engine; if not, write to the Free Software
  20   -  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  21   -->
  22
  23 <!DOCTYPE xsl:stylesheet [
  24
  25         <!--
  26           -  Entities
  27           -->
  28
  29         <!--
  30           -  Character classes
  31           -->
  32
  33         <!ENTITY uppercase "'ABCDEFGHIJKLMNOPQRSTUVWXYZ'">
  34         <!ENTITY lowercase "'abcdefghijklmnopqrstuvwxyz'">
  35
  36         <!--
  37           -
  38           -  NOTE: the below entities operate on edit records, which
  39           -  are expected to conform to exactly one of the following patterns:
  40           -
  41           -  <edit by="David Hilvert" on="2006-Sep-24">
  42           -  <edit by="David Hilvert" in-month="2006-Sep">
  43           -  <edit by="David Hilvert" in-year="2006">
  44           -
  45           -  The first form is preferred for occasional edits; the latter two
  46           -  are provided as shorthand for edits occurring over a number of
  47           -  days in succession, or for cases where the exact date of the edit
  48           -  is not known (e.g., when basing edit history on copyright notices
  49           -  from older files).
  50           -->
  51
  52
  53         <!--
  54           -  Obtain an editor name from an edit record.
  55           -->
  56
  57         <!ENTITY editor 'normalize-space(@by)'>
  58
  59         <!--
  60           -  Obtain an edit year from an edit record.
  61           -->
  62
  63         <!ENTITY year 'concat(@in-year, substring-before(@in-month, "-"), substring-before(@on, "-"))'>
  64
  65         <!--
  66           -  Generate a string unique for each (editor, year) combination.
  67           -->
  68
  69         <!ENTITY editor-year 'concat(&editor;, &year;)'>
  70
  71         <!--
  72           -  Boolean test to determine whether the current node is within the scope of
  73           -  $objectroot.
  74           -->
  75
  76         <!ENTITY scope 'count(ancestor::node()|$objectroot) = count(ancestor::node())'>
  77
  78         <!--
  79           -  Editor first name.
  80           -->
  81
  82         <!ENTITY editor-firstname 'substring-before(&editor;, " ")'>
  83
  84         <!--
  85           -  Editor last name
  86           -->
  87
  88         <!ENTITY editor-surname 'substring-after(&editor;, " ")'>
  89
  90         <!--
  91           -  Sort order for outputs including editor names.
  92           -->
  93
  94         <!ENTITY editor-sort-order '&editor-surname;'>
  95
  96         <!--
  97           -  Sort order for years
  98           -->
  99
 100         <!ENTITY year-sort-order '&year;'>
 101
 102 ]>
 103
 104 <xsl:stylesheet id="style1"
 105                 version="1.0"
 106                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 107                 xmlns:fo="http://www.w3.org/1999/XSL/Format"
 108                 xmlns:xi="http://www.w3.org/2001/XInclude">
 109
 110         <!--
 111           -  Product information
 112           -->
 113
 114         <xsl:param name="product-name" select="'ALE'"/>
 115
 116         <xsl:param name="product-version" select="'0.8.5-prerelease'"/>
 117
 118         <!--
 119           -  License information
 120           -->
 121
 122         <xsl:template match="*|/" mode="license-terms">
 123         <para>
 124           This <xsl:apply-templates select="." mode="document-type"/> is free
 125           documentation; you can redistribute it and/or modify it under the
 126           terms of the GNU General Public License as published by the Free
 127           Software Foundation; either version 2 of the License, or (at your
 128           option) any later version.
 129         </para>
 130         </xsl:template>
 131
 132         <xsl:template match="*|/" mode="license-object">
 133         <para>
 134           Unless otherwise defined within the GNU General Public License, any
 135           references to "object code" within the license are to be interpreted
 136           to refer to any non-source version of this <xsl:apply-templates
 137           select="." mode="document-type"/> (or of any work based on this
 138           <xsl:apply-templates select="." mode="document-type"/>).
 139         </para>
 140         </xsl:template>
 141
 142         <xsl:template match="*|/" mode="license-warranty">
 143         <para>
 144            This <xsl:apply-templates select="." mode="document-type"/> is
 145            distributed in the hope that it will be useful, but WITHOUT ANY
 146            WARRANTY; without even the implied warranty of MERCHANTABILITY or
 147            FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
 148            for more details.
 149          </para>
 150         </xsl:template>
 151
 152         <xsl:template match="*|/" mode="license-availability">
 153         <para>
 154            You should have received a copy of the GNU General Public License
 155            along with this <xsl:apply-templates select="."
 156            mode="document-type"/>; if not, write to the Free Software
 157            Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 158            02110-1301, USA.
 159         </para>
 160         </xsl:template>
 161
 162         <xsl:template match="*|/" mode="license">
 163         <legalnotice>
 164           <xsl:apply-templates select="." mode="license-terms"/>
 165           <xsl:apply-templates select="." mode="license-warranty"/>
 166           <xsl:apply-templates select="." mode="license-availability"/>
 167           <xsl:apply-templates select="." mode="license-object"/>
 168         </legalnotice>
 169         </xsl:template>
 170
 171         <!--
 172           -  Editing information
 173           -->
 174
 175         <xsl:key name="editors" match="edit" use="&editor;"/>
 176         <xsl:key name="editor-years" match="edit" use="&editor-year;"/>
 177
 178         <!--
 179           -  If no other template matches, we copy the tree structure unchanged.
 180           -->
 181
 182         <xsl:template match="@*|node()">
 183           <xsl:copy>
 184               <xsl:apply-templates select="@*|node()"/>
 185           </xsl:copy>
 186         </xsl:template>
 187
 188         <!--
 189           -  Do not pass edit tags to DocBook, as it doesn't understand them.
 190           -->
 191
 192         <xsl:template match="edit"/>
 193
 194         <!--
 195           -  Capitalize the initial letter of titles.
 196           -->
 197
 198         <xsl:template name="write_title">
 199            <xsl:param name="product-name"/>
 200            <xsl:param name="product-version"/>
 201            <xsl:param name="title" select="."/>
 202
 203            <xsl:variable name="space-stripped-title" select="normalize-space($title)"/>
 204            <xsl:variable name="initial" select="substring($space-stripped-title, 1, 1)"/>
 205            <xsl:variable name="sequel" select="substring($space-stripped-title, 2)"/>
 206
 207            <title>
 208
 209              <xsl:copy-of select="$product-name"/>
 210              <xsl:text> </xsl:text>
 211              <xsl:copy-of select="$product-version"/>
 212              <xsl:text> </xsl:text>
 213              <xsl:copy-of select="concat(translate($initial, &lowercase;, &uppercase;), $sequel)"/>
 214
 215            </title>
 216         </xsl:template>
 217
 218         <xsl:template match="text()" mode="title">
 219           <xsl:call-template name="write_title">
 220             <xsl:with-param name="title" select="."/>
 221           </xsl:call-template>
 222         </xsl:template>
 223
 224         <!--
 225           - Titles other than article, book and set titles.
 226           -->
 227
 228         <xsl:template match="title|t">
 229           <xsl:apply-templates select="text()" mode="title"/>
 230         </xsl:template>
 231
 232         <!--
 233           -  Add package information to titles of articles, books and sets.
 234           -->
 235
 236         <xsl:template match="setinfo/title|bookinfo/title|articleinfo/title|setinfo/t|bookinfo/t|articleinfo/t">
 237            <xsl:call-template name="write_title">
 238              <xsl:with-param name="product-name" select="$product-name"/>
 239              <xsl:with-param name="product-version" select="$product-version"/>
 240              <xsl:with-param name="title" select="text()"/>
 241            </xsl:call-template>
 242         </xsl:template>
 243
 244         <!--
 245           -  Generate title, author, copyright, and license information for
 246           -  articles, books and sets.
 247           -->
 248
 249         <xsl:template match="setinfo" mode="document-type">
 250           <xsl:text>set</xsl:text>
 251         </xsl:template>
 252
 253         <xsl:template match="bookinfo" mode="document-type">
 254           <xsl:text>book</xsl:text>
 255         </xsl:template>
 256
 257         <xsl:template match="articleinfo" mode="document-type">
 258           <xsl:text>article</xsl:text>
 259         </xsl:template>
 260
 261         <xsl:template match="setinfo|bookinfo|articleinfo">
 262         <xsl:copy>
 263           <xsl:param name="objectroot" select=".."/>
 264           <xsl:param name="editors-unique" select="$objectroot//edit[count(.|key('editors', &editor;)[&scope;][1]) = 1]"/>
 265           <xsl:param name="editor-years-unique" select="$objectroot//edit[count(.|key('editor-years', &editor-year;)[&scope;][1]) = 1]"/>
 266
 267           <!--
 268             -  Generate the title, if available.
 269             -->
 270
 271             <xsl:apply-templates select="title|t"/>
 272
 273           <!--
 274             -  Preserve abstracts.
 275             -->
 276
 277             <xsl:apply-templates select="abstract"/>
 278
 279           <!--
 280             -  Add author information.
 281             -->
 282
 283             <xsl:for-each select="$editors-unique">
 284               <xsl:sort select="&editor-sort-order;"/>
 285               <author>
 286                 <firstname>
 287                   <xsl:value-of select="&editor-firstname;"/>
 288                 </firstname>
 289                 <surname>
 290                   <xsl:value-of select="&editor-surname;"/>
 291                 </surname>
 292               </author>
 293             </xsl:for-each>
 294
 295           <!--
 296             -  Add copyright information
 297             -->
 298
 299             <xsl:for-each select="$editors-unique">
 300               <xsl:sort select="&editor-sort-order;"/>
 301               <xsl:param name="this-editor" select="&editor;"/>
 302               <copyright>
 303               <holder>
 304                 <xsl:value-of select="&editor;"/>
 305               </holder>
 306               <xsl:for-each select="$editor-years-unique">
 307                 <xsl:sort select="&year-sort-order;"/>
 308                 <xsl:if test="&editor; = $this-editor">
 309                   <year>
 310                     <xsl:value-of select="&year;"/>
 311                   </year>
 312                 </xsl:if>
 313               </xsl:for-each>
 314               </copyright>
 315             </xsl:for-each>
 316
 317
 318           <!--
 319             -  Add a license notice
 320             -->
 321
 322             <xsl:apply-templates select="." mode="license"/>
 323
 324         </xsl:copy>
 325         </xsl:template>
 326
 327         <!--
 328           -  Changelogs
 329           -->
 330
 331         <!--
 332           -  Changelog item
 333           -->
 334
 335         <xsl:template match="entry">
 336           <listitem>
 337             <xsl:apply-templates select="text/text()"/>
 338           </listitem>
 339         </xsl:template>
 340
 341         <!--
 342           - Keys
 343           -->
 344
 345         <xsl:key name="word-map" match="entry" use="word/child::text()"/>
 346
 347         <!--
 348           - Taxonomy
 349           -->
 350
 351         <xsl:variable name="taxonomy-root" select="document('taxonomy.xmli')"/>
 352
 353         <!--
 354           - Write a fragment substring for a (change, category) pair.
 355           -->
 356
 357         <xsl:template name="write-change-category">
 358           <xsl:param name="change"/>
 359           <xsl:param name="category"/>
 360           <xsl:value-of select="concat(generate-id($change), ':', generate-id($category), ' ')"/>
 361         </xsl:template>
 362
 363         <!--
 364           - Get a change category from a fragment result
 365           -->
 366
 367         <xsl:template name="get-change-category">
 368           <xsl:param name="change"/>
 369           <xsl:param name="fragment"/>
 370           <xsl:value-of select="substring-before(substring-after(substring-after($fragment, generate-id($change)), ':'), ' ')"/>
 371         </xsl:template>
 372
 373         <!--
 374           - Get a tree fragment with categories set to zero.
 375           -->
 376
 377         <xsl:template name="get-zero-categories">
 378           <xsl:param name="changes"/>
 379             <xsl:for-each select="$changes">
 380               <xsl:call-template name="write-change-category">
 381                 <xsl:with-param name="change" select="."/>
 382                 <xsl:with-param name="category" select="$taxonomy-root"/>
 383               </xsl:call-template>
 384             </xsl:for-each>
 385         </xsl:template>
 386
 387         <!--
 388           - Determine whether a category tree is valid (no undefineds) for all
 389           - changes.  Returns a tree fragment including the string 'fail'
 390           - upon failure.
 391           -->
 392
 393         <xsl:template name="categories-valid">
 394           <xsl:param name="changes"/>
 395           <xsl:param name="fragment"/>
 396             <xsl:for-each select="$changes">
 397               <xsl:variable name="category">
 398                 <xsl:call-template name="get-change-category">
 399                   <xsl:with-param name="change" select="."/>
 400                   <xsl:with-param name="fragment" select="$fragment"/>
 401                 </xsl:call-template>
 402               </xsl:variable>
 403
 404               <xsl:if test="$category = ''">
 405                 <xsl:text>fail: </xsl:text>
 406                 <apply-templates select="."/>
 407               </xsl:if>
 408             </xsl:for-each>
 409         </xsl:template>
 410
 411         <!--
 412           - make a map unique
 413           -->
 414         <xsl:template name="make-map-unique">
 415           <xsl:param name="map"/>
 416           <xsl:param name="map-prefix"/>
 417
 418           <xsl:choose>
 419             <xsl:when test="$map = ''">
 420             </xsl:when>
 421             <xsl:when test="contains($map-prefix, substring-before($map, ':'))">
 422               <xsl:call-template name="make-map-unique">
 423                 <xsl:with-param name="map" select="substring-after($map, ' ')"/>
 424                 <xsl:with-param name="map-prefix" select="$map-prefix"/>
 425               </xsl:call-template>
 426             </xsl:when>
 427             <xsl:otherwise>
 428               <xsl:value-of select="substring-before($map, ' ')"/>
 429               <xsl:text> </xsl:text>
 430               <xsl:call-template name="make-map-unique">
 431                 <xsl:with-param name="map" select="substring-after($map, ' ')"/>
 432                 <xsl:with-param name="map-prefix" select="concat($map-prefix, substring-before($map, ' '))"/>
 433               </xsl:call-template>
 434             </xsl:otherwise>
 435           </xsl:choose>
 436         </xsl:template>
 437
 438         <!--
 439           - Attempt to map all changes to sublevels
 440           -->
 441
 442         <xsl:template name="map-changes-to-sublevels">
 443           <xsl:param name="taxonomy"/>
 444           <xsl:param name="changes"/>
 445
 446           <xsl:variable name="non-unique-map">
 447           <xsl:for-each select="$taxonomy">
 448             <xsl:sort select="@match-priority" order="descending"/>
 449
 450               <xsl:variable name="category" select="."/>
 451
 452               <xsl:variable name="keywords" select=".//keyword"/>
 453
 454                 <xsl:for-each select="$changes">
 455
 456                   <xsl:variable name="change" select="."/>
 457
 458                   <xsl:choose>
 459                     <xsl:when test="name($category) = name(.)">
 460                       <xsl:call-template name="write-change-category">
 461                         <xsl:with-param name="change" select="."/>
 462                         <xsl:with-param name="category" select="$category"/>
 463                       </xsl:call-template>
 464                     </xsl:when>
 465                     <xsl:when test="count(key('word-map', $keywords/child::text()))
 466                                   = count(key('word-map', $keywords/child::text())|.)">
 467                       <xsl:call-template name="write-change-category">
 468                         <xsl:with-param name="change" select="."/>
 469                         <xsl:with-param name="category" select="$category"/>
 470                       </xsl:call-template>
 471                     </xsl:when>
 472                   </xsl:choose>
 473                 </xsl:for-each>
 474               </xsl:for-each>
 475             </xsl:variable>
 476
 477             <xsl:call-template name="make-map-unique">
 478               <xsl:with-param name="map" select="$non-unique-map"/>
 479             </xsl:call-template>
 480         </xsl:template>
 481
 482         <!--
 483           - Write changes
 484           -->
 485
 486         <xsl:template name="write-changes">
 487           <xsl:param name="taxonomy"/>
 488           <xsl:param name="changes"/>
 489
 490           <!--
 491             - Attempt to map changes to sublevels
 492             -->
 493
 494           <xsl:variable name="map">
 495             <xsl:call-template name="map-changes-to-sublevels">
 496               <xsl:with-param name="taxonomy" select="$taxonomy"/>
 497               <xsl:with-param name="changes" select="$changes"/>
 498             </xsl:call-template>
 499           </xsl:variable>
 500
 501           <xsl:variable name="map-failures">
 502             <xsl:call-template name="categories-valid">
 503               <xsl:with-param name="changes" select="$changes"/>
 504               <xsl:with-param name="fragment" select="$map"/>
 505             </xsl:call-template>
 506           </xsl:variable>
 507
 508           <xsl:choose>
 509             <xsl:when test="contains($map-failures, 'fail')">
 510
 511               <!--
 512                 - In case of failure, insert all nodes at the current level.
 513                 -->
 514
 515               <itemizedlist>
 516                 <xsl:apply-templates select="$changes"/>
 517               </itemizedlist>
 518
 519             </xsl:when>
 520             <xsl:otherwise>
 521
 522               <!--
 523                 - In case of success, insert all nodes within sublevels.
 524                 -->
 525
 526               <xsl:for-each select="$taxonomy">
 527                 <xsl:variable name="category" select="."/>
 528                 <xsl:if test="contains($map, concat(generate-id($category), ' '))">
 529                   <section tocexclude="1">
 530                     <xsl:call-template name="write_title">
 531                       <xsl:with-param name="title">
 532                         <xsl:choose>
 533                         <xsl:when test="@t != ''">
 534                           <xsl:value-of select="@t"/>
 535                         </xsl:when>
 536                         <xsl:otherwise>
 537                           <xsl:value-of select="translate(name($category), '-', ' ')"/>
 538                         </xsl:otherwise>
 539                         </xsl:choose>
 540                       </xsl:with-param>
 541                     </xsl:call-template>
 542                     <xsl:call-template name="write-changes">
 543                       <xsl:with-param name="taxonomy" select="$category/*"/>
 544                       <xsl:with-param name="changes" select="$changes[name(.) = name($category)]/*|$changes[not(name(.) = name($category))][contains($map, concat(generate-id(.), ':', generate-id($category), ' '))]"/>
 545                     </xsl:call-template>
 546                   </section>
 547                 </xsl:if>
 548               </xsl:for-each>
 549
 550             </xsl:otherwise>
 551
 552           </xsl:choose>
 553
 554         </xsl:template>
 555
 556         <!--
 557           - Release
 558           -->
 559
 560         <xsl:template match="release" name="release">
 561             <xsl:param name="label" select="1"/>
 562             <section label="{$label}">
 563             <!-- <section label="{@version}"> -->
 564                 <xsl:choose>
 565                   <xsl:when test="@date">
 566                     <title>
 567                       <xsl:text>Version </xsl:text>
 568                       <xsl:value-of select="@version"/>
 569                       <xsl:text>, </xsl:text>
 570                       <xsl:value-of select="@date"/>
 571                     </title>
 572                   </xsl:when>
 573                   <xsl:otherwise>
 574                     <title>
 575                       <xsl:text>Version </xsl:text>
 576                       <xsl:value-of select="@version"/>
 577                     </title>
 578                   </xsl:otherwise>
 579                 </xsl:choose>
 580
 581                 <!--
 582                   - Notes
 583                   -->
 584
 585                 <xsl:apply-templates select=".//note"/>
 586
 587                 <!--
 588                   - Write changes according to the change taxonomy
 589                   -->
 590
 591                 <xsl:call-template name="write-changes">
 592                   <xsl:with-param name="taxonomy" select="$taxonomy-root/taxonomy/*"/>
 593                   <xsl:with-param name="changes" select="./*[name() != 'edit']"/>
 594                 </xsl:call-template>
 595             </section>
 596         </xsl:template>
 597
 598         <xsl:template match="changelog">
 599           <xsl:for-each select="release">
 600             <xsl:call-template name="release">
 601               <xsl:with-param name="label" select="count(../release) - position()"/>
 602             </xsl:call-template>
 603           </xsl:for-each>
 604         </xsl:template>
 605
 606         <!--
 607           -  Abbreviations for DocBook elements.
 608           -->
 609
 610         <xsl:template match="ul">
 611         <itemizedlist>
 612           <xsl:apply-templates/>
 613         </itemizedlist>
 614         </xsl:template>
 615
 616         <xsl:template match="li">
 617         <listitem>
 618           <xsl:apply-templates/>
 619         </listitem>
 620         </xsl:template>
 621
 622         <xsl:template match="s">
 623         <section>
 624           <xsl:apply-templates/>
 625         </section>
 626         </xsl:template>
 627
 628
 629 </xsl:stylesheet>