Provide unoidl-write also for the SDK

...after the new types.rdb format that unoidl-write generates has been used
internally since LibreOffice 4.1 in 2013; following up on
6db34b6b33ba8e3b13683efd05df8441b87e9c92 "Directly build UNOIDL .rdb files from
.idl files" and its "The legacy tools idlc, regcompare, regmerge, and regview
are still contained in the URE or SDK for now."

The tools idlc and regmerge are deprecated but still shipped in the SDK for now.
The plan is to drop them completely for LO 7.5.

odk/examples/ and ure/source/uretest/ are adapted to use unoidl-write instead of
idlc and regmerge:

* unoidl-write does not use a C preprocessor and the # directives in .idl files,
it supports reading a single .idl file (containing an arbitrary number of
declarations) or a directory tree where each directory corresponds to a UNOIDL
module of the same name and each .idl file contains the declaration of the
(non-module) UNOIDL entity of the same name.  For some of the odk/examples/,
that required moving individual .idl files into sub-directories named after
the respective modules.  In odk/settings/std.mk, definitinos of IDL and
REGMERGE have been replaced with a new UNOIDLWRITE.

* unoidl-write always enforces reserved UNOIDL identifier restrictions (see
04af4e4f55f3ef319a78edd4d0109e2e7eba90b6 "[API CHANGE] Fix all bad UNOIDL
identifiers across offapi" and 620179240670bd00f60555f1f5c5b0268492f97c
"Enforce the UNOIDL identifier scheme") (which idlc only enforced optionally
with -cid -we).  That required renaming "my_module" in
odk/examples/DevelopersGuide/Components/CppComponent/.

* The new types.rdb format is not compatibly with LibreOffice < 4.1.  Clients
generating extensions containing such files are advised to use appropriate
LibreOffice-minimal-version elements.

Change-Id: I1a248fd96e86ecbf407f829bc100d44bfe7f4e7d
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/130533
Tested-by: Jenkins
Reviewed-by: Stephan Bergmann <sbergman@redhat.com>

1 files changed, 89 insertions, 16 deletions

diff --git a/odk/docs/tools.html b/odk/docs/tools.html
index 2785f9f3eb64..e145e059de9b 100644
--- a/odk/docs/tools.html
+++ b/odk/docs/tools.html
@@ -71,13 +71,13 @@
            <tr valign="top">
               <td class="content3"><img src="images/arrow-1.gif"/></td>
               <td><a href="#regmerge"  title="link to the regmerge tool description">regmerge</a></td>
-              <td class="content87">Tool to merge several registry (e.g. type
+              <td class="content87">Deprecated tool to merge several legacy registry (e.g. type
 			  libraries) files into one file. <b>Note:</b> Since OpenOffice.org 3 it is no longer part of the SDK but it comes directly with the office as part of the <b>ure</b>.</td>
             </tr>
             <tr valign="top">
               <td class="content3"><img src="images/arrow-1.gif"/></td>
               <td><a href="#regview"  title="link to the regview tool description">regview</a></td>
-              <td class="content87">Tool to view the content of a registry file
+              <td class="content87">Tool to view the content of a legacy registry file
 			  in a human readable manner. Special support for type library
 			  nodes. <b>Note:</b> Since OpenOffice.org 3 it is no longer part of the SDK but it comes directly with the office as part of the <b>ure</b>.</td>
             </tr>
@@ -87,7 +87,14 @@
             <tr valign="top">
               <td class="content3"><img src="images/arrow-1.gif"/></td>
               <td><a href="#idlc" title="link to the idlc tool description">idlc</a></td>
-              <td class="content87">The UNOIDL compiler, generates a common
+              <td class="content87">The deprecated UNOIDL compiler, generates a common
+			  legacy binary type library format as base for all codemaker tools and
+			  the UNO runtime type library.</td>
+            </tr>
+            <tr valign="top">
+              <td class="content3"><img src="images/arrow-1.gif"/></td>
+              <td><a href="#unoidl-write" title="link to the unoidl-write tool description">unoidl-write</a></td>
+              <td class="content87">The new UNOIDL compiler, generates a common
 			  binary type library format as base for all codemaker tools and
 			  the UNO runtime type library.</td>
             </tr>
@@ -117,13 +124,13 @@
             <tr valign="top">
               <td class="content3"><img src="images/arrow-1.gif"/></td>
               <td><a href="#regmerge"  title="link to the regmerge tool description">regmerge</a></td>
-              <td class="content87">Tool to merge several registry (e.g. type
+              <td class="content87">Deprecated tool to merge several legacy registry (e.g. type
 			  libraries) files into one file.</td>
             </tr>
             <tr valign="top">
               <td class="content3"><img src="images/arrow-1.gif"/></td>
               <td><a href="#regview"  title="link to the regview tool description">regview</a></td>
-              <td class="content87">Tool to view the content of a registry file
+              <td class="content87">Tool to view the content of a legacy registry file
 			  in a human readable manner. Special support for type library
 			  nodes.</td>
             </tr>
@@ -345,11 +352,14 @@
         </tr>
 		<tr>
 		  <td colspan="3">
-		  <p>'idlc' is the UNOIDL compiler.  It is a full featured compiler used
+		  <p>'idlc' is the deprecated UNOIDL compiler.  It is a full featured compiler used
 		  to check UNODL type definitions and transform valid type definitions
 		  into a binary type library format, which is later used by all codemaker
 		  tools. It is also used as a dynamic type library for UNO at runtime.<br/>
 		  You can find a syntax description for UNOIDL <a href="http://wiki.openoffice.org/wiki/Documentation/DevGuide/AppendixD/UNOIDL_Syntax_Specification" title="link to the &quot;UNOIDL Syntax Specification&quot; chapter in the Developer's Guide">here</a>.</p>
+		  <p><b>Note:</b> idlc and regmerge are deprecated and produce a legacy binary type
+		  library format that is different from the new format that is produced by
+		  unoidl-write.</p>
 		  <p class="head2">Usage:</p>
 		  <blockquote>
 		  <b><code>idlc [-options] file_1 ... file_n | @&lt;filename&gt;</code></b>
@@ -371,7 +381,7 @@
 		  <tr>
             <td class="cell15"><code>-O&lt;path&gt;</code></td>
 			<td class="cell85">path describes the output directory. The
-			generated output is a registry file with the same name as the idl
+			generated output is a legacy registry file with the same name as the idl
 			input file.</td>
           </tr>
           <tr>
@@ -408,6 +418,66 @@
     <td>
       <table class="table2">
         <tr>
+		  <td colspan="2" class="head1"><a name="unoidl-write"/>unoidl-write</td>
+		  <td align="right">
+		    <a href="#tools" title="link to the tools overview"><img class="navigate" src="images/nav_up.png"/></a>
+		    <a href="../index.html" title="link to the SDK start page"><img class="navigate" src="images/nav_home.png"/></a>
+		  </td>
+        </tr>
+		<tr>
+		  <td colspan="3">
+		  <p>'unoidl-write' is the new UNOIDL compiler, replacing the former idlc and regmerge tools.  It is a full featured compiler used
+		  to check UNODL type definitions and transform valid type definitions
+		  into a binary type library format, which is later used by all codemaker
+		  tools. It is also used as a dynamic type library for UNO at runtime.<br/>
+		  You can find a syntax description for UNOIDL <a href="http://wiki.openoffice.org/wiki/Documentation/DevGuide/AppendixD/UNOIDL_Syntax_Specification" title="link to the &quot;UNOIDL Syntax Specification&quot; chapter in the Developer's Guide">here</a>.</p>
+		  <p><b>Note:</b> unoidl-write produces a new binary type library format that is
+		  different from the legacy format that was produced by idlc and regmerge.  While
+		  recent versions of LibreOffice are still able to read the old format, versions of
+		  LibreOffice prior to LibreOffice&nbsp;4.1 were not able to read the new format.
+		  Thus, if you use this SDK to generate a LibreOffice extension that contains a type
+		  library file produced by unoidl-write, you should specify a
+		  <code>LibreOffice-minimal-version</code> of at least&nbsp;4.1 for that extension
+		  (see <a
+		  href="https://wiki.documentfoundation.org/Development/Extension_Development#Compatibility_notes">&ldquo;Extension
+		  Development: Compatibility notes&rdquo;</a>).</p>
+		  <p class="head2">Usage:</p>
+		  <blockquote>
+		  <b><code>unoidl-write [&lt;registries&gt;] [@&lt;entries file&gt;] &lt;unoidl file&gt;</code></b>
+		  </blockquote>
+		  <table class="table4">
+		  <tr>
+            <td class="cell15"><code>&lt;registries&gt;</code></td>
+			<td class="cell85">each <code>&lt;registry&gt;</code> is either a new- or
+			legacy-format .rdb file, a single .idl file, or a root directory of an .idl
+			file tree.</td>
+          </tr>
+		  <tr>
+            <td class="cell15"><code>@&lt;entries file&gt;</code></td>
+			<td class="cell85">a UTF-8 encoded file containing zero or more
+			space-separated names of (non-module) entities to include in the output; if
+			omitted, the output defaults to the complete content of the last
+			<code>&lt;registry&gt;</code>, if any.</td>
+          </tr>
+		  <tr>
+            <td class="cell15"><code>@&lt;unoidl file&gt;</code></td>
+			<td class="cell85">specifies the name of the output file.</td>
+          </tr>
+		  </table>
+		  </td>
+		</tr>
+      </table>
+    </td>
+    <td class="content1"><img class="nothing8" src="images/nada.gif"/></td>
+  </tr>
+  <tr>
+    <td colspan="3"><img class="line" src="images/sdk_line-1.gif"/></td>
+  </tr>
+  <tr>
+    <td class="content1"><img class="nothing8" src="images/nada.gif"/></td>
+    <td>
+      <table class="table2">
+        <tr>
 		  <td colspan="2" class="head1"><a name="cppumaker"/>cppumaker</td>
 		  <td align="right">
 		    <a href="#tools" title="link to the tools overview"><img class="navigate" src="images/nav_up.png"/></a>
@@ -418,8 +488,8 @@
 		  <td colspan="3">
 		  <p>The 'cppumaker' generates a C++ representation for idl types. The
 		  cppumaker works on a typelibrary, which is generated by the UNOIDL
-		  compiler (<a href="#idlc" title="link to the idlc tool description">
-		  idlc</a>). It generates the output for all specified types and for all
+		  compiler (<a href="#unoidl-write" title="link to the unoidl-write tool description">
+		  unoidl-write</a>). It generates the output for all specified types and for all
 		  types the specified types depend on.</p>
 		  <p class="head2">Usage:</p>
 		  <blockquote>
@@ -509,8 +579,8 @@
 		  <td colspan="3">
 		  <p>The 'javamaker' generates the appropriate Java class file for each idl
 		  type. The javamaker works on a typelibrary which is generated by the
-		  UNOIDL compiler (<a href="#idlc" title="link to the idlc tool description">
-		  idlc</a>). It generates the output for all specified types and for all
+		  UNOIDL compiler (<a href="#unoidl-write" title="link to the unoidl-write tool description">
+		  unoidl-write</a>). It generates the output for all specified types and for all
 types the specified types depend on.</p>
 		  <p class="head2">Usage:</p>
 		  <blockquote>
@@ -588,8 +658,8 @@ types the specified types depend on.</p>
 		  <td colspan="3">
 		  <p>The 'climaker' (windows only) generates the appropriate CLI assemblies file for each idl
 		  type. The climaker works on a typelibrary which is generated by the
-		  UNOIDL compiler (<a href="#idlc" title="link to the idlc tool description">
-		  idlc</a>). It generates the output for all specified types and for all
+		  UNOIDL compiler (<a href="#unoidl-write" title="link to the unoidl-write tool description">
+		  unoidl-write</a>). It generates the output for all specified types and for all
 		    types the specified types depend on.</p>
 		  <p class="head2">Usage:</p>
 		  <blockquote>
@@ -796,10 +866,13 @@ types the specified types depend on.</p>
         </tr>
 		<tr>
 		  <td colspan="3">
-		  <p>'regmerge' is a small tool to merge different registry files under a
-		  specified key into another registry file. If a value already exists in
+		  <p>The deprecated 'regmerge' is a small tool to merge different legacy registry files under a
+		  specified key into another legacy registry file. If a value already exists in
 		  the target file the value is overwritten by the value of the source
 		  file.</p>
+		  <p><b>Note:</b> idlc and regmerge are deprecated and produce a legacy binary type
+		  library format that is different from the new format that is produced by
+		  unoidl-write.</p>
 		  <p class="head2">Usage:</p>
 		  <blockquote>
 		  <b><code>regmerge [-v|--verbose] &lt;mergefile&gt; &lt;mergeKeyName&gt; &lt;regfile_1&gt; ... &lt;regfile_n&gt;</code></b>
@@ -848,7 +921,7 @@ types the specified types depend on.</p>
         </tr>
 		<tr>
 		  <td colspan="3">
-		  <p>'regview' is a tool to show the contents of a registry file. The tool
+		  <p>'regview' is a tool to show the contents of a legacy registry file. The tool
 		  dumps the hierarchical structure and the values of the nodes in a human
 		  readable manner to stdout.</p>
 		  <p class="head2">Usage:</p>