Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/tools/boostbook/xsl/function.xsl @ 12

Last change on this file since 12 was 12, checked in by landauf, 18 years ago

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