README: migrate to the documentation subdirectory.
[Ale.git] / doc / ale-doc.xsl
blob99119f1c685b2d54c8c284d02b3b9bcf984458a2
1 <!--
2 - Copyright 2006 David Hilvert
3 -
4 - ALE documentation stylesheet definition.
6 - This file is part of the Anti-Lamenessing Engine documentation.
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.
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.
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 -->
23 <!DOCTYPE xsl:stylesheet [
25 <!--
26 - Entities
27 -->
29 <!--
30 - Character classes
31 -->
33 <!ENTITY uppercase "'ABCDEFGHIJKLMNOPQRSTUVWXYZ'">
34 <!ENTITY lowercase "'abcdefghijklmnopqrstuvwxyz'">
36 <!--
38 - NOTE: the below entities operate on edit records, which
39 - are expected to conform to exactly one of the following patterns:
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">
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 -->
53 <!--
54 - Obtain an editor name from an edit record.
55 -->
57 <!ENTITY editor 'normalize-space(@by)'>
59 <!--
60 - Obtain an edit year from an edit record.
61 -->
63 <!ENTITY year 'concat(@in-year, substring-before(@in-month, "-"), substring-before(@on, "-"))'>
65 <!--
66 - Generate a string unique for each (editor, year) combination.
67 -->
69 <!ENTITY editor-year 'concat(&editor;, &year;)'>
71 <!--
72 - Boolean test to determine whether the current node is within the scope of
73 - $objectroot.
74 -->
76 <!ENTITY scope 'count(ancestor::node()|$objectroot) = count(ancestor::node())'>
78 <!--
79 - Editor first name.
80 -->
82 <!ENTITY editor-firstname 'substring-before(&editor;, " ")'>
84 <!--
85 - Editor last name
86 -->
88 <!ENTITY editor-surname 'substring-after(&editor;, " ")'>
90 <!--
91 - Sort order for outputs including editor names.
92 -->
94 <!ENTITY editor-sort-order '&editor-surname;'>
96 <!--
97 - Sort order for years
98 -->
100 <!ENTITY year-sort-order '&year;'>
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">
110 <!--
111 - Product information
114 <xsl:param name="product-name" select="'ALE'"/>
115 <xsl:param name="product-version" select="'0.8.5-prerelease'"/>
116 <xsl:param name="site-URL" select="
117 concat('http://auricle.dyndns.org/', $product-name, '/')"/>
118 <xsl:param name="download-URL" select="concat($site-URL, 'download/')"/>
119 <xsl:param name="windows-binary-package-name" select="
120 concat(translate($product-name, &uppercase;, &lowercase;), '-',
121 translate($product-version, '.', '_'), '-win32.zip')"/>
122 <xsl:param name="source-package-name" select="
123 concat(translate($product-name, &uppercase;, &lowercase;), '-', $product-version)"/>
124 <xsl:param name="source-package-name-tar-gz" select="
125 concat($source-package-name, '.tar.gz')"/>
126 <xsl:param name="windows-binary-URL" select="concat($site-URL, $windows-binary-package-name)"/>
127 <xsl:param name="source-URL" select="concat($site-URL, $source-package-name-tar-gz)"/>
129 <!--
130 - License information
133 <xsl:template match="*|/" mode="license-terms">
134 <para>
135 This <xsl:apply-templates select="." mode="document-type"/> is free
136 documentation; you can redistribute it and/or modify it under the
137 terms of the GNU General Public License as published by the Free
138 Software Foundation; either version 2 of the License, or (at your
139 option) any later version.
140 </para>
141 </xsl:template>
143 <xsl:template match="*|/" mode="license-object">
144 <para>
145 Unless explicitly defined within the applicable version of the GNU
146 General Public License, any references to "object code" within the
147 license shall refer to any non-source version of this
148 <xsl:apply-templates select="." mode="document-type"/> (or of any
149 work based on this <xsl:apply-templates select="."
150 mode="document-type"/>).
151 </para>
152 </xsl:template>
154 <xsl:template match="*|/" mode="license-warranty">
155 <para>
156 This <xsl:apply-templates select="." mode="document-type"/> is
157 distributed in the hope that it will be useful, but WITHOUT ANY
158 WARRANTY; without even the implied warranty of MERCHANTABILITY or
159 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
160 for more details.
161 </para>
162 </xsl:template>
164 <xsl:template match="*|/" mode="license-availability">
165 <para>
166 You should have received a copy of the GNU General Public License
167 along with this <xsl:apply-templates select="."
168 mode="document-type"/>; if not, write to the Free Software
169 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
170 02110-1301, USA.
171 </para>
172 </xsl:template>
174 <xsl:template match="*|/" mode="license">
175 <legalnotice>
176 <xsl:apply-templates select="." mode="license-terms"/>
177 <xsl:apply-templates select="." mode="license-warranty"/>
178 <xsl:apply-templates select="." mode="license-availability"/>
179 <xsl:apply-templates select="." mode="license-object"/>
180 </legalnotice>
181 </xsl:template>
183 <!--
184 - Editing information
187 <xsl:key name="editors" match="edit" use="&editor;"/>
188 <xsl:key name="editor-years" match="edit" use="&editor-year;"/>
190 <!--
191 - If no other template matches, we copy the tree structure unchanged.
194 <xsl:template match="@*|node()">
195 <xsl:copy>
196 <xsl:apply-templates select="@*|node()"/>
197 </xsl:copy>
198 </xsl:template>
200 <!--
201 - Do not pass edit tags to DocBook, as it doesn't understand them.
204 <xsl:template match="edit"/>
206 <!--
207 - Capitalize the initial letter of titles.
210 <xsl:template name="write_title">
211 <xsl:param name="product-name"/>
212 <xsl:param name="product-version"/>
213 <xsl:param name="title" select="."/>
215 <xsl:variable name="space-stripped-title" select="normalize-space($title)"/>
216 <xsl:variable name="initial" select="substring($space-stripped-title, 1, 1)"/>
217 <xsl:variable name="sequel" select="substring($space-stripped-title, 2)"/>
219 <title>
221 <xsl:copy-of select="$product-name"/>
222 <xsl:text> </xsl:text>
223 <xsl:copy-of select="$product-version"/>
224 <xsl:text> </xsl:text>
225 <xsl:copy-of select="concat(translate($initial, &lowercase;, &uppercase;), $sequel)"/>
227 </title>
228 </xsl:template>
230 <xsl:template match="text()" mode="title">
231 <xsl:call-template name="write_title">
232 <xsl:with-param name="title" select="."/>
233 </xsl:call-template>
234 </xsl:template>
236 <!--
237 - Titles other than article, book and set titles.
240 <xsl:template match="title|t">
241 <xsl:apply-templates select="text()" mode="title"/>
242 </xsl:template>
244 <!--
245 - Add package information to titles of articles, books and sets.
248 <xsl:template match="setinfo/title|bookinfo/title|articleinfo/title|setinfo/t|bookinfo/t|articleinfo/t">
249 <xsl:call-template name="write_title">
250 <xsl:with-param name="product-name" select="$product-name"/>
251 <xsl:with-param name="product-version" select="$product-version"/>
252 <xsl:with-param name="title" select="text()"/>
253 </xsl:call-template>
254 </xsl:template>
256 <!--
257 - Generate title, author, copyright, and license information for
258 - articles, books and sets.
261 <xsl:template match="setinfo" mode="document-type">
262 <xsl:text>set</xsl:text>
263 </xsl:template>
265 <xsl:template match="bookinfo" mode="document-type">
266 <xsl:text>book</xsl:text>
267 </xsl:template>
269 <xsl:template match="articleinfo" mode="document-type">
270 <xsl:text>article</xsl:text>
271 </xsl:template>
273 <xsl:template match="setinfo|bookinfo|articleinfo">
274 <xsl:copy>
275 <xsl:param name="objectroot" select=".."/>
276 <xsl:param name="editors-unique" select="$objectroot//edit[count(.|key('editors', &editor;)[&scope;][1]) = 1]"/>
277 <xsl:param name="editor-years-unique" select="$objectroot//edit[count(.|key('editor-years', &editor-year;)[&scope;][1]) = 1]"/>
279 <!--
280 - Generate the title, if available.
283 <xsl:apply-templates select="title|t"/>
285 <!--
286 - Preserve abstracts.
289 <xsl:apply-templates select="abstract"/>
291 <!--
292 - Add author information.
295 <xsl:for-each select="$editors-unique">
296 <xsl:sort select="&editor-sort-order;"/>
297 <author>
298 <firstname>
299 <xsl:value-of select="&editor-firstname;"/>
300 </firstname>
301 <surname>
302 <xsl:value-of select="&editor-surname;"/>
303 </surname>
304 </author>
305 </xsl:for-each>
307 <!--
308 - Add copyright information
311 <xsl:for-each select="$editors-unique">
312 <xsl:sort select="&editor-sort-order;"/>
313 <xsl:param name="this-editor" select="&editor;"/>
314 <copyright>
315 <holder>
316 <xsl:value-of select="&editor;"/>
317 </holder>
318 <xsl:for-each select="$editor-years-unique">
319 <xsl:sort select="&year-sort-order;"/>
320 <xsl:if test="&editor; = $this-editor">
321 <year>
322 <xsl:value-of select="&year;"/>
323 </year>
324 </xsl:if>
325 </xsl:for-each>
326 </copyright>
327 </xsl:for-each>
330 <!--
331 - Add a license notice
334 <xsl:apply-templates select="." mode="license"/>
336 </xsl:copy>
337 </xsl:template>
339 <!--
340 - Changelogs and news files.
343 <!--
344 - Changelog item
347 <xsl:template match="entry">
348 <listitem>
349 <xsl:apply-templates select="text/text()"/>
350 </listitem>
351 </xsl:template>
353 <!--
354 - Keys
357 <xsl:key name="word-map" match="entry" use="word/child::text()"/>
359 <!--
360 - Taxonomy
363 <xsl:variable name="taxonomy-root" select="document('taxonomy.xmli')"/>
365 <!--
366 - Write a fragment substring for a (change, category) pair.
369 <xsl:template name="write-change-category">
370 <xsl:param name="change"/>
371 <xsl:param name="category"/>
372 <xsl:value-of select="concat(generate-id($change), ':', generate-id($category), ' ')"/>
373 </xsl:template>
375 <!--
376 - Get a change category from a fragment result
379 <xsl:template name="get-change-category">
380 <xsl:param name="change"/>
381 <xsl:param name="fragment"/>
382 <xsl:value-of select="substring-before(substring-after(substring-after($fragment, generate-id($change)), ':'), ' ')"/>
383 </xsl:template>
385 <!--
386 - Get a tree fragment with categories set to zero.
389 <xsl:template name="get-zero-categories">
390 <xsl:param name="changes"/>
391 <xsl:for-each select="$changes">
392 <xsl:call-template name="write-change-category">
393 <xsl:with-param name="change" select="."/>
394 <xsl:with-param name="category" select="$taxonomy-root"/>
395 </xsl:call-template>
396 </xsl:for-each>
397 </xsl:template>
399 <!--
400 - Determine whether a category tree is valid (no undefineds) for all
401 - changes. Returns a tree fragment including the string 'fail'
402 - upon failure.
405 <xsl:template name="categories-valid">
406 <xsl:param name="changes"/>
407 <xsl:param name="fragment"/>
408 <xsl:for-each select="$changes">
409 <xsl:variable name="category">
410 <xsl:call-template name="get-change-category">
411 <xsl:with-param name="change" select="."/>
412 <xsl:with-param name="fragment" select="$fragment"/>
413 </xsl:call-template>
414 </xsl:variable>
416 <xsl:if test="$category = ''">
417 <xsl:text>fail: </xsl:text>
418 <apply-templates select="."/>
419 </xsl:if>
420 </xsl:for-each>
421 </xsl:template>
423 <!--
424 - make a map unique
426 <xsl:template name="make-map-unique">
427 <xsl:param name="map"/>
428 <xsl:param name="map-prefix"/>
430 <xsl:choose>
431 <xsl:when test="$map = ''">
432 </xsl:when>
433 <xsl:when test="contains($map-prefix, substring-before($map, ':'))">
434 <xsl:call-template name="make-map-unique">
435 <xsl:with-param name="map" select="substring-after($map, ' ')"/>
436 <xsl:with-param name="map-prefix" select="$map-prefix"/>
437 </xsl:call-template>
438 </xsl:when>
439 <xsl:otherwise>
440 <xsl:value-of select="substring-before($map, ' ')"/>
441 <xsl:text> </xsl:text>
442 <xsl:call-template name="make-map-unique">
443 <xsl:with-param name="map" select="substring-after($map, ' ')"/>
444 <xsl:with-param name="map-prefix" select="concat($map-prefix, substring-before($map, ' '))"/>
445 </xsl:call-template>
446 </xsl:otherwise>
447 </xsl:choose>
448 </xsl:template>
450 <!--
451 - Attempt to map all changes to sublevels
454 <xsl:template name="map-changes-to-sublevels">
455 <xsl:param name="taxonomy"/>
456 <xsl:param name="changes"/>
458 <xsl:variable name="non-unique-map">
459 <xsl:for-each select="$taxonomy">
460 <xsl:sort select="@match-priority" order="descending"/>
462 <xsl:variable name="category" select="."/>
464 <xsl:variable name="keywords" select=".//keyword"/>
466 <xsl:for-each select="$changes">
468 <xsl:variable name="change" select="."/>
470 <xsl:choose>
471 <xsl:when test="name($category) = name(.)">
472 <xsl:call-template name="write-change-category">
473 <xsl:with-param name="change" select="."/>
474 <xsl:with-param name="category" select="$category"/>
475 </xsl:call-template>
476 </xsl:when>
477 <xsl:when test="count(key('word-map', $keywords/child::text()))
478 = count(key('word-map', $keywords/child::text())|.)">
479 <xsl:call-template name="write-change-category">
480 <xsl:with-param name="change" select="."/>
481 <xsl:with-param name="category" select="$category"/>
482 </xsl:call-template>
483 </xsl:when>
484 </xsl:choose>
485 </xsl:for-each>
486 </xsl:for-each>
487 </xsl:variable>
489 <xsl:call-template name="make-map-unique">
490 <xsl:with-param name="map" select="$non-unique-map"/>
491 </xsl:call-template>
492 </xsl:template>
494 <!--
495 - Write changes
498 <xsl:template name="write-changes">
499 <xsl:param name="taxonomy"/>
500 <xsl:param name="changes"/>
502 <!--
503 - Attempt to map changes to sublevels
506 <xsl:variable name="map">
507 <xsl:call-template name="map-changes-to-sublevels">
508 <xsl:with-param name="taxonomy" select="$taxonomy"/>
509 <xsl:with-param name="changes" select="$changes"/>
510 </xsl:call-template>
511 </xsl:variable>
513 <xsl:variable name="map-failures">
514 <xsl:call-template name="categories-valid">
515 <xsl:with-param name="changes" select="$changes"/>
516 <xsl:with-param name="fragment" select="$map"/>
517 </xsl:call-template>
518 </xsl:variable>
520 <xsl:choose>
521 <xsl:when test="contains($map-failures, 'fail')">
523 <!--
524 - In case of failure, insert all nodes at the current level.
527 <itemizedlist>
528 <xsl:apply-templates select="$changes"/>
529 </itemizedlist>
531 </xsl:when>
532 <xsl:otherwise>
534 <!--
535 - In case of success, insert all nodes within sublevels.
538 <xsl:for-each select="$taxonomy">
539 <xsl:variable name="category" select="."/>
540 <xsl:if test="contains($map, concat(generate-id($category), ' '))">
541 <section tocexclude="1">
542 <xsl:call-template name="write_title">
543 <xsl:with-param name="title">
544 <xsl:choose>
545 <xsl:when test="@t != ''">
546 <xsl:value-of select="@t"/>
547 </xsl:when>
548 <xsl:otherwise>
549 <xsl:value-of select="translate(name($category), '-', ' ')"/>
550 </xsl:otherwise>
551 </xsl:choose>
552 </xsl:with-param>
553 </xsl:call-template>
554 <xsl:call-template name="write-changes">
555 <xsl:with-param name="taxonomy" select="$category/*"/>
556 <xsl:with-param name="changes" select="$changes[name(.) = name($category)]/*|$changes[not(name(.) = name($category))][contains($map, concat(generate-id(.), ':', generate-id($category), ' '))]"/>
557 </xsl:call-template>
558 </section>
559 </xsl:if>
560 </xsl:for-each>
562 </xsl:otherwise>
564 </xsl:choose>
566 </xsl:template>
568 <!--
569 - News entries.
572 <xsl:template match="fm">
573 <para>
574 <xsl:choose>
575 <xsl:when test="@nh">
576 <xsl:apply-templates/><xsl:text> (Freshmeat blurb via Neohapsis)</xsl:text>
577 </xsl:when>
578 <xsl:otherwise>
579 <xsl:apply-templates/><xsl:text> (Freshmeat blurb)</xsl:text>
580 </xsl:otherwise>
581 </xsl:choose>
582 </para>
583 </xsl:template>
585 <xsl:template match="sum">
586 <section tocexclude="1"><title>Program summary</title>
587 <xsl:if test="@revised">
588 <para>This release includes a revised summary:</para>
589 <!-- This release is accompanied by a revised summary: -->
590 </xsl:if>
591 <para>
592 <xsl:apply-templates/>
593 </para>
594 </section>
595 </xsl:template>
597 <xsl:template match="ed-note">
598 <xsl:apply-templates/>
599 </xsl:template>
601 <xsl:template match="notes">
602 <section tocexclude="1"><title>Notes</title>
603 <para>
604 <xsl:apply-templates/>
605 </para>
606 </section>
607 </xsl:template>
609 <xsl:template match="ch">
610 <section tocexclude="1"><title>Changelog summary</title>
611 <xsl:apply-templates/>
612 </section>
613 </xsl:template>
615 <xsl:template match="ml">
616 <section tocexclude="1"><title>Mailing list announcement</title>
617 <xsl:apply-templates/>
618 </section>
619 </xsl:template>
621 <!--
622 - Releases
625 <xsl:template match="release" name="release-news" mode="news">
626 <xsl:param name="label" select="1"/>
627 <section label="{$label}">
628 <!-- <section label="{@version}"> -->
629 <xsl:choose>
630 <xsl:when test="@date">
631 <title>
632 <xsl:text>Version </xsl:text>
633 <xsl:value-of select="@version"/>
634 <xsl:text>, </xsl:text>
635 <xsl:value-of select="@date"/>
636 </title>
637 </xsl:when>
638 <xsl:otherwise>
639 <title>
640 <xsl:text>Version </xsl:text>
641 <xsl:value-of select="@version"/>
642 </title>
643 </xsl:otherwise>
644 </xsl:choose>
646 <!--
647 - Notes
650 <xsl:apply-templates select=".//note"/>
652 <!--
653 - Write subsections.
656 <xsl:apply-templates/>
658 </section>
659 </xsl:template>
661 <xsl:template match="release" name="release-changelog" mode="changelog">
662 <xsl:param name="label" select="1"/>
663 <section label="{$label}">
664 <!-- <section label="{@version}"> -->
665 <xsl:choose>
666 <xsl:when test="@date">
667 <title>
668 <xsl:text>Version </xsl:text>
669 <xsl:value-of select="@version"/>
670 <xsl:text>, </xsl:text>
671 <xsl:value-of select="@date"/>
672 </title>
673 </xsl:when>
674 <xsl:otherwise>
675 <title>
676 <xsl:text>Version </xsl:text>
677 <xsl:value-of select="@version"/>
678 </title>
679 </xsl:otherwise>
680 </xsl:choose>
682 <!--
683 - Notes
686 <xsl:apply-templates select=".//note"/>
688 <!--
689 - Write changes according to the change taxonomy
692 <xsl:call-template name="write-changes">
693 <xsl:with-param name="taxonomy" select="$taxonomy-root/taxonomy/*"/>
694 <xsl:with-param name="changes" select="./*[name() != 'edit']"/>
695 </xsl:call-template>
696 </section>
697 </xsl:template>
699 <xsl:template match="news">
700 <xsl:for-each select="release">
701 <xsl:call-template name="release-news">
702 <xsl:with-param name="label" select="count(../release) - position()"/>
703 </xsl:call-template>
704 </xsl:for-each>
705 </xsl:template>
707 <xsl:template match="changelog">
708 <xsl:for-each select="release">
709 <xsl:call-template name="release-changelog" mode="changelog">
710 <xsl:with-param name="label" select="count(../release) - position()"/>
711 </xsl:call-template>
712 </xsl:for-each>
713 </xsl:template>
715 <!--
716 - Inline product information
719 <xsl:template match="winpack">
720 <xsl:value-of select="$windows-binary-package-name"/>
721 </xsl:template>
723 <xsl:template match="sourcepack">
724 <xsl:value-of select="$source-package-name"/>
725 </xsl:template>
727 <xsl:template match="sourcepacktargz">
728 <xsl:value-of select="$source-package-name-tar-gz"/>
729 </xsl:template>
731 <xsl:template match="winurl">
732 <ulink url="{$windows-binary-URL}"/>
733 </xsl:template>
735 <xsl:template match="sourceurl">
736 <ulink url="{$source-URL}"/>
737 </xsl:template>
739 <!--
740 - Abbreviations for DocBook elements.
743 <xsl:template match="p">
744 <para>
745 <xsl:apply-templates/>
746 </para>
747 </xsl:template>
749 <xsl:template match="ul">
750 <itemizedlist>
751 <xsl:apply-templates/>
752 </itemizedlist>
753 </xsl:template>
755 <xsl:template match="li">
756 <listitem>
757 <xsl:apply-templates/>
758 </listitem>
759 </xsl:template>
761 <xsl:template match="s">
762 <section>
763 <xsl:apply-templates/>
764 </section>
765 </xsl:template>
767 <xsl:template match="ll">
768 <literallayout class="monospaced">
769 <xsl:apply-templates/>
770 </literallayout>
771 </xsl:template>
774 </xsl:stylesheet>