Add PACKAGE-README.md

9 files changed, 80 insertions, 21 deletions

diff --git a/PACKAGE-README.md b/PACKAGE-README.md
new file mode 100644
index 0000000..4a1ce70
--- /dev/null
+++ b/PACKAGE-README.md
@@ -0,0 +1,66 @@
+# XSD
+
+XSD is an open-source, cross-platform XML Schema to C++ data binding
+compiler. Provided with an XML document specification (XML Schema), it
+generates C++ classes that represent the given vocabulary as well as XML
+parsing and serialization code. You can then access the data stored in XML
+using types and functions that semantically correspond to your application
+domain rather than dealing with generic elements/attributes and raw strings.
+
+For further information, refer to the [XSD project
+page](https://codesynthesis.com/products/xsd/).
+
+## Usage
+
+XSD consists of several packages with the main ones being `xsd` (the XML
+Schema to C++ compiler) and `libxsd` (the runtime library). There are also
+several `*-tests` packages as well as `xsd-examples`.
+
+When specifying dependencies on XSD packages in your project, the `xsd`
+package should be a build-time dependency. The `libxsd` library is
+header-only and because it can be used either with Xerces-C++ or
+Expat as the underlying XML parser, it does not have a dependency on
+either, expecting your project to make the choice by depending on
+one or the other explicitly and then importing and linking the
+corresponding library.
+
+So, putting it all together, your project's `manifest` would normally
+have the following fragment if using Xerces-C++:
+
+```
+depends: * xsd ^4.2.0
+depends: libxsd ^4.2.0
+depends  libxerces-c ^3.2.4
+```
+
+Or the following fragment if using Expat:
+
+```
+depends: * xsd ^4.2.0
+depends: libxsd ^4.2.0
+depends  libexpat ^2.5.0
+```
+
+Then your `buildfile` would have something along these lines if using
+Xerces-C++:
+
+```
+import! [metadata] xsd = xsd%exe{xsd}
+
+import libs  = libxsd%lib{xsd}
+import libs += libxerces-c%lib{xerces-c}
+```
+
+Or along these lines if using Expat:
+
+```
+import! [metadata] xsd = xsd%exe{xsd}
+
+import libs  = libxsd%lib{xsd}
+import libs += libexpat%lib{expat}
+```
+
+Note that the `xsd` executable provides `build2` metadata.
+
+The compilation of XML Schema to C++ can be implemented using ad hoc recipes
+or rules. See the `xsd-examples` package for the complete examples.
diff --git a/libxsd/INSTALL b/libxsd/INSTALL
deleted file mode 100644
index 181de1b..0000000
--- a/libxsd/INSTALL
+++ /dev/null
@@ -1,6 +0,0 @@
-The easiest way to build this package is with the bpkg package manager:
-
-$ bpkg build libxsd
-
-But if you don't want to use the package manager, then you can also build it
-manually using the standard build2 build system.
diff --git a/libxsd/PACKAGE-README.md b/libxsd/PACKAGE-README.md
new file mode 120000
index 0000000..422e63f
--- /dev/null
+++ b/libxsd/PACKAGE-README.md
@@ -0,0 +1 @@
+../PACKAGE-README.md
\ No newline at end of file
diff --git a/libxsd/buildfile b/libxsd/buildfile
index abb2c7c..adba28a 100644
--- a/libxsd/buildfile
+++ b/libxsd/buildfile
@@ -1,8 +1,7 @@
 # file      : buildfile
 # license   : GNU GPL v2 + exceptions; see accompanying LICENSE file
 
-./: {*/ -build/} doc{INSTALL NEWS README} legal{GPLv2 LICENSE FLOSSE} manifest
-
-# Don't the INSTALL file.
-#
-doc{INSTALL}@./: install = false
+./: {*/ -build/} \
+    doc{README PACKAGE-README.md NEWS} \
+    legal{GPLv2 LICENSE FLOSSE} \
+    manifest
diff --git a/libxsd/manifest b/libxsd/manifest
index f4abc04..4b5398a 100644
--- a/libxsd/manifest
+++ b/libxsd/manifest
@@ -8,6 +8,7 @@ summary: XML Schema to C++ data binding compiler runtime library
 license: other: GPL-2.0-only with Xerces-C++ linking exception and FLOSS exception
 topics: C++, XML, XML Schema, XML parser
 description-file: README
+package-description-file: PACKAGE-README.md
 changes-file: NEWS
 url: https://www.codesynthesis.com/projects/xsd/
 doc-url: https://www.codesynthesis.com/projects/xsd/
diff --git a/xsd/INSTALL b/xsd/INSTALL
deleted file mode 100644
index 3402df2..0000000
--- a/xsd/INSTALL
+++ /dev/null
@@ -1,6 +0,0 @@
-The easiest way to build this package is with the bpkg package manager:
-
-$ bpkg build xsd
-
-But if you don't want to use the package manager, then you can also build it
-manually using the standard build2 build system.
diff --git a/xsd/PACKAGE-README.md b/xsd/PACKAGE-README.md
new file mode 120000
index 0000000..422e63f
--- /dev/null
+++ b/xsd/PACKAGE-README.md
@@ -0,0 +1 @@
+../PACKAGE-README.md
\ No newline at end of file
diff --git a/xsd/buildfile b/xsd/buildfile
index 552635c..2550da0 100644
--- a/xsd/buildfile
+++ b/xsd/buildfile
@@ -1,9 +1,11 @@
 # file      : buildfile
 # license   : GNU GPL v2 + exceptions; see accompanying LICENSE file
 
-./: {*/ -build/} doc{INSTALL NEWS README} legal{GPLv2 LICENSE FLOSSE} manifest
+./: {*/ -build/} \
+    doc{README PACKAGE-README.md NEWS} \
+    legal{GPLv2 LICENSE FLOSSE} \
+    manifest
 
-# Don't install tests or the INSTALL file.
+# Don't install tests.
 #
-tests/:          install = false
-doc{INSTALL}@./: install = false
+tests/: install = false
diff --git a/xsd/manifest b/xsd/manifest
index 909c058..c7a1a76 100644
--- a/xsd/manifest
+++ b/xsd/manifest
@@ -6,6 +6,7 @@ summary: XML Schema to C++ data binding compiler
 license: other: GPL-2.0-only with Xerces-C++ linking exception and FLOSS exception
 topics: C++, XML, XML Schema, XML parser, source code generation
 description-file: README
+package-description-file: PACKAGE-README.md
 changes-file: NEWS
 url: https://www.codesynthesis.com/projects/xsd/
 doc-url: https://www.codesynthesis.com/projects/xsd/