Update unoidl/README

Change-Id: Ib4cc138ab4c6de0d3d3a8ad55e40ba9ca30c15ae

unoidl/README

-Support for the new UNOIDL types.rdb format
-
-...that replaces the old types.rdb format based on modules [[store]] and
-[[registry]].
+Support for UNOIDL registry formats
 
 Library_unoidl contains the unoidl::Manager and unoidl::Provider implementations
-for both the new and the old types.rdb formats (unoidl::loadProvider tries both
-implementations in turn for a given file, so the old format is still supported
-transparently for now).
-
-Executable_unoidl-write is a helper tool to convert from the old to the new
-types.rdb format.  It is currently used at build-time.  idlc still generates the
-old format, and any new-format files (used at build-time only, or included in
-installation sets in URE or program/types/ or as part of bundled extensions that
-are created during the build and not merely included as pre-built .oxt files)
-are explicitly generated via unoidl-write.  The SDK is still designed to
-generate old-format files exclusively (especially, any non-bundled extensions
-will only contain old-format files for now; that allows to modify the new format
-further without having to worry about compatibility with multiple versions of
-that format).
+for the following registry formats:
+
+* The new UNOIDL binary types.rdb format.
+* The old legacy binary types.rdb format (based on modules [[store]] and
+  [[registry]]).
+* A source-file format, reading (multiple) UNOIDL entity definitions directly
+  from a single .idl source file.
+* A source-tree format, reading UNOIDL entity definitions directly from a tree
+  of .idl source files rooted at a given directory.  (Where an entity named
+  foo.bar.Baz is expected in a file named foo/bar/Baz.idl within that tree.)
+
+(While .idl files still contain #include directives for legacy idlc, the source-
+based formats ignore any preprocessing directives starting with "#" in the .idl
+files.)  unoidl::loadProvider transparently detects the registry format for a
+given URI and instantiates the corresponding provider implementation.
+
+Executable_unoidl-write is a helper tool to convert from any of the registry
+formats to the UNOIDL format.  It is currently used at build-time.  idlc still
+generates the old format, and any new-format files (used at build-time only, or
+included in installation sets in URE or program/types/ or as part of bundled
+extensions that are created during the build and not merely included as pre-
+built .oxt files) are explicitly generated via unoidl-write.  The SDK is still
+designed to generate old-format files exclusively (especially, any non-bundled
+extensions will only contain old-format files for now; that allows to modify the
+new format further without having to worry about compatibility with multiple
+versions of that format).
+
+Executable_unoidl-read is a helper tool to convert from any of the registry
+formats to the source-file format.  It can be used manually after a LibreOffice
+version update to create new reference registries for Executable_unoidl-check.
+
+Executable_unoidl-check is a helper tool to check that one registry is
+backwards-compatible with another registry.  It is used at build-time to detect
+inadvertent breakage of the udkapi and offapi APIs.
 
 == Specification of the new UNOIDL types.rdb format ==