Allow the title of top level pages to be overridden in the Atmel Studio help.
[pub/USBasp.git] / LUFA / StudioIntegration / HV1 / lufa_docbook_transform.xslt
1 <?xml version="1.0" encoding="UTF-8"?>
2
3 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
4
5 <xsl:output method="xml" indent="no"/>
6
7 <xsl:param name="keyword.namespace" select="'Atmel.Language.C'"/>
8
9 <xsl:template name="generate.book.title">
10 <xsl:text>LUFA Library</xsl:text>
11 </xsl:template>
12
13 <xsl:template name="generate.book.id">
14 <xsl:param name="book.title"/>
15 <xsl:choose>
16 <xsl:when test="@id">
17 <xsl:value-of select="@id"/>
18 </xsl:when>
19 <xsl:otherwise>
20 <xsl:value-of select="translate($book.title, ' ','')"/>
21 </xsl:otherwise>
22 </xsl:choose>
23 </xsl:template>
24
25 <xsl:template name="generate.index.id">
26 <xsl:param name="name"/>
27 <xsl:variable name="book.title">
28 <xsl:call-template name="generate.book.title"/>
29 </xsl:variable>
30 <xsl:variable name="book.id">
31 <xsl:call-template name="generate.book.id">
32 <xsl:with-param name="book.title" select="$book.title"/>
33 </xsl:call-template>
34 </xsl:variable>
35
36 <indexterm id="{$keyword.namespace}.{$name}">
37 <primary>
38 <xsl:value-of select="$book.title"/>
39 </primary>
40 <secondary>
41 <xsl:value-of select="$name"/>
42 </secondary>
43 </indexterm>
44 </xsl:template>
45
46 <xsl:template match="doxygen">
47 <xsl:variable name="book.title">
48 <xsl:call-template name="generate.book.title"/>
49 </xsl:variable>
50
51 <xsl:variable name="book.id">
52 <xsl:call-template name="generate.book.id">
53 <xsl:with-param name="book.title" select="$book.title"/>
54 </xsl:call-template>
55 </xsl:variable>
56
57 <book id="{$book.id}">
58 <title>
59 <xsl:value-of select="$book.title"/>
60 </title>
61
62 <!-- Add index chapter -->
63 <xsl:call-template name="generate.top.level.page">
64 <xsl:with-param name="top.level.page" select="compounddef[@kind = 'page' and @id = 'indexpage']"/>
65 <xsl:with-param name="top.level.page.title" select="'Library Information'"/>
66 </xsl:call-template>
67
68 <!-- Add free-floating chapters -->
69 <xsl:for-each select="compounddef[@kind = 'page' and not(@id = 'indexpage')]">
70 <xsl:if test="not(//innerpage[@refid = current()/@id])">
71 <xsl:call-template name="generate.top.level.page">
72 <xsl:with-param name="top.level.page" select="current()"/>
73 </xsl:call-template>
74 </xsl:if>
75 </xsl:for-each>
76
77 <!-- Add Module chapter -->
78 <chapter>
79 <title>Modules</title>
80 <xsl:for-each select="compounddef[@kind = 'group']">
81 <xsl:if test="not(//innergroup[@refid = current()/@id])">
82 <xsl:apply-templates select="current()"/>
83 </xsl:if>
84 </xsl:for-each>
85 </chapter>
86 </book>
87 </xsl:template>
88
89 <xsl:template name="generate.top.level.page">
90 <xsl:param name="top.level.page"/>
91 <xsl:param name="top.level.page.title" select="$top.level.page/title"/>
92
93 <chapter id="{$top.level.page/@id}">
94 <title>
95 <xsl:value-of select="$top.level.page.title"/>
96 </title>
97
98 <xsl:apply-templates select="$top.level.page/detaileddescription"/>
99
100 <xsl:for-each select="$top.level.page/innerpage">
101 <xsl:apply-templates select="ancestor::*/compounddef[@kind = 'page' and @id = current()/@refid]"/>
102 </xsl:for-each>
103 </chapter>
104 </xsl:template>
105
106 <xsl:template match="compounddef">
107 <!-- Discard compounddef elements unless a later template matches -->
108 </xsl:template>
109
110 <xsl:template match="compounddef[@kind = 'page']">
111 <section id="{@id}">
112 <title>
113 <xsl:value-of select="title"/>
114 </title>
115
116 <xsl:apply-templates select="detaileddescription"/>
117
118 <xsl:for-each select="innerpage">
119 <xsl:apply-templates select="ancestor::*/compounddef[@kind = 'page' and @id = current()/@refid]"/>
120 </xsl:for-each>
121 </section>
122 </xsl:template>
123
124 <xsl:template match="compounddef[@kind = 'group']">
125 <section id="{@id}">
126 <title>
127 <xsl:value-of select="title"/>
128 </title>
129
130 <xsl:variable name="name">
131 <xsl:choose>
132 <xsl:when test="contains(compoundname, '_')">
133 <xsl:value-of select="translate(compoundname, '_', '/')"/>
134 <xsl:text>.h</xsl:text>
135 </xsl:when>
136
137 <xsl:otherwise>
138 <xsl:value-of select="compoundname"/>
139 <xsl:text>.h</xsl:text>
140 </xsl:otherwise>
141 </xsl:choose>
142 </xsl:variable>
143
144 <xsl:variable name="name.escaped">
145 <xsl:choose>
146 <xsl:when test="contains(compoundname, '_')">
147 <xsl:value-of select="translate(compoundname, '_', '.')"/>
148 <xsl:text>.h</xsl:text>
149 </xsl:when>
150
151 <xsl:otherwise>
152 <xsl:value-of select="compoundname"/>
153 <xsl:text>.h</xsl:text>
154 </xsl:otherwise>
155 </xsl:choose>
156 </xsl:variable>
157
158 <indexterm id="{$keyword.namespace}.{$name.escaped}">
159 <primary>Header</primary>
160 <secondary>
161 <xsl:value-of select="$name"/>
162 </secondary>
163 </indexterm>
164
165 <xsl:call-template name="generate.index.id">
166 <xsl:with-param name="name" select="$name"/>
167 </xsl:call-template>
168
169 <indexterm>
170 <primary>
171 <xsl:value-of select="$name"/>
172 </primary>
173 </indexterm>
174
175 <xsl:apply-templates select="detaileddescription" />
176
177 <xsl:apply-templates select="sectiondef" />
178
179 <xsl:for-each select="innerclass">
180 <xsl:apply-templates select="ancestor::*/compounddef[@id = current()/@refid]"/>
181 </xsl:for-each>
182
183 <xsl:for-each select="innergroup">
184 <xsl:apply-templates select="ancestor::*/compounddef[@kind = 'group' and @id = current()/@refid]"/>
185 </xsl:for-each>
186 </section>
187 </xsl:template>
188
189 <xsl:template match="compounddef[@kind = 'struct' or @kind = 'union']">
190 <xsl:variable name="name" select="compoundname"/>
191
192 <section id="{@id}" xreflabel="{$name}">
193 <title>
194 <xsl:choose>
195 <xsl:when test="@kind = 'struct'">
196 <xsl:text>Struct </xsl:text>
197 </xsl:when>
198
199 <xsl:when test="@kind = 'union'">
200 <xsl:text>Union </xsl:text>
201 </xsl:when>
202 </xsl:choose>
203
204 <xsl:value-of select="$name"/>
205 </title>
206
207 <xsl:call-template name="generate.index.id">
208 <xsl:with-param name="name" select="$name"/>
209 </xsl:call-template>
210
211 <xsl:apply-templates select="detaileddescription"/>
212
213 <xsl:for-each select="sectiondef[@kind = 'public-attrib']">
214 <table tabstyle="striped">
215 <title>
216 <xsl:value-of select="$name"/>
217 </title>
218 <tgroup cols="3">
219 <colspec colnum="1" colname="start.col"/>
220 <colspec colnum="3" colname="stop.col"/>
221 <spanspec spanname="full" namest="start.col" nameend="stop.col"/>
222 <thead>
223 <row>
224 <entry>Type</entry>
225 <entry>Name</entry>
226 <entry>Description</entry>
227 </row>
228 </thead>
229 <tbody>
230 <xsl:for-each select="memberdef">
231 <row id="{@id}" xreflabel="{name}">
232 <entry>
233 <xsl:apply-templates select="type"/>
234 </entry>
235 <entry>
236 <xsl:value-of select="name"/>
237 <xsl:if test="starts-with(argsstring, '[')">
238 <xsl:text>[]</xsl:text>
239 </xsl:if>
240 <indexterm id="{$keyword.namespace}.{$name}.{name}"/>
241 </entry>
242 <entry>
243 <xsl:apply-templates select="detaileddescription"/>
244 </entry>
245 </row>
246 </xsl:for-each>
247 </tbody>
248 </tgroup>
249 </table>
250 </xsl:for-each>
251 </section>
252 </xsl:template>
253
254 <xsl:template match="memberdef[@kind = 'function']">
255 <section id="{@id}" xreflabel="{name}">
256 <title>
257 <xsl:text>Function </xsl:text>
258 <xsl:value-of select="name"/>
259 <xsl:text>()</xsl:text>
260 </title>
261
262 <xsl:call-template name="generate.index.id">
263 <xsl:with-param name="name" select="name"/>
264 </xsl:call-template>
265
266 <para>
267 <emphasis role="italic">
268 <xsl:value-of select="briefdescription"/>
269 </emphasis>
270 </para>
271
272 <programlisting language="c">
273 <emphasis role="keyword">
274 <xsl:value-of select="type"/>
275 </emphasis>
276 <xsl:text> </xsl:text>
277 <xsl:value-of select="name"/>
278 <xsl:text>(</xsl:text>
279
280 <xsl:choose>
281 <xsl:when test="argsstring = '(void)'">
282 <emphasis role="keyword">void</emphasis>
283 </xsl:when>
284
285 <xsl:otherwise>
286 <xsl:for-each select="param">
287 <xsl:if test="position() > 1">
288 <xsl:text>,</xsl:text>
289 </xsl:if>
290 <xsl:text>&#10;&#9;</xsl:text>
291 <emphasis role="keyword">
292 <xsl:value-of select="type"/>
293 </emphasis>
294 <xsl:text> </xsl:text>
295 <xsl:value-of select="declname"/>
296 </xsl:for-each>
297 </xsl:otherwise>
298 </xsl:choose>
299
300 <xsl:text>)</xsl:text>
301 </programlisting>
302
303 <xsl:apply-templates select="detaileddescription"/>
304 </section>
305 </xsl:template>
306
307 <xsl:template match="memberdef[@kind = 'enum']">
308 <xsl:variable name="name" select="name"/>
309
310 <section id="{@id}" xreflabel="{name}">
311 <title>
312 <xsl:text>Enum </xsl:text>
313 <xsl:value-of select="$name"/>
314 </title>
315
316 <xsl:call-template name="generate.index.id">
317 <xsl:with-param name="name" select="$name"/>
318 </xsl:call-template>
319
320 <xsl:apply-templates select="detaileddescription"/>
321
322 <table tabstyle="striped">
323 <title>Members</title>
324 <tgroup cols="2">
325 <thead>
326 <row>
327 <entry>Enum Value</entry>
328 <entry>Description</entry>
329 </row>
330 </thead>
331 <tbody>
332 <xsl:for-each select="enumvalue">
333 <row>
334 <entry>
335 <para id="{@id}" xreflabel="{name}">
336 <xsl:value-of select="name"/>
337 <indexterm id="{$keyword.namespace}.{$name}.{name}"/>
338 </para>
339 </entry>
340 <entry>
341 <xsl:apply-templates select="detaileddescription"/>
342 </entry>
343 </row>
344 </xsl:for-each>
345 </tbody>
346 </tgroup>
347 </table>
348 </section>
349 </xsl:template>
350
351 <xsl:template match="memberdef[@kind = 'define']">
352 <section id="{@id}" xreflabel="{name}">
353 <title>
354 <xsl:text>Macro </xsl:text>
355 <xsl:value-of select="name"/>
356 </title>
357
358 <xsl:call-template name="generate.index.id">
359 <xsl:with-param name="name" select="name"/>
360 </xsl:call-template>
361
362 <programlisting language="c">
363 <emphasis role="preprocessor">
364 <xsl:text>#define </xsl:text>
365 <xsl:value-of select="name"/>
366 <xsl:if test="count(param) > 0">
367 <xsl:text>(</xsl:text>
368 <xsl:for-each select="param/defname">
369 <xsl:if test="position() > 1">
370 <xsl:text>,</xsl:text>
371 </xsl:if>
372 <xsl:value-of select="."/>
373 </xsl:for-each>
374 <xsl:text>)</xsl:text>
375 </xsl:if>
376 <xsl:text> </xsl:text>
377
378 <!-- Split long macro definitions across multiple lines -->
379 <xsl:if test="(string-length(initializer) > 50) or (count(param) > 0)">
380 <xsl:text>\&#10;&#9;</xsl:text>
381 </xsl:if>
382
383 <xsl:value-of select="initializer"/>
384 </emphasis>
385 <xsl:text> </xsl:text>
386 </programlisting>
387
388 <xsl:apply-templates select="detaileddescription"/>
389 </section>
390 </xsl:template>
391
392 <xsl:template match="memberdef[@kind = 'variable' or @kind = 'typedef']">
393 <section id="{@id}" xreflabel="{name}">
394 <!-- Doxygen gets confused and thinks function pointer type definitions
395 are variables, so we need to map them to this common section and
396 check the definition to see which of the two it is. -->
397 <xsl:choose>
398 <xsl:when test="contains(definition, 'typedef')">
399 <title>
400 <xsl:text>Type </xsl:text>
401 <xsl:value-of select="name"/>
402 </title>
403
404 <xsl:call-template name="generate.index.id">
405 <xsl:with-param name="name" select="name"/>
406 </xsl:call-template>
407
408 <programlisting language="c">
409 <emphasis role="keyword">
410 <xsl:text>typedef </xsl:text>
411 <xsl:value-of select="type"/>
412 </emphasis>
413 <xsl:text> </xsl:text>
414 <xsl:value-of select="name"/>
415 <xsl:text> </xsl:text>
416 <xsl:value-of select="argsstring"/>
417 </programlisting>
418 </xsl:when>
419
420 <xsl:otherwise>
421 <title>
422 <xsl:text>Variable </xsl:text>
423 <xsl:value-of select="name"/>
424 </title>
425
426 <xsl:call-template name="generate.index.id">
427 <xsl:with-param name="name" select="name"/>
428 </xsl:call-template>
429
430 <programlisting language="c">
431 <emphasis role="keyword">
432 <xsl:value-of select="type"/>
433 </emphasis>
434 <xsl:text> </xsl:text>
435 <xsl:value-of select="name"/>
436 </programlisting>
437 </xsl:otherwise>
438 </xsl:choose>
439
440 <xsl:apply-templates select="detaileddescription"/>
441 </section>
442 </xsl:template>
443
444 <xsl:template match="linebreak">
445 <literallayout>
446 </literallayout>
447 </xsl:template>
448
449 <xsl:template match="verbatim">
450 <programlisting>
451 <xsl:apply-templates/>
452 </programlisting>
453 </xsl:template>
454
455 <xsl:template match="sectiondef">
456 <para>
457 <xsl:value-of select="description"/>
458 </para>
459
460 <xsl:apply-templates select="memberdef"/>
461 </xsl:template>
462
463 <xsl:template match="simplesect" mode="struct">
464 <footnote>
465 <xsl:apply-templates/>
466 </footnote>
467 </xsl:template>
468
469 <xsl:template match="simplesect">
470 <xsl:choose>
471 <xsl:when test="@kind = 'par'">
472 <note>
473 <title>
474 <xsl:value-of select="title"/>
475 </title>
476 <xsl:apply-templates select="para"/>
477 </note>
478 </xsl:when>
479
480 <xsl:when test="@kind = 'return'">
481 <note>
482 <title>Returns</title>
483 <xsl:apply-templates select="para"/>
484 </note>
485 </xsl:when>
486
487 <xsl:when test="@kind = 'warning'">
488 <warning>
489 <title>Warning</title>
490 <xsl:apply-templates select="para"/>
491 </warning>
492 </xsl:when>
493
494 <xsl:when test="@kind = 'pre'">
495 <note>
496 <title>Precondition</title>
497 <xsl:apply-templates select="para"/>
498 </note>
499 </xsl:when>
500
501 <xsl:when test="@kind = 'see'">
502 <note>
503 <title>See also</title>
504 <xsl:apply-templates select="para"/>
505 </note>
506 </xsl:when>
507
508 <xsl:when test="@kind = 'note'">
509 <note>
510 <title>Note</title>
511 <xsl:apply-templates select="para"/>
512 </note>
513 </xsl:when>
514
515 </xsl:choose>
516 </xsl:template>
517
518 <xsl:template match="parameterlist[@kind = 'param']">
519 <table tabstyle="striped">
520 <title>Parameters</title>
521 <tgroup cols="3">
522 <thead>
523 <row>
524 <entry>Data Direction</entry>
525 <entry>Parameter Name</entry>
526 <entry>Description</entry>
527 </row>
528 </thead>
529 <tbody>
530 <xsl:for-each select="parameteritem">
531 <row>
532 <xsl:apply-templates select="."/>
533 </row>
534 </xsl:for-each>
535 </tbody>
536 </tgroup>
537 </table>
538 </xsl:template>
539
540 <xsl:template match="parameterlist[@kind = 'retval']">
541 <table tabstyle="striped">
542 <title>Return Values</title>
543 <tgroup cols="2">
544 <thead>
545 <row>
546 <entry>Return Value</entry>
547 <entry>Description</entry>
548 </row>
549 </thead>
550 <tbody>
551 <xsl:for-each select="parameteritem">
552 <row>
553 <xsl:apply-templates select="."/>
554 </row>
555 </xsl:for-each>
556 </tbody>
557 </tgroup>
558 </table>
559 </xsl:template>
560
561 <xsl:template match="parameteritem">
562 <xsl:if test="parent::parameterlist/@kind = 'param'">
563 <entry>
564 <para>
565 <xsl:choose>
566 <xsl:when test="not(descendant::parametername/@direction)">
567 <emphasis role="italic">?</emphasis>
568 </xsl:when>
569
570 <xsl:otherwise>
571 <emphasis role="bold">
572 [<xsl:value-of select="descendant::parametername/@direction"/>]
573 </emphasis>
574 </xsl:otherwise>
575 </xsl:choose>
576 </para>
577 </entry>
578 </xsl:if>
579
580 <entry>
581 <para>
582 <xsl:value-of select="parameternamelist/parametername"/>
583 </para>
584 </entry>
585
586 <entry>
587 <xsl:apply-templates select="parameterdescription"/>
588 </entry>
589 </xsl:template>
590
591 <xsl:template match="type">
592 <xsl:apply-templates/>
593 </xsl:template>
594
595 <xsl:template match="para">
596 <para>
597 <xsl:apply-templates/>
598 </para>
599 </xsl:template>
600
601 <xsl:template match="bold">
602 <emphasis role="bold">
603 <xsl:value-of select="."/>
604 </emphasis>
605 </xsl:template>
606
607 <xsl:template match="emphasis">
608 <emphasis role="italic">
609 <xsl:value-of select="."/>
610 </emphasis>
611 </xsl:template>
612
613 <xsl:template match="computeroutput">
614 <computeroutput>
615 <xsl:value-of select="."/>
616 </computeroutput>
617 </xsl:template>
618
619 <xsl:template match="ulink">
620 <ulink url="{@url}">
621 <xsl:value-of select="."/>
622 </ulink>
623 </xsl:template>
624
625 <xsl:template match="registered">
626 <xsl:text>&#174;</xsl:text>
627 </xsl:template>
628
629 <xsl:template match="copy">
630 <xsl:text>&#169;</xsl:text>
631 </xsl:template>
632
633 <xsl:template match="trademark">
634 <xsl:text>&#8482;</xsl:text>
635 </xsl:template>
636
637 <xsl:template match="superscript">
638 <superscript>
639 <xsl:value-of select="."/>
640 </superscript>
641 </xsl:template>
642
643 <xsl:template match="subscript">
644 <subscript>
645 <xsl:value-of select="."/>
646 </subscript>
647 </xsl:template>
648
649 <xsl:template match="ref">
650 <xsl:choose>
651 <!-- Don't show links inside program listings -->
652 <xsl:when test="ancestor::programlisting">
653 <xsl:value-of select="."/>
654 </xsl:when>
655
656 <!-- Don't show links to file compound definitions, as they are discarded -->
657 <xsl:when test="ancestor::*/compounddef[@kind = 'file' and @id = current()/@refid]">
658 <xsl:value-of select="."/>
659 </xsl:when>
660
661 <!-- Show links outside program listings -->
662 <xsl:otherwise>
663 <link linkend="{@refid}">
664 <xsl:value-of select="text()"/>
665 </link>
666 </xsl:otherwise>
667 </xsl:choose>
668 </xsl:template>
669
670 <xsl:template match="table">
671 <xsl:choose>
672 <xsl:when test="caption">
673 <table tabstyle="striped">
674 <title>
675 <xsl:value-of select="caption"/>
676 </title>
677 <xsl:call-template name="write.table.content"/>
678 </table>
679 </xsl:when>
680
681 <xsl:otherwise>
682 <informaltable tabstyle="striped">
683 <xsl:call-template name="write.table.content"/>
684 </informaltable>
685 </xsl:otherwise>
686 </xsl:choose>
687 </xsl:template>
688
689 <xsl:template name="write.table.content">
690 <tgroup cols="{@cols}">
691 <thead>
692 <xsl:for-each select="row[1]">
693 <row>
694 <xsl:for-each select="entry">
695 <entry>
696 <xsl:apply-templates select="."/>
697 </entry>
698 </xsl:for-each>
699 </row>
700 </xsl:for-each>
701 </thead>
702 <tbody>
703 <xsl:for-each select="row[position() != 1]">
704 <row>
705 <xsl:for-each select="entry">
706 <entry>
707 <xsl:apply-templates select="."/>
708 </entry>
709 </xsl:for-each>
710 </row>
711 </xsl:for-each>
712 </tbody>
713 </tgroup>
714 </xsl:template>
715
716 <xsl:template match="itemizedlist">
717 <itemizedlist>
718 <xsl:apply-templates/>
719 </itemizedlist>
720 </xsl:template>
721
722 <xsl:template match="orderedlist">
723 <orderedlist>
724 <xsl:apply-templates/>
725 </orderedlist>
726 </xsl:template>
727
728 <xsl:template match="listitem">
729 <listitem>
730 <xsl:apply-templates/>
731 </listitem>
732 </xsl:template>
733
734 <xsl:template match="programlisting">
735 <programlisting language="c">
736 <xsl:for-each select="codeline[position() > 1 or highlight]">
737 <xsl:apply-templates select="."/>
738 <xsl:text>&#10;</xsl:text>
739 </xsl:for-each>
740 </programlisting>
741 </xsl:template>
742
743 <xsl:template match="highlight">
744 <emphasis role="{@class}">
745 <xsl:apply-templates/>
746 </emphasis>
747 </xsl:template>
748
749 <xsl:template match="sp[ancestor::codeline]">
750 <xsl:text> </xsl:text>
751 </xsl:template>
752
753 <xsl:template match="image">
754 <mediaobject>
755 <imageobject>
756 <imagedata>
757 <xsl:attribute name="fileref">
758 <xsl:text>images/</xsl:text>
759 <xsl:value-of select="@name"/>
760 </xsl:attribute>
761 </imagedata>
762 </imageobject>
763 </mediaobject>
764 </xsl:template>
765
766 <xsl:template match="detaileddescription">
767 <xsl:apply-templates/>
768 </xsl:template>
769
770 <xsl:template match="sect1 | sect2 | sect3 | sect4 | sect5 | sect6 | sect7 | sect8 | sect9">
771 <section>
772 <xsl:if test="@id">
773 <xsl:attribute name="id">
774 <xsl:value-of select="@id"/>
775 </xsl:attribute>
776 </xsl:if>
777
778 <title>
779 <xsl:value-of select="title"/>
780 </title>
781
782 <xsl:apply-templates/>
783 </section>
784 </xsl:template>
785
786 <xsl:template match="anchor">
787 <xsl:if test="@id">
788 <indexterm id="{@id}"/>
789 </xsl:if>
790 </xsl:template>
791
792 <xsl:template match="title"/>
793
794 </xsl:stylesheet>