Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/tools/boostbook/xsl/function.xsl @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 43.2 KB
RevLine 
[29]1<?xml version="1.0" encoding="utf-8"?>
2<!--
3   Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com>
4 
5   Distributed under the Boost Software License, Version 1.0.
6   (See accompanying file LICENSE_1_0.txt or copy at
7   http://www.boost.org/LICENSE_1_0.txt)
8  -->
9<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
10                version="1.0">
11
12  <xsl:strip-space elements="requires effects postconditions returns throws
13                             complexity notes rationale purpose"/>
14
15  <!-- When true, the stylesheet will emit compact definitions of
16       functions when the function does not have any detailed
17       description. -->
18  <xsl:param name="boost.compact.function">1</xsl:param>
19
20  <!-- The longest type length that is considered "short" for the
21       layout of function return types. When the length of the result type
22       and any storage specifiers is greater than this length, they will be
23       placed on a separate line from the function name and parameters
24       unless everything fits on a single line. -->
25  <xsl:param name="boost.short.result.type">12</xsl:param>
26
27  <!-- Display a function declaration -->
28  <xsl:template name="function">
29    <xsl:param name="indentation"/>
30    <xsl:param name="is-reference"/>
31
32    <!-- Whether or not we should include parameter names in the output -->
33    <xsl:param name="include-names" select="$is-reference"/>
34
35    <!-- What type of link the function name should have. This shall
36         be one of 'anchor' (the function output will be the target of
37         links), 'link' (the function output will link to a definition), or
38         'none' (the function output will not be either a link or a link
39         target) -->
40    <xsl:param name="link-type">
41      <xsl:choose>
42        <xsl:when test="$is-reference">
43          <xsl:text>anchor</xsl:text>
44        </xsl:when>
45        <xsl:otherwise>
46          <xsl:text>link</xsl:text>
47        </xsl:otherwise>
48      </xsl:choose>
49    </xsl:param>
50
51    <!-- The id we should link to or anchor as -->
52    <xsl:param name="link-to">
53      <xsl:call-template name="generate.id"/>
54    </xsl:param>
55
56    <!-- If we are printing a constructor -->
57    <xsl:param name="constructor-for"/>
58
59    <!-- If we are printing a destructor -->
60    <xsl:param name="destructor-for"/>
61
62    <!-- If we are printing a copy assignment operator -->
63    <xsl:param name="copy-assign-for"/>
64
65    <!-- The name of this function -->
66    <xsl:param name="name" select="@name"/>
67
68    <!-- True if this is the function's separate documentation -->
69    <xsl:param name="standalone" select="false()"/>
70
71    <!-- True if we should suppress the template header -->
72    <xsl:param name="suppress-template" select="false()"/>
73
74    <!-- Calculate the specifiers -->
75    <xsl:variable name="specifiers">
76      <xsl:if test="@specifiers">
77        <xsl:value-of select="concat(@specifiers, ' ')"/>
78      </xsl:if>
79    </xsl:variable>
80
81    <!-- Calculate the type -->
82    <xsl:variable name="type">
83      <xsl:value-of select="$specifiers"/>
84
85      <xsl:choose>
86        <!-- Conversion operators have an empty type, because the return
87             type is part of the name -->
88        <xsl:when test="$name='conversion-operator'"/>
89
90        <!-- Constructors and destructors have no return type -->
91        <xsl:when test="$constructor-for or $destructor-for"/>
92
93        <!-- Copy assignment operators return a reference to the class
94             they are in, unless another type has been explicitly
95             provided in the element. -->
96        <xsl:when test="$copy-assign-for and not(type)">
97          <xsl:value-of select="concat($copy-assign-for, '&amp; ')"/>
98        </xsl:when>
99
100        <xsl:otherwise>
101          <xsl:apply-templates select="type" mode="annotation"/>
102          <xsl:text> </xsl:text>
103        </xsl:otherwise>
104      </xsl:choose>
105    </xsl:variable>
106
107    <!-- Build the function name with return type -->
108    <xsl:variable name="function-name">
109      <xsl:choose>
110        <xsl:when test="$constructor-for">
111          <xsl:value-of select="$constructor-for"/>
112        </xsl:when>
113        <xsl:when test="$destructor-for">
114          <xsl:value-of select="concat('~',$destructor-for)"/>
115        </xsl:when>
116        <xsl:when test="$copy-assign-for">
117          <xsl:value-of select="'operator='"/>
118        </xsl:when>
119        <xsl:when test="$name='conversion-operator'">
120          <xsl:text>operator </xsl:text>
121          <xsl:apply-templates select="type" mode="annotation"/>
122        </xsl:when>
123        <xsl:otherwise>
124          <xsl:value-of select="$name"/>
125        </xsl:otherwise>
126      </xsl:choose>
127    </xsl:variable>
128
129    <xsl:if test="not ($standalone) or
130                  (local-name(.)='signature' and (position() &gt; 1))
131                  or $suppress-template">
132      <xsl:text>&#10;</xsl:text>
133    </xsl:if>
134
135    <!-- Indent this declaration -->
136    <xsl:call-template name="indent">
137      <xsl:with-param name="indentation" select="$indentation"/>
138    </xsl:call-template>
139   
140    <!-- Build the template header -->
141    <xsl:variable name="template-length">
142      <xsl:choose>
143        <xsl:when test="$suppress-template">
144          0
145        </xsl:when>
146        <xsl:otherwise>
147          <xsl:call-template name="template.synopsis.length"/>
148        </xsl:otherwise>
149      </xsl:choose>
150    </xsl:variable>
151       
152    <!-- Build a full parameter string (without line breaks) -->
153    <xsl:variable name="param-string">
154      <xsl:text>(</xsl:text>
155      <xsl:call-template name="function-parameters">
156        <xsl:with-param name="include-names" select="$include-names"/>
157        <xsl:with-param name="wrap" select="false()"/>
158      </xsl:call-template>
159      <xsl:text>)</xsl:text>
160    </xsl:variable>
161
162    <!-- Build the text that follows the declarator-->
163    <xsl:variable name="postdeclarator">
164      <xsl:if test="@cv">
165        <xsl:text> </xsl:text>
166        <xsl:value-of select="@cv"/>
167      </xsl:if>
168    </xsl:variable>
169
170    <!-- Build the full declaration text -->
171    <xsl:variable name="decl-string" 
172      select="concat($type, $function-name, $param-string, $postdeclarator)"/>
173    <xsl:variable name="end-column" 
174      select="$template-length + string-length($decl-string) + $indentation"/>
175   
176    <xsl:choose>
177      <!-- Check if we should put the template header on its own line to
178           save horizontal space. -->
179      <xsl:when test="($template-length &gt; 0) and
180                      ($end-column &gt; $max-columns)">
181        <!-- Emit template header on its own line -->
182        <xsl:apply-templates select="template" mode="synopsis">
183          <xsl:with-param name="indentation" select="$indentation"/>
184        </xsl:apply-templates>
185       
186        <!-- Emit the rest of the function declaration (without the
187             template header) indented two extra spaces. -->
188        <xsl:call-template name="function">
189          <xsl:with-param name="indentation" select="$indentation + 2"/>
190          <xsl:with-param name="is-reference" select="$is-reference"/>
191          <xsl:with-param name="include-names" select="$include-names"/>
192          <xsl:with-param name="link-type" select="$link-type"/>
193          <xsl:with-param name="link-to" select="$link-to"/>
194          <xsl:with-param name="constructor-for" select="$constructor-for"/>
195          <xsl:with-param name="destructor-for" select="$destructor-for"/>
196          <xsl:with-param name="copy-assign-for" select="$copy-assign-for"/>
197          <xsl:with-param name="name" select="$name"/>
198          <xsl:with-param name="standalone" select="$standalone"/>
199          <xsl:with-param name="suppress-template" select="true()"/>
200        </xsl:call-template>
201      </xsl:when>
202
203      <!-- Check if we can put the entire declaration on a single
204           line. -->
205      <xsl:when test="not($end-column &gt; $max-columns)">
206        <!-- Emit template header, if not suppressed -->
207        <xsl:if test="not($suppress-template)">
208          <xsl:apply-templates select="template" mode="synopsis">
209            <xsl:with-param name="indentation" select="$indentation"/>
210            <xsl:with-param name="wrap" select="false()"/>
211            <xsl:with-param name="highlight" select="true()"/>
212          </xsl:apply-templates>
213        </xsl:if>
214
215        <!-- Emit specifiers -->
216        <xsl:call-template name="source-highlight">
217          <xsl:with-param name="text" select="$specifiers"/>
218        </xsl:call-template>
219
220        <!-- Emit type, if any -->
221        <xsl:choose>
222          <!-- Conversion operators have an empty type, because the return
223               type is part of the name -->
224          <xsl:when test="$name='conversion-operator'"/>
225
226          <!-- Constructors and destructors have no return type -->
227          <xsl:when test="$constructor-for or $destructor-for"/>
228
229          <!-- Copy assignment operators return a reference to the class
230               they are in, unless another type has been explicitly
231               provided in the element. -->
232          <xsl:when test="$copy-assign-for and not(type)">
233            <xsl:value-of select="concat($copy-assign-for, '&amp; ')"/>
234          </xsl:when>
235
236          <xsl:otherwise>
237            <xsl:apply-templates select="type" mode="highlight"/>
238            <xsl:text> </xsl:text>
239          </xsl:otherwise>
240        </xsl:choose>
241
242        <xsl:call-template name="link-or-anchor">
243          <xsl:with-param name="to" select="$link-to"/>
244          <xsl:with-param name="text" select="$function-name"/>
245          <xsl:with-param name="link-type" select="$link-type"/>
246          <xsl:with-param name="highlight" select="true()"/>
247        </xsl:call-template>
248
249        <xsl:text>(</xsl:text>
250        <xsl:call-template name="function-parameters">
251          <xsl:with-param name="include-names" select="$include-names"/>
252          <xsl:with-param name="indentation" 
253            select="$indentation + $template-length + string-length($type)
254                    + string-length($function-name) + 1"/>
255          <xsl:with-param name="final" select="true()"/>
256        </xsl:call-template>               
257        <xsl:text>)</xsl:text>
258
259        <xsl:call-template name="source-highlight">
260          <xsl:with-param name="text" select="$postdeclarator"/>
261        </xsl:call-template>
262        <xsl:text>;</xsl:text>   
263      </xsl:when>
264
265      <!-- This declaration will take multiple lines -->
266      <xsl:otherwise>
267        <!-- Emit specifiers -->
268        <xsl:call-template name="source-highlight">
269          <xsl:with-param name="text" select="$specifiers"/>
270        </xsl:call-template>
271
272        <!-- Emit type, if any -->
273        <xsl:choose>
274          <!-- Conversion operators have an empty type, because the return
275               type is part of the name -->
276          <xsl:when test="$name='conversion-operator'"/>
277
278          <!-- Constructors and destructors have no return type -->
279          <xsl:when test="$constructor-for or $destructor-for"/>
280
281          <!-- Copy assignment operators return a reference to the class
282               they are in, unless another type has been explicitly
283               provided in the element. -->
284          <xsl:when test="$copy-assign-for and not(type)">
285            <xsl:value-of select="concat($copy-assign-for, '&amp; ')"/>
286          </xsl:when>
287
288          <xsl:otherwise>
289            <xsl:apply-templates select="type" mode="highlight"/>
290            <xsl:text> </xsl:text>
291          </xsl:otherwise>
292        </xsl:choose>
293
294        <xsl:if test="string-length($type) &gt; $boost.short.result.type">
295          <xsl:text>&#10;</xsl:text>
296          <xsl:call-template name="indent">
297            <xsl:with-param name="indentation" select="$indentation"/>
298          </xsl:call-template>
299        </xsl:if>
300
301        <!-- Determine how many columns the type and storage
302             specifiers take on the same line as the function name. -->
303        <xsl:variable name="type-length">
304          <xsl:choose>
305            <xsl:when test="string-length($type) &gt; $boost.short.result.type">
306              0
307            </xsl:when>
308            <xsl:otherwise>
309              <xsl:value-of select="string-length($type)"/>
310            </xsl:otherwise>
311          </xsl:choose>
312        </xsl:variable>
313
314        <xsl:call-template name="link-or-anchor">
315          <xsl:with-param name="to" select="$link-to"/>
316          <xsl:with-param name="text" select="$function-name"/>
317          <xsl:with-param name="link-type" select="$link-type"/>
318          <xsl:with-param name="highlight" select="true()"/>
319        </xsl:call-template>
320        <xsl:text>(</xsl:text>
321        <xsl:call-template name="function-parameters">
322          <xsl:with-param name="include-names" select="$include-names"/>
323          <xsl:with-param name="indentation" 
324            select="$indentation + $type-length
325                    + string-length($function-name) + 1"/>
326          <xsl:with-param name="final" select="true()"/>
327        </xsl:call-template>               
328        <xsl:text>)</xsl:text>
329        <xsl:call-template name="source-highlight">
330          <xsl:with-param name="text" select="$postdeclarator"/>
331        </xsl:call-template>
332        <xsl:text>;</xsl:text>
333      </xsl:otherwise>
334    </xsl:choose>
335  </xsl:template>   
336
337  <!-- Synopsis of function parameters, e.g., "(const T&, int x = 5)" -->
338  <xsl:template name="function-parameters">
339    <!-- Indentation level of this parameter list -->
340    <xsl:param name="indentation"/>
341
342    <!-- True if we should include parameter names -->
343    <xsl:param name="include-names" select="true()"/>
344
345    <!-- True if we should wrap function parameters to the next line -->
346    <xsl:param name="wrap" select="true()"/>
347
348    <!-- True if we are printing the final output -->
349    <xsl:param name="final" select="false()"/>
350
351    <!-- Internal: The prefix to emit before a parameter -->
352    <xsl:param name="prefix" select="''"/>
353
354    <!-- Internal: The list of parameters -->
355    <xsl:param name="parameters" select="parameter"/>
356
357    <!-- Internal: The column we are on -->
358    <xsl:param name="column" select="$indentation"/>
359
360    <!-- Internal: Whether this is the first parameter on this line or not -->
361    <xsl:param name="first-on-line" select="true()"/>
362
363    <xsl:if test="$parameters">
364      <!-- Information for this parameter -->
365      <xsl:variable name="parameter" select="$parameters[position()=1]"/>
366      <xsl:variable name="name">
367        <xsl:if test="$include-names and $parameter/@name != ''">
368          <xsl:text> </xsl:text><xsl:value-of select="$parameter/@name"/>
369        </xsl:if>
370      </xsl:variable>
371
372      <xsl:variable name="type" select="string($parameter/paramtype)"/>
373
374      <xsl:variable name="default">
375        <xsl:choose>
376          <xsl:when test="$parameter/@default">
377            <xsl:text> = </xsl:text>
378            <xsl:value-of select="$parameter/@default"/>
379          </xsl:when>
380          <xsl:when test="$parameter/default">
381            <xsl:text> = </xsl:text>
382            <xsl:choose>
383              <xsl:when test="$final">
384                <xsl:apply-templates
385                  select="$parameter/default/*|$parameter/default/text()"
386                  mode="annotation"/>
387              </xsl:when>
388              <xsl:otherwise>
389                <xsl:value-of select="string($parameter/default)"/>
390              </xsl:otherwise>
391            </xsl:choose>
392          </xsl:when>
393        </xsl:choose>
394      </xsl:variable>
395
396      <xsl:variable name="text" select="concat($type, $name, $default)"/>
397     
398      <xsl:variable name="end-column" 
399        select="$column + string-length($prefix) + string-length($text)"/>
400
401      <xsl:choose>
402        <!-- Parameter goes on this line -->
403        <xsl:when test="$first-on-line or ($end-column &lt; $max-columns)
404                        or not($wrap)">
405          <xsl:choose>
406            <xsl:when test="$final">
407              <xsl:value-of select="$prefix"/>
408              <xsl:apply-templates 
409                select="$parameter/paramtype/*|$parameter/paramtype/text()"
410                mode="annotation">
411                <xsl:with-param name="highlight" select="true()"/>
412              </xsl:apply-templates>
413              <xsl:value-of select="$name"/>
414              <xsl:copy-of select="$default"/>
415            </xsl:when>
416            <xsl:otherwise>
417              <xsl:value-of select="concat($prefix, $text)"/>
418            </xsl:otherwise>
419          </xsl:choose>
420
421          <xsl:call-template name="function-parameters">
422            <xsl:with-param name="indentation" select="$indentation"/>
423            <xsl:with-param name="include-names" select="$include-names"/>
424            <xsl:with-param name="wrap" select="$wrap"/>
425            <xsl:with-param name="final" select="$final"/>
426            <xsl:with-param name="parameters" 
427              select="$parameters[position()!=1]"/>
428            <xsl:with-param name="prefix" select="', '"/>
429            <xsl:with-param name="column" select="$end-column"/>
430            <xsl:with-param name="first-on-line" select="false()"/>
431          </xsl:call-template>
432        </xsl:when>
433        <!-- Parameter goes on next line -->
434        <xsl:otherwise>
435          <!-- The comma goes on this line -->
436          <xsl:value-of select="$prefix"/><xsl:text>&#10;</xsl:text>
437
438          <!-- Indent and print the parameter -->
439          <xsl:call-template name="indent">
440            <xsl:with-param name="indentation" select="$indentation"/>
441          </xsl:call-template>
442          <xsl:choose>
443            <xsl:when test="$final">
444              <xsl:apply-templates 
445                select="$parameter/paramtype/*|$parameter/paramtype/text()"
446                mode="annotation">
447                <xsl:with-param name="highlight" select="true()"/>
448              </xsl:apply-templates>
449              <xsl:value-of select="$name"/>
450              <xsl:value-of select="$default"/>
451            </xsl:when>
452            <xsl:otherwise>
453              <xsl:value-of select="concat($prefix, $text)"/>
454            </xsl:otherwise>
455          </xsl:choose>
456
457          <!-- Emit next parameter -->
458          <xsl:call-template name="function-parameters">
459            <xsl:with-param name="indentation" select="$indentation"/>
460            <xsl:with-param name="include-names" select="$include-names"/>
461            <xsl:with-param name="wrap" select="$wrap"/>
462            <xsl:with-param name="final" select="$final"/>
463            <xsl:with-param name="parameters" 
464              select="$parameters[position()!=1]"/>
465            <xsl:with-param name="prefix" select="', '"/>
466            <xsl:with-param name="column" 
467              select="1 + string-length($text) + $indentation"/>
468            <xsl:with-param name="first-on-line" select="false()"/>
469          </xsl:call-template>
470        </xsl:otherwise>
471      </xsl:choose>
472    </xsl:if>
473  </xsl:template>
474
475  <!-- Function synopsis -->
476  <xsl:template match="function|method" mode="synopsis">
477    <xsl:param name="indentation"/>
478
479    <!-- True if we should compact this function -->
480    <xsl:variable name="compact"
481      select="not (para|description|requires|effects|postconditions|returns|
482                   throws|complexity|notes|rationale) and
483              ($boost.compact.function='1') and
484              not (local-name(.)='method')"/>
485
486    <xsl:choose>
487      <xsl:when test="$compact">
488        <xsl:if test="purpose">
489          <!-- Compact display outputs the purpose as a comment (if
490               there is one) and the entire function declaration. -->
491          <xsl:text>&#10;&#10;</xsl:text>
492          <xsl:call-template name="indent">
493            <xsl:with-param name="indentation" select="$indentation"/>
494          </xsl:call-template>
495
496          <xsl:call-template name="highlight-comment">
497            <xsl:with-param name="text">
498              <xsl:text>// </xsl:text>
499              <xsl:apply-templates select="purpose/*|purpose/text()"
500                mode="purpose"/>
501            </xsl:with-param>
502          </xsl:call-template>
503        </xsl:if>
504
505        <xsl:call-template name="function">
506          <xsl:with-param name="indentation" select="$indentation"/>
507          <xsl:with-param name="is-reference" select="true()"/>
508        </xsl:call-template>
509      </xsl:when>
510      <xsl:otherwise>
511        <xsl:call-template name="function">
512          <xsl:with-param name="indentation" select="$indentation"/>
513          <xsl:with-param name="is-reference" select="false()"/>
514        </xsl:call-template>
515      </xsl:otherwise>
516    </xsl:choose>
517  </xsl:template>
518
519  <xsl:template match="overloaded-function|overloaded-method" mode="synopsis">
520    <xsl:param name="indentation"/>
521
522    <xsl:variable name="name" select="@name"/>
523
524    <!-- True if we should compact this function -->
525    <xsl:variable name="compact"
526      select="not (para|description|requires|effects|postconditions|returns|
527                   throws|complexity|notes|rationale) and
528              ($boost.compact.function='1') and
529              not (local-name(.)='overloaded-method')"/>
530
531    <xsl:choose>
532      <xsl:when test="$compact">
533        <xsl:if test="purpose">
534          <!-- Compact display outputs the purpose as a comment (if
535               there is one) and the entire function declaration. -->
536          <xsl:text>&#10;</xsl:text>
537          <xsl:call-template name="indent">
538            <xsl:with-param name="indentation" select="$indentation"/>
539          </xsl:call-template>
540         
541          <xsl:call-template name="highlight-comment">
542            <xsl:with-param name="text">
543              <xsl:text>// </xsl:text>
544              <xsl:apply-templates select="purpose" mode="annotation"/>
545            </xsl:with-param>
546          </xsl:call-template>
547        </xsl:if>
548
549        <xsl:for-each select="signature">
550          <xsl:call-template name="function">
551            <xsl:with-param name="indentation" select="$indentation"/>
552            <xsl:with-param name="is-reference" select="true()"/>
553            <xsl:with-param name="name" select="$name"/>
554          </xsl:call-template>
555        </xsl:for-each>
556      </xsl:when>
557      <xsl:when test="local-name(..)='namespace'">
558        <xsl:variable name="link-to">
559          <xsl:call-template name="generate.id"/>
560        </xsl:variable>
561
562        <xsl:for-each select="signature">
563          <xsl:call-template name="function">
564            <xsl:with-param name="indentation" select="$indentation"/>
565            <xsl:with-param name="is-reference" select="false()"/>
566            <xsl:with-param name="name" select="$name"/>
567            <xsl:with-param name="link-to" select="$link-to"/>
568          </xsl:call-template>
569        </xsl:for-each>       
570      </xsl:when>
571      <xsl:otherwise>
572        <xsl:for-each select="signature">
573          <xsl:call-template name="function">
574            <xsl:with-param name="indentation" select="$indentation"/>
575            <xsl:with-param name="is-reference" select="false()"/>
576            <xsl:with-param name="name" select="$name"/>
577          </xsl:call-template>
578        </xsl:for-each>
579      </xsl:otherwise>
580    </xsl:choose>
581  </xsl:template>
582
583  <!-- Group free functions together under a category name (header synopsis)-->
584  <xsl:template match="free-function-group" mode="header-synopsis">
585    <xsl:param name="class"/>
586    <xsl:param name="indentation"/>
587    <xsl:apply-templates select="function|overloaded-function" mode="synopsis">
588      <xsl:with-param name="indentation" select="$indentation"/>
589    </xsl:apply-templates>
590  </xsl:template>
591
592  <!-- Constructors, destructor, and assignment operators -->
593  <xsl:template name="construct-copy-destruct-synopsis">
594    <xsl:param name="indentation"/>
595    <xsl:if test="constructor|copy-assignment|destructor">
596      <xsl:if test="typedef|static-constant">
597        <xsl:text>&#10;</xsl:text>
598      </xsl:if>
599      <xsl:text>&#10;</xsl:text>
600      <xsl:call-template name="indent">
601        <xsl:with-param name="indentation" select="$indentation"/>     
602      </xsl:call-template>
603      <emphasis>
604        <xsl:text>// </xsl:text>
605        <xsl:call-template name="internal-link">
606          <xsl:with-param name="to">
607            <xsl:call-template name="generate.id"/>
608            <xsl:text>construct-copy-destruct</xsl:text>
609          </xsl:with-param>
610          <xsl:with-param name="text" select="'construct/copy/destruct'"/>
611        </xsl:call-template>
612      </emphasis>
613      <xsl:apply-templates select="constructor" mode="synopsis">
614        <xsl:with-param name="indentation" select="$indentation"/>
615      </xsl:apply-templates>
616      <xsl:apply-templates select="copy-assignment" mode="synopsis">
617        <xsl:with-param name="indentation" select="$indentation"/>
618      </xsl:apply-templates>
619      <xsl:apply-templates select="destructor" mode="synopsis">
620        <xsl:with-param name="indentation" select="$indentation"/>
621      </xsl:apply-templates>
622    </xsl:if>
623  </xsl:template>
624
625  <xsl:template name="construct-copy-destruct-reference">
626    <xsl:if test="constructor|copy-assignment|destructor">
627      <xsl:call-template name="member-documentation">
628        <xsl:with-param name="name">
629          <xsl:call-template name="anchor">
630            <xsl:with-param name="to">
631              <xsl:call-template name="generate.id"/>
632              <xsl:text>construct-copy-destruct</xsl:text>
633            </xsl:with-param>
634            <xsl:with-param name="text" select="''"/>
635          </xsl:call-template>
636          <xsl:call-template name="monospaced">
637            <xsl:with-param name="text" select="@name"/>
638          </xsl:call-template>
639          <xsl:text> construct/copy/destruct</xsl:text>
640        </xsl:with-param>
641        <xsl:with-param name="text">
642          <orderedlist>
643            <xsl:apply-templates select="constructor" mode="reference"/>
644            <xsl:apply-templates select="copy-assignment" mode="reference"/>
645            <xsl:apply-templates select="destructor" mode="reference"/>
646          </orderedlist>
647        </xsl:with-param>
648      </xsl:call-template>
649    </xsl:if>
650  </xsl:template>
651
652  <xsl:template match="constructor" mode="reference">
653    <xsl:call-template name="function.documentation">
654      <xsl:with-param name="text">
655        <para>
656          <xsl:call-template name="preformatted">
657            <xsl:with-param name="text">
658              <xsl:call-template name="function">
659                <xsl:with-param name="indentation" select="0"/>
660                <xsl:with-param name="is-reference" select="true()"/>
661                <xsl:with-param name="constructor-for" select="../@name"/>
662                <xsl:with-param name="standalone" select="true()"/>
663              </xsl:call-template>
664            </xsl:with-param>
665          </xsl:call-template>
666        </para>
667        <xsl:call-template name="function-requirements"/>
668      </xsl:with-param>
669    </xsl:call-template>
670  </xsl:template>
671 
672  <xsl:template match="copy-assignment" mode="reference">
673    <xsl:call-template name="function.documentation">
674      <xsl:with-param name="text">
675        <para>
676          <xsl:call-template name="preformatted">
677            <xsl:with-param name="text">
678              <xsl:call-template name="function">
679                <xsl:with-param name="indentation" select="0"/>
680                <xsl:with-param name="is-reference" select="true()"/>
681                <xsl:with-param name="copy-assign-for" select="../@name"/>
682                <xsl:with-param name="standalone" select="true()"/>
683              </xsl:call-template>
684            </xsl:with-param>
685          </xsl:call-template>
686        </para>
687        <xsl:call-template name="function-requirements"/>
688      </xsl:with-param>
689    </xsl:call-template>
690  </xsl:template>
691
692  <xsl:template match="destructor" mode="reference">
693    <xsl:call-template name="function.documentation">
694      <xsl:with-param name="text">
695        <para>
696          <xsl:call-template name="preformatted">
697            <xsl:with-param name="text">
698              <xsl:call-template name="function">
699                <xsl:with-param name="indentation" select="0"/>
700                <xsl:with-param name="is-reference" select="true()"/>
701                <xsl:with-param name="destructor-for" select="../@name"/>
702                <xsl:with-param name="standalone" select="true()"/>
703              </xsl:call-template>
704            </xsl:with-param>
705          </xsl:call-template>
706        </para>
707        <xsl:call-template name="function-requirements"/>
708      </xsl:with-param>
709    </xsl:call-template>
710  </xsl:template>
711
712  <!-- Templates for functions -->
713  <xsl:template name="function.documentation">
714    <xsl:param name="text"/>
715    <xsl:choose>
716      <xsl:when test="count(ancestor::free-function-group) &gt; 0
717                      or count(ancestor::method-group) &gt; 0
718                      or local-name(.)='constructor'
719                      or local-name(.)='copy-assignment'
720                      or local-name(.)='destructor'">
721        <listitem><xsl:copy-of select="$text"/></listitem>
722      </xsl:when>
723      <xsl:otherwise>
724        <xsl:copy-of select="$text"/>
725      </xsl:otherwise>
726    </xsl:choose>
727  </xsl:template>
728
729  <!-- Semantic descriptions of functions -->
730  <xsl:template name="function-requirements">
731    <xsl:param name="namespace-reference" select="false()"/>
732
733    <xsl:if test="$namespace-reference=false()">
734      <xsl:apply-templates select="purpose/*"/>
735    </xsl:if>
736
737    <xsl:apply-templates select="description/*"/>
738
739    <xsl:if test="parameter/description|signature/parameter/description|
740                  requires|effects|postconditions|returns|throws|complexity|
741                  notes|rationale">
742      <variablelist spacing="compact">
743        <xsl:processing-instruction name="dbhtml">
744          list-presentation="table"
745        </xsl:processing-instruction>
746
747        <!-- Document parameters -->
748        <xsl:if test="parameter/description|signature/parameter/description">
749          <varlistentry>
750            <term>Parameters:</term>
751            <listitem>
752              <variablelist spacing="compact">
753                <xsl:processing-instruction name="dbhtml">
754                  list-presentation="table"
755                </xsl:processing-instruction>
756                <xsl:for-each select="parameter|signature/parameter">
757                              <xsl:sort select="attribute::name"/>
758                  <xsl:if test="description">
759                    <varlistentry>
760                      <term>
761                        <xsl:call-template name="monospaced">
762                          <xsl:with-param name="text" select="@name"/>
763                        </xsl:call-template>
764                      </term>
765                      <listitem>
766                        <xsl:apply-templates select="description/*"/>
767                      </listitem>
768                    </varlistentry>
769                  </xsl:if>
770                </xsl:for-each>
771              </variablelist>
772            </listitem>
773          </varlistentry>
774        </xsl:if>
775
776        <!-- Document rest of function's contract -->
777        <xsl:for-each select="requires|effects|postconditions|returns|throws|complexity|
778                      notes|rationale">
779          <varlistentry>
780            <term><xsl:call-template name="function.requirement.name"/>:</term>
781            <listitem>
782              <xsl:apply-templates select="./*|./text()" mode="annotation"/>
783            </listitem>
784          </varlistentry>
785        </xsl:for-each>
786
787      </variablelist>
788    </xsl:if>
789
790    <xsl:if test="para">
791      <xsl:message>
792        <xsl:text>Warning: Use of 'para' elements in a function is deprecated.&#10;</xsl:text>
793        <xsl:text>  Wrap them in a 'description' element.</xsl:text>
794      </xsl:message>
795      <xsl:call-template name="print.warning.context"/>
796      <xsl:apply-templates select="para"/>
797    </xsl:if>
798
799  </xsl:template>
800
801  <xsl:template name="function.requirement.name">
802    <xsl:param name="node" select="."/>
803    <xsl:choose>
804      <xsl:when test="local-name($node)='requires'">Requires</xsl:when>
805      <xsl:when test="local-name($node)='effects'">Effects</xsl:when>
806      <xsl:when test="local-name($node)='postconditions'">
807        <xsl:text>Postconditions</xsl:text>
808      </xsl:when>
809      <xsl:when test="local-name($node)='returns'">Returns</xsl:when>
810      <xsl:when test="local-name($node)='throws'">Throws</xsl:when>
811      <xsl:when test="local-name($node)='complexity'">Complexity</xsl:when>
812      <xsl:when test="local-name($node)='notes'">Notes</xsl:when>
813      <xsl:when test="local-name($node)='rationale'">Rationale</xsl:when>
814      <xsl:otherwise>
815        <xsl:message>
816          <xsl:text>Error: unhandled node type `</xsl:text>
817          <xsl:value-of select="local-name($node)"/>
818          <xsl:text>' in template function.requirement.name.</xsl:text>
819        </xsl:message>
820      </xsl:otherwise>
821    </xsl:choose>
822  </xsl:template>
823
824  <!-- Function reference -->
825  <xsl:template match="function|method" mode="reference">
826    <!-- True if we should compact this function -->
827    <xsl:variable name="compact"
828      select="not (para|description|requires|effects|postconditions|returns|
829                   throws|complexity|notes|rationale) and
830              ($boost.compact.function='1') and
831              not (local-name(.)='method')"/>
832
833    <xsl:if test="not ($compact)">
834      <xsl:call-template name="function.documentation">
835        <xsl:with-param name="text">
836          <para>
837            <xsl:call-template name="preformatted">
838              <xsl:with-param name="text">
839                <xsl:call-template name="function">
840                  <xsl:with-param name="indentation" select="0"/>
841                  <xsl:with-param name="is-reference" select="true()"/>
842                  <xsl:with-param name="link-type" select="'anchor'"/>
843                  <xsl:with-param name="standalone" select="true()"/>
844                </xsl:call-template>
845              </xsl:with-param>
846            </xsl:call-template>
847          </para>
848          <xsl:call-template name="function-requirements"/>
849        </xsl:with-param>
850      </xsl:call-template>
851    </xsl:if>
852  </xsl:template>
853
854  <!-- Reference for functions at namespace level -->
855  <xsl:template match="function" mode="namespace-reference">
856    <!-- True if we should compact this function -->
857    <xsl:variable name="compact"
858      select="not (para|description|requires|effects|postconditions|returns|
859                   throws|complexity|notes|rationale) and
860              ($boost.compact.function='1')"/>
861
862    <xsl:if test="not ($compact)">
863      <xsl:call-template name="reference-documentation">
864        <xsl:with-param name="name">
865          <xsl:text>Function </xsl:text>
866          <xsl:if test="template">
867            <xsl:text>template </xsl:text>
868          </xsl:if>
869          <xsl:call-template name="monospaced">
870            <xsl:with-param name="text" select="@name"/>
871          </xsl:call-template>
872        </xsl:with-param>
873        <xsl:with-param name="refname">
874          <xsl:call-template name="fully-qualified-name">
875            <xsl:with-param name="node" select="."/>
876          </xsl:call-template>
877        </xsl:with-param>
878        <xsl:with-param name="purpose" select="purpose/*|purpose/text()"/>
879        <xsl:with-param name="anchor">
880          <xsl:call-template name="generate.id"/>
881        </xsl:with-param>
882        <xsl:with-param name="synopsis">
883          <xsl:call-template name="function">
884            <xsl:with-param name="indentation" select="0"/>
885            <xsl:with-param name="is-reference" select="true()"/>
886            <xsl:with-param name="link-type" select="'none'"/>
887          </xsl:call-template>
888        </xsl:with-param>
889        <xsl:with-param name="text">
890          <xsl:call-template name="function-requirements">
891            <xsl:with-param name="namespace-reference" select="true()"/>
892          </xsl:call-template>
893        </xsl:with-param>
894      </xsl:call-template> 
895    </xsl:if>   
896  </xsl:template>
897
898  <xsl:template match="overloaded-function" mode="reference">
899    <xsl:variable name="name" select="@name"/>
900
901    <!-- True if we should compact this function -->
902    <xsl:variable name="compact"
903      select="not (para|description|requires|effects|postconditions|returns|
904                   throws|complexity|notes|rationale) and
905              ($boost.compact.function='1')"/>
906   
907    <xsl:if test="not ($compact)">
908      <xsl:call-template name="function.documentation">
909        <xsl:with-param name="text">
910          <para>
911            <xsl:attribute name="id">
912              <xsl:call-template name="generate.id"/>
913            </xsl:attribute>
914           
915            <xsl:call-template name="preformatted">
916              <xsl:with-param name="text">
917                <xsl:for-each select="signature">
918                  <xsl:call-template name="function">
919                    <xsl:with-param name="indentation" select="0"/>
920                    <xsl:with-param name="is-reference" select="true()"/>
921                    <xsl:with-param name="name" select="$name"/>
922                    <xsl:with-param name="standalone" select="true()"/>
923                  </xsl:call-template>
924                </xsl:for-each>
925              </xsl:with-param>
926            </xsl:call-template>
927          </para>
928          <xsl:call-template name="function-requirements"/>
929        </xsl:with-param>
930      </xsl:call-template>
931    </xsl:if>
932  </xsl:template>
933
934  <xsl:template match="overloaded-function" mode="namespace-reference">
935    <!-- True if we should compact this function -->
936    <xsl:variable name="compact"
937      select="not (para|description|requires|effects|postconditions|returns|
938                   throws|complexity|notes|rationale) and
939              ($boost.compact.function='1')"/>
940
941    <xsl:variable name="name" select="@name"/>
942
943    <xsl:if test="not ($compact)">
944      <xsl:call-template name="reference-documentation">
945        <xsl:with-param name="name">
946          <xsl:text>Function </xsl:text>
947          <xsl:if test="template">
948            <xsl:text>template </xsl:text>
949          </xsl:if>
950          <xsl:call-template name="monospaced">
951            <xsl:with-param name="text" select="@name"/>
952          </xsl:call-template>
953        </xsl:with-param>
954        <xsl:with-param name="refname">
955          <xsl:call-template name="fully-qualified-name">
956            <xsl:with-param name="node" select="."/>
957          </xsl:call-template>
958        </xsl:with-param>
959        <xsl:with-param name="purpose" select="purpose/*|purpose/text()"/>
960        <xsl:with-param name="anchor">
961          <xsl:call-template name="generate.id"/>
962        </xsl:with-param>
963        <xsl:with-param name="synopsis">
964          <xsl:for-each select="signature">
965            <xsl:call-template name="function">
966              <xsl:with-param name="indentation" select="0"/>
967              <xsl:with-param name="is-reference" select="true()"/>
968              <xsl:with-param name="link-type" select="'none'"/>
969              <xsl:with-param name="name" select="$name"/>
970            </xsl:call-template>
971          </xsl:for-each>
972        </xsl:with-param>
973        <xsl:with-param name="text">
974          <xsl:call-template name="function-requirements">
975            <xsl:with-param name="namespace-reference" select="true()"/>
976          </xsl:call-template>
977        </xsl:with-param>
978      </xsl:call-template> 
979    </xsl:if>   
980  </xsl:template>
981
982  <xsl:template match="overloaded-method" mode="reference">
983    <xsl:variable name="name" select="@name"/>
984
985    <xsl:call-template name="function.documentation">
986      <xsl:with-param name="text">
987        <para>
988          <xsl:attribute name="id">
989            <xsl:call-template name="generate.id"/>
990          </xsl:attribute>
991         
992          <xsl:call-template name="preformatted">
993            <xsl:with-param name="text">
994              <xsl:for-each select="signature">
995                <xsl:call-template name="function">
996                  <xsl:with-param name="indentation" select="0"/>
997                  <xsl:with-param name="is-reference" select="true()"/>
998                  <xsl:with-param name="name" select="$name"/>
999                  <xsl:with-param name="standalone" select="true()"/>
1000                </xsl:call-template>
1001              </xsl:for-each>
1002            </xsl:with-param>
1003          </xsl:call-template>
1004        </para>
1005        <xsl:call-template name="function-requirements"/>
1006      </xsl:with-param>
1007    </xsl:call-template>
1008  </xsl:template>
1009
1010  <!-- Group member functions together under a category name (synopsis)-->
1011  <xsl:template match="method-group" mode="synopsis">
1012    <xsl:param name="indentation"/>
1013    <xsl:if test="count(child::*) &gt; 0">
1014      <xsl:text>&#10;</xsl:text>
1015      <xsl:text>&#10;</xsl:text>
1016      <xsl:call-template name="indent">
1017        <xsl:with-param name="indentation" select="$indentation"/>
1018      </xsl:call-template>
1019      <emphasis>
1020        <xsl:text>// </xsl:text>
1021        <xsl:call-template name="internal-link">
1022          <xsl:with-param name="to">
1023            <xsl:call-template name="generate.id"/>
1024          </xsl:with-param>
1025          <xsl:with-param name="text" select="string(@name)"/>
1026        </xsl:call-template>
1027      </emphasis>
1028      <xsl:apply-templates select="method|overloaded-method" 
1029        mode="synopsis">
1030        <xsl:with-param name="indentation" select="$indentation"/>
1031      </xsl:apply-templates>
1032    </xsl:if>
1033  </xsl:template>
1034
1035  <!-- Group member functions together under a category name (reference)-->
1036  <xsl:template match="method-group" mode="reference">
1037    <xsl:if test="count(child::*) &gt; 0">
1038      <xsl:call-template name="member-documentation">
1039        <xsl:with-param name="name">
1040          <xsl:call-template name="anchor">
1041            <xsl:with-param name="to">
1042              <xsl:call-template name="generate.id"/>
1043            </xsl:with-param>
1044            <xsl:with-param name="text" select="''"/>
1045          </xsl:call-template>
1046          <xsl:call-template name="monospaced">
1047            <xsl:with-param name="text" select="../@name"/>
1048          </xsl:call-template>
1049          <xsl:text> </xsl:text>
1050          <xsl:value-of select="@name"/>
1051        </xsl:with-param>
1052        <xsl:with-param name="text">
1053          <orderedlist>
1054            <xsl:apply-templates select="method|overloaded-method"
1055              mode="reference"/>
1056          </orderedlist>
1057        </xsl:with-param>
1058      </xsl:call-template>
1059    </xsl:if>
1060  </xsl:template> 
1061
1062  <!-- Group free functions together under a category name (synopsis)-->
1063  <xsl:template match="free-function-group" mode="synopsis">
1064    <xsl:param name="class"/>
1065    <xsl:param name="indentation"/>
1066    <xsl:text>&#10;</xsl:text>
1067    <xsl:text>&#10;</xsl:text>
1068    <xsl:call-template name="indent">
1069      <xsl:with-param name="indentation" select="$indentation"/>
1070    </xsl:call-template>
1071    <emphasis>
1072      <xsl:text>// </xsl:text>
1073      <xsl:call-template name="internal-link">
1074        <xsl:with-param name="to">
1075          <xsl:call-template name="generate.id"/>
1076        </xsl:with-param>
1077        <xsl:with-param name="text" select="string(@name)"/>
1078      </xsl:call-template>
1079    </emphasis>
1080    <xsl:apply-templates select="function|overloaded-function" mode="synopsis">
1081      <xsl:with-param name="indentation" select="$indentation"/>
1082    </xsl:apply-templates>
1083  </xsl:template>
1084
1085  <!-- Group free functions together under a category name (reference)-->
1086  <xsl:template match="free-function-group" mode="reference">
1087    <xsl:param name="class"/>
1088    <xsl:call-template name="member-documentation">
1089      <xsl:with-param name="name">
1090        <xsl:call-template name="anchor">
1091          <xsl:with-param name="to">
1092            <xsl:call-template name="generate.id"/>
1093          </xsl:with-param>
1094          <xsl:with-param name="text" select="''"/>
1095        </xsl:call-template>
1096        <xsl:call-template name="monospaced">
1097          <xsl:with-param name="text" select="$class"/>
1098        </xsl:call-template>
1099        <xsl:value-of select="concat(' ',@name)"/>
1100      </xsl:with-param>
1101      <xsl:with-param name="text">
1102        <orderedlist>
1103          <xsl:apply-templates select="function|overloaded-function"
1104            mode="reference"/>
1105        </orderedlist>
1106      </xsl:with-param>
1107    </xsl:call-template>
1108  </xsl:template> 
1109</xsl:stylesheet>
Note: See TracBrowser for help on using the repository browser.