Fix Atmel Studio integrated help generation and branding.

diff --git a/LUFA/StudioIntegration/Blob/LUFA.dll b/LUFA/StudioIntegration/Blob/LUFA.dll
index b25c4b5..4570162 100644 (file)
Binary files a/LUFA/StudioIntegration/Blob/LUFA.dll and b/LUFA/StudioIntegration/Blob/LUFA.dll differ

diff --git a/LUFA/StudioIntegration/HV1/transform_base.xsl b/LUFA/StudioIntegration/HV1/transform_base.xsl
index 03b7901..8ff3428 100644 (file)
--- a/LUFA/StudioIntegration/HV1/transform_base.xsl
+++ b/LUFA/StudioIntegration/HV1/transform_base.xsl
@@ -7,7 +7,7 @@
   version="1.0">\r
 \r
   <xsl:output\r
-    method="xml" indent="yes"\r
+    method="xml" indent="no"\r
     doctype-public="-//OASIS//DTD DocBook XML V4.5//EN"\r
     doctype-system="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"/>\r
 \r
@@ -40,11 +40,11 @@
         </section>\r
       </xsl:if>\r
 \r
-      <xsl:if test="count(ancestor::*/sectiondef[memberdef/@kind = 'define' or @kind = 'define']) > 0">\r
+      <xsl:if test="count(ancestor::*/sectiondef[memberdef/@kind = 'define']) > 0">\r
         <section>\r
           <title>Macro Definitions</title>\r
 \r
-          <xsl:for-each select="ancestor::*/sectiondef[memberdef/@kind = 'define' or @kind = 'define']">\r
+          <xsl:for-each select="ancestor::*/sectiondef[memberdef/@kind = 'define']">\r
             <section>\r
               <title>\r
                 <xsl:value-of select="header"/>\r
@@ -106,7 +106,9 @@
       <xsl:apply-templates select="detaileddescription"/>\r
 \r
       <xsl:for-each select="sectiondef[@kind = 'public-attrib']">\r
-        <informaltable tabstyle="striped">\r
+        <table tabstyle="striped">\r
+          <title>Members</title>\r
+\r
           <tgroup cols="3">\r
             <thead>\r
               <row>\r
@@ -134,7 +136,7 @@
               </xsl:for-each>\r
             </tbody>\r
           </tgroup>\r
-        </informaltable>\r
+        </table>\r
         <para>&#xa0;</para>\r
       </xsl:for-each>\r
     </section>\r
@@ -151,9 +153,34 @@
       </para>\r
 \r
       <programlisting language="c">\r
-        <xsl:value-of select="definition"/>\r
-        <xsl:text>&#10;&#9;&#9;</xsl:text>\r
-        <xsl:apply-templates select="argsstring"/>\r
+        <emphasis role="keyword">\r
+          <xsl:value-of select="type"/>\r
+        </emphasis>\r
+        <xsl:text> </xsl:text>\r
+        <xsl:value-of select="name"/>\r
+        <xsl:text>(</xsl:text>\r
+\r
+        <xsl:choose>\r
+          <xsl:when test="argsstring = '(void)'">\r
+            <emphasis role="keyword">void</emphasis>\r
+          </xsl:when>\r
+\r
+          <xsl:otherwise>\r
+            <xsl:for-each select="param">\r
+              <xsl:if test="position() > 1">\r
+                <xsl:text>,</xsl:text>\r
+              </xsl:if>\r
+              <xsl:text>&#10;&#9;&#9;</xsl:text>\r
+              <emphasis role="keyword">\r
+                <xsl:value-of select="type"/>\r
+              </emphasis>\r
+              <xsl:text> </xsl:text>\r
+              <xsl:value-of select="declname"/>\r
+            </xsl:for-each>\r
+          </xsl:otherwise>\r
+        </xsl:choose>\r
+\r
+        <xsl:text>)</xsl:text>\r
       </programlisting>\r
 \r
       <xsl:apply-templates select="detaileddescription"/>\r
@@ -168,11 +195,12 @@
 \r
       <xsl:apply-templates select="detaileddescription"/>\r
 \r
-      <informaltable tabstyle="striped">\r
+      <table tabstyle="striped">\r
+        <title>Members</title>\r
         <tgroup cols="2">\r
           <thead>\r
             <row>\r
-              <entry>Enum Value</entry>\r
+              <entry>Enum value</entry>\r
               <entry>Description</entry>\r
             </row>\r
           </thead>\r
@@ -191,7 +219,7 @@
             </xsl:for-each>\r
           </tbody>\r
         </tgroup>\r
-      </informaltable>\r
+      </table>\r
 \r
       <para>&#xa0;</para>\r
     </section>\r
@@ -202,26 +230,29 @@
       <title> Macro <xsl:value-of select="name"/> </title>\r
 \r
       <programlisting language="c">\r
-        <xsl:text>#define </xsl:text>\r
-        <xsl:value-of select="name"/>\r
-        <xsl:if test="count(param) > 0">\r
-          <xsl:text>(</xsl:text>\r
-          <xsl:for-each select="param/defname">\r
-            <xsl:if test="position() > 1">\r
-              <xsl:text>, </xsl:text>\r
-            </xsl:if>\r
-            <xsl:value-of select="."/>\r
-          </xsl:for-each>\r
-          <xsl:text>)</xsl:text>\r
-        </xsl:if>\r
-        <xsl:text> </xsl:text>\r
+        <emphasis role="preprocessor">\r
+          <xsl:text>#define </xsl:text>\r
+          <xsl:value-of select="name"/>\r
+          <xsl:if test="count(param) > 0">\r
+            <xsl:text>(</xsl:text>\r
+            <xsl:for-each select="param/defname">\r
+              <xsl:if test="position() > 1">\r
+                <xsl:text>, </xsl:text>\r
+              </xsl:if>\r
+              <xsl:value-of select="."/>\r
+            </xsl:for-each>\r
+            <xsl:text>)</xsl:text>\r
+          </xsl:if>\r
+          <xsl:text> </xsl:text>\r
 \r
-        <!-- Split long macro definitions across multiple lines -->\r
-        <xsl:if test="(string-length(initializer) > 50) or (count(param) > 0)">\r
-          <xsl:text>\&#10;&#09;&#9;</xsl:text>\r
-        </xsl:if>\r
+          <!-- Split long macro definitions across multiple lines -->\r
+          <xsl:if test="(string-length(initializer) > 50) or (count(param) > 0)">\r
+            <xsl:text>\&#10;&#09;&#9;</xsl:text>\r
+          </xsl:if>\r
 \r
-        <xsl:value-of select="initializer"/>\r
+          <xsl:value-of select="initializer"/>\r
+        </emphasis>\r
+        <xsl:text> </xsl:text>\r
       </programlisting>\r
 \r
       <xsl:apply-templates select="detaileddescription"/>\r
@@ -232,26 +263,37 @@
 \r
   <xsl:template match="memberdef[@kind = 'variable' or @kind = 'typedef']">\r
     <section id="{@id}" xreflabel="{name}">\r
-      <title>\r
-        <!-- Doxygen gets confused and thinks function pointer type definitions\r
-             are variables, so we need to map them to this common section and\r
-             check the definition to see which of the two it is. -->\r
-        <xsl:choose>\r
-          <xsl:when test="contains(definition,'typedef')">\r
-            <xsl:text>Type </xsl:text>\r
-          </xsl:when>\r
-\r
-          <xsl:otherwise>\r
-            <xsl:text>Variable </xsl:text>\r
-          </xsl:otherwise>\r
-        </xsl:choose>\r
-\r
-        <xsl:value-of select="name"/>\r
-      </title>\r
-\r
-      <programlisting language="c">\r
-        <xsl:value-of select="definition"/>\r
-      </programlisting>\r
+      <!-- Doxygen gets confused and thinks function pointer type definitions\r
+           are variables, so we need to map them to this common section and\r
+           check the definition to see which of the two it is. -->\r
+      <xsl:choose>\r
+        <xsl:when test="contains(definition,'typedef')">\r
+          <title> Type <xsl:value-of select="name"/></title>\r
+\r
+          <programlisting language="c">\r
+            <emphasis role="keyword">\r
+              <xsl:text>typedef </xsl:text>\r
+              <xsl:value-of select="type"/>\r
+            </emphasis>\r
+            <xsl:text> </xsl:text>\r
+            <xsl:value-of select="name"/>\r
+            <xsl:text> </xsl:text>\r
+            <xsl:value-of select="argsstring"/>\r
+          </programlisting>\r
+        </xsl:when>\r
+\r
+        <xsl:otherwise>\r
+          <title> Variable <xsl:value-of select="name"/></title>\r
+\r
+          <programlisting language="c">\r
+            <emphasis role="keyword">\r
+              <xsl:value-of select="type"/>\r
+            </emphasis>\r
+            <xsl:text> </xsl:text>\r
+            <xsl:value-of select="name"/>\r
+          </programlisting>\r
+        </xsl:otherwise>\r
+      </xsl:choose>\r
 \r
       <xsl:apply-templates select="detaileddescription"/>\r
 \r
@@ -269,7 +311,7 @@
 \r
   <xsl:template match="simplesect" mode="struct">\r
     <footnote>\r
-      <xsl:apply-templates select="para"/>\r
+      <xsl:apply-templates/>\r
     </footnote>\r
   </xsl:template>\r
 \r
@@ -324,8 +366,8 @@
               <title>To Do</title>\r
             </xsl:when>\r
 \r
-            <xsl:when test="$note.prefix = 'TIP:'">\r
-              <xsl:attribute name="role">tip</xsl:attribute>\r
+            <xsl:when test="$note.prefix = 'TIPS:'">\r
+              <xsl:attribute name="role">tips</xsl:attribute>\r
               <title>Tip</title>\r
             </xsl:when>\r
 \r
@@ -370,7 +412,7 @@
         <xsl:value-of select="$note.content"/>\r
       </xsl:when>\r
 \r
-      <xsl:when test="$note.prefix = 'TIP:'">\r
+      <xsl:when test="$note.prefix = 'TIPS:'">\r
         <xsl:value-of select="$note.content"/>\r
       </xsl:when>\r
 \r
@@ -402,8 +444,8 @@
       <tgroup cols="3">\r
         <thead>\r
           <row>\r
-            <entry>Data Direction</entry>\r
-            <entry>Parameter Name</entry>\r
+            <entry>Data direction</entry>\r
+            <entry>Parameter name</entry>\r
             <entry>Description</entry>\r
           </row>\r
         </thead>\r
@@ -424,7 +466,7 @@
       <tgroup cols="2">\r
         <thead>\r
           <row>\r
-            <entry>Return Value</entry>\r
+            <entry>Return value</entry>\r
             <entry>Description</entry>\r
           </row>\r
         </thead>\r
@@ -549,6 +591,18 @@
     <xsl:text>&#8482;</xsl:text>\r
   </xsl:template>\r
 \r
+  <xsl:template match="superscript">\r
+    <superscript>\r
+      <xsl:value-of select="."/>\r
+    </superscript>\r
+  </xsl:template>\r
+\r
+  <xsl:template match="subscript">\r
+    <subscript>\r
+      <xsl:value-of select="."/>\r
+    </subscript>\r
+  </xsl:template>\r
+\r
   <xsl:template match="ref">\r
     <xsl:choose>\r
       <!-- Don't show links inside program listings -->\r
@@ -558,9 +612,18 @@
 \r
       <!-- Show links outside program listings -->\r
       <xsl:otherwise>\r
-        <link linkend="{@refid}" xrefstyle="nopage">\r
-          <xsl:value-of select="text()"/>\r
-        </link>\r
+        <xsl:choose>\r
+          <!-- Use hard links for anchors to make the reference\r
+               look correct for figure and table references -->\r
+          <xsl:when test="//anchor[@id = current()/@refid]">\r
+            <xref linkend="{@refid}" xrefstyle="select: label title"/>\r
+          </xsl:when>\r
+          <xsl:otherwise>\r
+            <link linkend="{@refid}">\r
+              <xsl:value-of select="text()"/>\r
+            </link>\r
+          </xsl:otherwise>\r
+        </xsl:choose>\r
       </xsl:otherwise>\r
     </xsl:choose>\r
   </xsl:template>\r
@@ -578,7 +641,9 @@
   <xsl:template match="table">\r
     <xsl:choose>\r
       <xsl:when test="caption">\r
-        <table tabstyle="striped">\r
+        <!-- Fetch the ID using a preceding doxygen \anchor to be\r
+             able to reference tables -->\r
+        <table tabstyle="striped" id="{preceding-sibling::anchor[last()]/@id}">\r
           <title>\r
             <xsl:value-of select="caption"/>\r
           </title>\r
@@ -640,6 +705,11 @@
 \r
   <xsl:template match="programlisting">\r
     <programlisting language="c">\r
+      <!-- Only allow really long code segments to split across pages -->\r
+      <xsl:if test="count(codeline) > 30">\r
+        <xsl:processing-instruction name="dbfo">keep-together="auto"</xsl:processing-instruction>\r
+      </xsl:if>\r
+\r
       <xsl:for-each select="codeline[position() > 1 or highlight]">\r
         <xsl:apply-templates select="."/>\r
         <xsl:text>&#10;</xsl:text>\r
@@ -648,10 +718,7 @@
   </xsl:template>\r
 \r
   <xsl:template match="highlight">\r
-    <emphasis>\r
-      <xsl:attribute name="role">\r
-        <xsl:value-of select="@class"/>\r
-      </xsl:attribute>\r
+    <emphasis role="{@class}">\r
       <xsl:apply-templates/>\r
     </emphasis>\r
   </xsl:template>\r
@@ -660,7 +727,7 @@
     <xsl:choose>\r
       <!-- Need to check if this is the first part of the line - if so we may\r
            need to strip off any leading <sp/> element indentation -->\r
-      <xsl:when test="ancestor::highlight = ancestor::codeline/highlight[1]">\r
+      <xsl:when test="count(../preceding-sibling::highlight) = 0">\r
         <!-- Doxygen retains a level of indentation in some code fragments - obtain\r
              the base indentation level by counting the leading <sp/> elements of the\r
              first code line, and use that to remove the indentation on the rest -->\r
@@ -678,7 +745,9 @@
   </xsl:template>\r
 \r
   <xsl:template match="image">\r
-    <figure>\r
+    <!-- Fetch the ID using a preceding doxygen \anchor to be\r
+         able to reference figures -->\r
+    <figure id="{preceding-sibling::anchor[last()]/@id}">\r
       <title>\r
         <xsl:value-of select="."/>\r
       </title>\r
@@ -686,7 +755,10 @@
       <mediaobject>\r
         <imageobject>\r
           <imagedata scalefit="1" width="{@width}">\r
-            <xsl:attribute name="fileref">html/<xsl:value-of select="@name"/></xsl:attribute>\r
+            <xsl:attribute name="fileref">\r
+              <xsl:text>html/</xsl:text>\r
+              <xsl:value-of select="@name"/>\r
+            </xsl:attribute>\r
           </imagedata>\r
         </imageobject>\r
       </mediaobject>\r
@@ -694,20 +766,44 @@
   </xsl:template>\r
 \r
   <xsl:template match="anchor">\r
-    <anchor id="{@id}"/>\r
+    <!-- Remove anchors from the PDF output, as these are used for referencing\r
+         images and tables. -->\r
   </xsl:template>\r
 \r
   <xsl:template match="dot">\r
+    <!-- Fetch the ID using a preceding doxygen \anchor to be able to reference\r
+         figures -->\r
+    <xsl:variable name="dot.id" select="preceding-sibling::anchor[last()]/@id" />\r
+\r
+    <xsl:choose>\r
+      <!-- If the DOT graph has an ID, use that for the filename -->\r
+      <xsl:when test="$dot.id">\r
+        <xsl:call-template name="write.dot.content">\r
+          <xsl:with-param name="dot.filename" select="$dot.id"/>\r
+          <xsl:with-param name="dot.id" select="$dot.id"/>\r
+        </xsl:call-template>\r
+      </xsl:when>\r
+\r
+      <!-- Otherwise use the auto-generated ID for it in the document -->\r
+      <xsl:otherwise>\r
+        <xsl:call-template name="write.dot.content"/>\r
+      </xsl:otherwise>\r
+    </xsl:choose>\r
+  </xsl:template>\r
+\r
+  <xsl:template name="write.dot.content">\r
+    <xsl:param name="dot.filename" select="generate-id(.)"/>\r
+    <xsl:param name="dot.id" select="''"/>\r
+\r
     <!-- We get raw DOT syntax rather than a rendered image: write the DOT code\r
-         to a new unique file, and make a image reference to a SVG version of\r
-         that file. The build system should then call dot to render all generated\r
+         to a external file, and make a image reference to a SVG version of that\r
+         file. The build system should then call dot to render all generated\r
          DOT files into their SVG equivalents before rendering the PDF. -->\r
-    <xsl:variable name="filename" select="generate-id(.)" />\r
-    <exsl:document href="{$filename}.dot" method="text">\r
+    <exsl:document href="{$dot.filename}.dot" method="text">\r
       <xsl:value-of select="." />\r
     </exsl:document>\r
 \r
-    <figure>\r
+    <figure id="{$dot.id}">\r
       <title>\r
         <xsl:value-of select="ancestor::*/title"/>\r
       </title>\r
@@ -715,7 +811,7 @@
         <imageobject>\r
           <imagedata format="SVG">\r
             <xsl:attribute name="fileref">\r
-                <xsl:value-of select="$filename" />\r
+                <xsl:value-of select="$dot.filename" />\r
                 <xsl:text>.svg</xsl:text>\r
             </xsl:attribute>\r
           </imagedata>\r
@@ -724,14 +820,4 @@
     </figure>\r
   </xsl:template>\r
 \r
-  <xsl:template match="argsstring" name="split.functions.args">\r
-    <xsl:param name="text" select="."/>\r
-    <xsl:value-of select="substring-before(concat($text,','),',')"/>\r
-    <xsl:if test="contains($text,',')">\r
-      <xsl:text>,&#10;&#09;&#9;</xsl:text>\r
-      <xsl:call-template name="split.functions.args">\r
-        <xsl:with-param name="text" select="substring-after($text,',')"/>\r
-      </xsl:call-template>\r
-    </xsl:if>\r
-  </xsl:template>\r
 </xsl:stylesheet>\r

diff --git a/LUFA/StudioIntegration/makefile b/LUFA/StudioIntegration/makefile
index 3227997..af9563a 100644 (file)
--- a/LUFA/StudioIntegration/makefile
+++ b/LUFA/StudioIntegration/makefile
@@ -44,7 +44,8 @@ VSIX_ASSETS          := $(LUFA_ROOT)/DoxygenPages/Images/LUFA_thumb.png \
 MSHELP_GEN_PARAMS   := --stringparam generate.toc "book toc"            \
                        --stringparam chunk.quietly "1"                  \
                        --stringparam chunk.section.depth "3"            \
-                       --stringparam chunk.first.sections "1"
+                       --stringparam chunk.first.sections "1"           \
+                       --stringparam chapter.autolabel "0"
 
 all: generate_xml check_filenames generate_vsix