From f215e02bf85f68d3a6106c2a1f4f7f063f819064 Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Thu, 11 Apr 2024 10:17:27 +0200
Subject: Adding upstream version 7.0.14-dfsg.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 doc/manual/xidl2docbook.xsl | 588 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 588 insertions(+)
 create mode 100644 doc/manual/xidl2docbook.xsl

(limited to 'doc/manual/xidl2docbook.xsl')

diff --git a/doc/manual/xidl2docbook.xsl b/doc/manual/xidl2docbook.xsl
new file mode 100644
index 00000000..67c6c0a4
--- /dev/null
+++ b/doc/manual/xidl2docbook.xsl
@@ -0,0 +1,588 @@
+<?xml version="1.0"?>
+
+<!--
+    xidl2docbook.xsl:
+        XSLT stylesheet that generates docbook from
+        VirtualBox.xidl.
+-->
+<!--
+    Copyright (C) 2006-2023 Oracle and/or its affiliates.
+
+    This file is part of VirtualBox base platform packages, as
+    available from https://www.virtualbox.org.
+
+    This program is free software; you can redistribute it and/or
+    modify it under the terms of the GNU General Public License
+    as published by the Free Software Foundation, in version 3 of the
+    License.
+
+    This program is distributed in the hope that it will be useful, but
+    WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, see <https://www.gnu.org/licenses>.
+
+    SPDX-License-Identifier: GPL-3.0-only
+-->
+
+<xsl:stylesheet
+  version="1.0"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:exsl="http://exslt.org/common"
+  extension-element-prefixes="exsl">
+
+  <xsl:output
+             method="xml"
+             version="1.0"
+             encoding="utf-8"
+             indent="yes"/>
+
+  <xsl:strip-space elements="*"/>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - -
+  Keys for more efficiently looking up of types.
+ - - - - - - - - - - - - - - - - - - - - - - -->
+
+<xsl:key name="G_keyEnumsByName"        match="//enum[@name]"       use="@name"/>
+<xsl:key name="G_keyInterfacesByName"   match="//interface[@name]"  use="@name"/>
+<xsl:key name="G_keyResultsByName"      match="//result[@name]"     use="@name"/>
+
+<!-- - - - - - - - - - - - - - - - - - - - - - -
+  global XSLT variables
+ - - - - - - - - - - - - - - - - - - - - - - -->
+
+<xsl:variable name="G_xsltFilename" select="'glue-jaxws.xsl'" />
+
+<!-- collect all interfaces with "wsmap='suppress'" in a global variable for
+     quick lookup -->
+<xsl:variable name="G_setSuppressedInterfaces"
+              select="//interface[@wsmap='suppress']" />
+
+<xsl:template name="makeLinkId">
+  <xsl:param name="ifname" />
+  <xsl:param name="member" />
+  <xsl:value-of select="concat($ifname, '__', $member)"/>
+</xsl:template>
+
+<xsl:template name="emitType">
+  <xsl:param name="type" />
+  <xsl:choose>
+    <xsl:when test="$type">
+      <xsl:choose>
+        <xsl:when test="count(key('G_keyInterfacesByName',$type)) > 0">
+          <link>
+            <xsl:attribute name="linkend">
+              <xsl:value-of select="translate($type, ':', '_')" />
+            </xsl:attribute>
+            <xsl:value-of select="$type" />
+          </link>
+        </xsl:when>
+        <xsl:when test="count(key('G_keyEnumsByName',$type)) > 0">
+          <link>
+            <xsl:attribute name="linkend">
+              <xsl:value-of select="translate($type, ':', '_')" />
+            </xsl:attribute>
+            <xsl:value-of select="$type" />
+          </link>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="$type" />
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:value-of select="'void'" />
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+<xsl:template name="isWebserviceOnly">
+  <xsl:for-each select="ancestor-or-self::*">
+    <xsl:if test="(name()='if') and (@target='wsdl')">
+      <xsl:text>yes</xsl:text>
+    </xsl:if>
+  </xsl:for-each>
+</xsl:template>
+
+
+<!-- - - - - - - - - - - - - - - - - - - - - - -
+  root match
+ - - - - - - - - - - - - - - - - - - - - - - -->
+
+<xsl:template match="/idl">
+ <book> <!-- Need a single top-level element for xi:include, we'll skip it using xpointer. -->
+  <chapter id="sdkref_classes">
+    <title>Classes (interfaces)</title>
+    <xsl:for-each select="//interface">
+      <xsl:sort select="@name"/>
+
+      <!-- ignore those interfaces within module sections; they don't have uuid -->
+      <xsl:if test="@uuid">
+        <xsl:variable name="ifname" select="@name" />
+        <xsl:variable name="wsmap" select="@wsmap" />
+        <xsl:variable name="wscpp" select="@wscpp" />
+        <xsl:variable name="wsonly"><xsl:call-template name="isWebserviceOnly" /></xsl:variable>
+        <xsl:variable name="extends" select="@extends" />
+        <xsl:variable name="reportExtends" select="not($extends='$unknown') and not($extends='$errorinfo')" />
+
+        <sect1>
+          <xsl:attribute name="id">
+            <xsl:value-of select="$ifname" />
+          </xsl:attribute>
+          <title><xsl:value-of select="$ifname" />
+              <xsl:if test="$reportExtends">
+              <xsl:value-of select="concat(' (', @extends, ')')" />
+            </xsl:if>
+          </title>
+
+          <xsl:choose>
+            <xsl:when test="$wsmap='suppress'">
+              <para><note><para>
+                This interface is not supported in the web service.
+              </para></note></para>
+            </xsl:when>
+            <xsl:when test="$wsmap='struct'">
+              <para><note><para>With the web service, this interface is mapped to a structure. Attributes that return this interface will not return an object, but a complete structure
+              containing the attributes listed below as structure members.</para></note></para>
+            </xsl:when>
+            <xsl:when test="$wsonly='yes'">
+              <para><note><para>This interface is supported in the web service only, not in COM/XPCOM.</para></note></para>
+            </xsl:when>
+          </xsl:choose>
+
+          <xsl:if test="$reportExtends">
+            <para><note><para>
+                This interface extends
+                <link>
+                  <xsl:attribute name="linkend"><xsl:value-of select="$extends" /></xsl:attribute>
+                  <xsl:value-of select="$extends" />
+                </link>
+                and therefore supports all its methods and attributes as well.
+            </para></note></para>
+          </xsl:if>
+
+          <xsl:apply-templates select="desc" />
+
+          <xsl:if test="attribute">
+            <sect2>
+              <title>Attributes</title>
+              <xsl:for-each select="attribute">
+                <xsl:variable name="attrtype" select="@type" />
+                <sect3>
+                  <xsl:attribute name="id">
+                    <xsl:call-template name="makeLinkId">
+                      <xsl:with-param name="ifname" select="$ifname" />
+                      <xsl:with-param name="member" select="@name" />
+                    </xsl:call-template>
+                  </xsl:attribute>
+                  <title>
+                    <xsl:choose>
+                      <xsl:when test="@readonly='yes'">
+                        <xsl:value-of select="concat(@name, ' (read-only)')" />
+                      </xsl:when>
+                      <xsl:otherwise>
+                        <xsl:value-of select="concat(@name, ' (read/write)')" />
+                      </xsl:otherwise>
+                    </xsl:choose>
+                  </title>
+                  <programlisting>
+                    <xsl:call-template name="emitType">
+                      <xsl:with-param name="type" select="$attrtype" />
+                    </xsl:call-template>
+                    <xsl:value-of select="concat(' ', $ifname, '::', @name)" />
+                    <xsl:if test="(@array='yes') or (@safearray='yes')">
+                      <xsl:text>[]</xsl:text>
+                    </xsl:if>
+                  </programlisting>
+                  <xsl:if test="( ($attrtype=($G_setSuppressedInterfaces/@name)) )">
+                    <para><note><para>
+                      This attribute is not supported in the web service.
+                    </para></note></para>
+                  </xsl:if>
+                  <xsl:apply-templates select="desc" />
+                </sect3>
+              </xsl:for-each>
+            </sect2>
+          </xsl:if>
+
+          <xsl:if test="method">
+<!--             <sect2> -->
+<!--               <title>Methods</title> -->
+              <xsl:for-each select="method">
+                <xsl:sort select="@name" />
+                <xsl:variable name="returnidltype" select="param[@dir='return']/@type" />
+                <sect2>
+                  <xsl:attribute name="id">
+                    <xsl:call-template name="makeLinkId">
+                      <xsl:with-param name="ifname" select="$ifname" />
+                      <xsl:with-param name="member" select="@name" />
+                    </xsl:call-template>
+                  </xsl:attribute>
+                  <title>
+                    <xsl:value-of select="@name" />
+                  </title>
+                  <xsl:if test="   (param[@type=($G_setSuppressedInterfaces/@name)])
+                                or (param[@mod='ptr'])" >
+                    <para><note><para>
+                      This method is not supported in the web service.
+                    </para></note></para>
+                  </xsl:if>
+                  <!-- make a set of all parameters with in and out direction -->
+                  <xsl:variable name="paramsinout" select="param[@dir='in' or @dir='out']" />
+                  <programlisting>
+                    <!--emit return type-->
+                    <xsl:call-template name="emitType">
+                      <xsl:with-param name="type" select="$returnidltype" />
+                    </xsl:call-template>
+                    <xsl:if test="(param[@dir='return']/@array='yes') or (param[@dir='return']/@safearray='yes')">
+                      <xsl:text>[]</xsl:text>
+                    </xsl:if>
+                    <xsl:value-of select="concat(' ', $ifname, '::', @name, '(')" />
+                    <xsl:if test="$paramsinout">
+                      <xsl:for-each select="$paramsinout">
+                        <xsl:text>&#10;</xsl:text>
+                        <xsl:value-of select="concat('           [', @dir, '] ')" />
+                        <xsl:if test="@mod = 'ptr'">
+                          <xsl:text>[ptr] </xsl:text>
+                        </xsl:if>
+                        <xsl:call-template name="emitType">
+                          <xsl:with-param name="type" select="@type" />
+                        </xsl:call-template>
+                        <emphasis role="bold">
+                          <xsl:value-of select="concat(' ', @name)" />
+                        </emphasis>
+                        <xsl:if test="(@array='yes') or (@safearray='yes')">
+                          <xsl:text>[]</xsl:text>
+                        </xsl:if>
+                        <xsl:if test="not(position()=last())">
+                          <xsl:text>, </xsl:text>
+                        </xsl:if>
+                      </xsl:for-each>
+                    </xsl:if>
+                    <xsl:text>)</xsl:text>
+                  </programlisting>
+
+                  <xsl:if test="$paramsinout">
+                    <glosslist>
+                      <xsl:for-each select="$paramsinout">
+                        <glossentry>
+                          <glossterm>
+                            <xsl:value-of select="@name" />
+                          </glossterm>
+                          <glossdef>
+                            <xsl:if test="not(desc)">
+                              <para/>
+                            </xsl:if>
+                            <xsl:apply-templates select="desc" />
+                          </glossdef>
+                        </glossentry>
+                      </xsl:for-each>
+                    </glosslist>
+                  </xsl:if>
+
+                  <!-- dump the description here -->
+                  <xsl:apply-templates select="desc" />
+
+                  <xsl:if test="desc/result">
+                    <para>If this method fails, the following error codes may be reported:</para>
+                    <itemizedlist>
+                      <xsl:for-each select="desc/result">
+                        <listitem>
+                          <para><code><xsl:value-of select="@name" />: </code>
+                            <xsl:apply-templates />
+                          </para>
+                        </listitem>
+                      </xsl:for-each>
+                    </itemizedlist>
+                  </xsl:if>
+                </sect2>
+              </xsl:for-each>
+<!--             </sect2> -->
+          </xsl:if>
+
+        </sect1>
+      </xsl:if>
+    </xsl:for-each>
+  </chapter>
+
+  <chapter id="sdkref_enums">
+    <title>Enumerations (enums)</title>
+    <xsl:for-each select="//enum">
+      <xsl:sort select="@name"/>
+
+      <xsl:variable name="ifname" select="@name" />
+      <xsl:variable name="wsmap" select="@wsmap" />
+      <xsl:variable name="wscpp" select="@wscpp" />
+
+      <sect1>
+        <xsl:attribute name="id">
+          <xsl:value-of select="$ifname" />
+        </xsl:attribute>
+        <title><xsl:value-of select="$ifname" /></title>
+
+        <xsl:apply-templates select="desc" />
+
+        <glosslist>
+          <xsl:for-each select="const">
+            <glossentry>
+              <glossterm>
+                <xsl:attribute name="id">
+                  <xsl:call-template name="makeLinkId">
+                    <xsl:with-param name="ifname" select="$ifname" />
+                    <xsl:with-param name="member" select="@name" />
+                  </xsl:call-template>
+                </xsl:attribute>
+                <xsl:value-of select="@name" />
+              </glossterm>
+              <glossdef>
+                <xsl:if test="not(desc)">
+                  <para/>
+                </xsl:if>
+                <xsl:apply-templates select="desc" />
+              </glossdef>
+            </glossentry>
+          </xsl:for-each>
+        </glosslist>
+      </sect1>
+    </xsl:for-each>
+  </chapter>
+ </book>
+</xsl:template>
+
+<!-- - - - - - - - - - - - - - - - - - - - - - -
+  if
+ - - - - - - - - - - - - - - - - - - - - - - -->
+
+<!--
+ *  ignore all |if|s except those for WSDL target
+-->
+<xsl:template match="if">
+    <xsl:if test="@target='wsdl'">
+        <xsl:apply-templates/>
+    </xsl:if>
+</xsl:template>
+
+<!-- - - - - - - - - - - - - - - - - - - - - - -
+  cpp
+ - - - - - - - - - - - - - - - - - - - - - - -->
+
+<xsl:template match="cpp">
+<!--  ignore this -->
+</xsl:template>
+
+<!-- - - - - - - - - - - - - - - - - - - - - - -
+     result
+     - - - - - - - - - - - - - - - - - - - - - - -->
+
+<xsl:template match="result">
+  <!--  ignore this, we handle them explicitly in method loops -->
+</xsl:template>
+
+<!-- - - - - - - - - - - - - - - - - - - - - - -
+  library
+ - - - - - - - - - - - - - - - - - - - - - - -->
+
+<xsl:template match="library">
+  <xsl:apply-templates />
+</xsl:template>
+
+<!-- - - - - - - - - - - - - - - - - - - - - - -
+  class
+ - - - - - - - - - - - - - - - - - - - - - - -->
+
+<xsl:template match="module/class">
+<!--  TODO swallow for now -->
+</xsl:template>
+
+<!-- - - - - - - - - - - - - - - - - - - - - - -
+  enum
+ - - - - - - - - - - - - - - - - - - - - - - -->
+
+<xsl:template match="enum">
+</xsl:template>
+
+<!-- - - - - - - - - - - - - - - - - - - - - - -
+  const
+ - - - - - - - - - - - - - - - - - - - - - - -->
+
+<!--
+<xsl:template match="const">
+  <xsl:apply-templates />
+</xsl:template>
+-->
+
+<!-- - - - - - - - - - - - - - - - - - - - - - -
+  desc
+ - - - - - - - - - - - - - - - - - - - - - - -->
+
+<xsl:template match="desc">
+  <!-- todo: wrapping the entire content in a single para is actually not
+       entirely correct, as it contains empty lines denoting new paragraphs -->
+  <para>
+  <xsl:apply-templates />
+  </para>
+</xsl:template>
+
+<xsl:template name="getCurrentInterface">
+  <xsl:for-each select="ancestor-or-self::*">
+    <xsl:if test="name()='interface'">
+      <xsl:value-of select="@name"/>
+    </xsl:if>
+  </xsl:for-each>
+</xsl:template>
+
+<!-- <link to="DeviceType::HardDisk"/> -->
+<xsl:template match="link">
+  <link>
+    <xsl:variable name="tmp" select="@to" />
+    <xsl:variable name="enumNameFromCombinedName">
+        <xsl:value-of select="substring-before($tmp, '_')" />
+    </xsl:variable>
+    <xsl:variable name="enumValueFromCombinedName">
+        <xsl:value-of select="substring-after($tmp, '_')" />
+    </xsl:variable>
+    <xsl:choose>
+      <xsl:when test="count(key('G_keyInterfacesByName',$tmp)) > 0 or count(key('G_keyEnumsByName',$tmp)) > 0"><!-- link to interface only -->
+        <xsl:attribute name="linkend"><xsl:value-of select="@to" /></xsl:attribute>
+        <xsl:value-of select="$tmp" />
+      </xsl:when>
+      <xsl:when test="count(key('G_keyEnumsByName',$enumNameFromCombinedName)) > 0">
+        <xsl:attribute name="linkend">
+          <xsl:value-of select="concat($enumNameFromCombinedName, '__', $enumValueFromCombinedName)" />
+        </xsl:attribute>
+        <xsl:value-of select="$enumValueFromCombinedName" />
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:variable name="currentif">
+          <xsl:call-template name="getCurrentInterface" />
+        </xsl:variable>
+        <xsl:variable name="if"><!-- interface -->
+          <xsl:choose>
+            <xsl:when test="contains(@to, '#')">
+              <xsl:value-of select="$currentif" />
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:value-of select="substring-before(@to, '::')" />
+            </xsl:otherwise>
+          </xsl:choose>
+        </xsl:variable>
+        <xsl:variable name="member"><!-- member in that interface -->
+          <xsl:choose>
+            <xsl:when test="contains(@to, '#')">
+              <xsl:value-of select="substring-after(@to, '#')" />
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:value-of select="substring-after(@to, '::')" />
+            </xsl:otherwise>
+          </xsl:choose>
+        </xsl:variable>
+
+        <xsl:attribute name="linkend"><xsl:value-of select="concat($if, '__', $member)" /></xsl:attribute>
+        <xsl:variable name="autotextsuffix">
+          <xsl:choose>
+            <!-- if link points to a method, append "()" -->
+            <xsl:when test="key('G_keyInterfacesByName',$if)/method[@name=$member]">
+              <xsl:value-of select="'()'" />
+            </xsl:when>
+            <!-- if link points to a safearray attribute, append "[]" -->
+            <xsl:when test="key('G_keyInterfacesByName',$if)/attribute[@name=$member]/@safearray = 'yes'">
+              <xsl:value-of select="'[]'" />
+            </xsl:when>
+            <xsl:when test="key('G_keyInterfacesByName',$if)/attribute[@name=$member]"/>
+            <xsl:when test="key('G_keyEnumsByName',$if)/const[@name=$member]"/>
+            <xsl:when test="count(key('G_keyResultsByName',$tmp)) > 0"/>
+            <xsl:otherwise>
+              <xsl:message terminate="yes">
+                <xsl:value-of select="concat('Invalid link pointing to &quot;', $tmp, '&quot;')" />
+              </xsl:message>
+            </xsl:otherwise>
+          </xsl:choose>
+        </xsl:variable>
+        <xsl:choose>
+          <xsl:when test="./text()"><!-- link text given in source -->
+            <xsl:apply-templates />
+          </xsl:when>
+          <xsl:when test="$if=$currentif"><!-- "near" link to method or attribute in current interface -->
+            <xsl:value-of select="concat($member, $autotextsuffix)" />
+          </xsl:when>
+          <xsl:otherwise><!-- "far" link to other method or attribute -->
+            <xsl:value-of select="concat($if, '::', $member, $autotextsuffix)" />
+          </xsl:otherwise>
+        </xsl:choose>
+      </xsl:otherwise>
+    </xsl:choose>
+  </link>
+</xsl:template>
+
+<!-- - - - - - - - - - - - - - - - - - - - - - -
+  note
+ - - - - - - - - - - - - - - - - - - - - - - -->
+
+<xsl:template match="note">
+  <xsl:if test="not(@internal='yes')">
+    <note><para>
+      <xsl:apply-templates />
+    </para></note>
+  </xsl:if>
+</xsl:template>
+
+<xsl:template match="tt">
+  <computeroutput>
+    <xsl:apply-templates />
+  </computeroutput>
+</xsl:template>
+
+<xsl:template match="b">
+  <emphasis role="bold">
+    <xsl:apply-templates />
+  </emphasis>
+</xsl:template>
+
+<xsl:template match="i">
+  <emphasis>
+    <xsl:apply-templates />
+  </emphasis>
+</xsl:template>
+
+<xsl:template match="see">
+  <xsl:text>See also: </xsl:text>
+  <xsl:apply-templates />
+</xsl:template>
+
+<xsl:template match="ul">
+  <itemizedlist>
+    <xsl:apply-templates />
+  </itemizedlist>
+</xsl:template>
+
+<xsl:template match="ol">
+  <orderedlist>
+    <xsl:apply-templates />
+  </orderedlist>
+</xsl:template>
+
+<xsl:template match="li">
+  <listitem>
+    <para>
+      <xsl:apply-templates />
+    </para>
+  </listitem>
+</xsl:template>
+
+<xsl:template match="h3">
+  <emphasis role="bold">
+    <xsl:apply-templates />
+  </emphasis>
+</xsl:template>
+
+<xsl:template match="pre">
+  <screen><xsl:apply-templates /></screen>
+</xsl:template>
+
+<xsl:template match="table">
+  <xsl:apply-templates /> <!-- todo -->
+</xsl:template>
+
+</xsl:stylesheet>
-- 
cgit v1.2.3