Replace package README with README.md, rewrite content

20 files changed, 53 insertions, 89 deletions

diff --git a/libxsd-tests/README b/libxsd-tests/README
deleted file mode 100644
index 1ab33da..0000000
--- a/libxsd-tests/README
+++ /dev/null
@@ -1,8 +0,0 @@
-This package contains tests for the XSD to C++ data binding runtime library.
-
-See the LICENSE file for distribution conditions.
-
-The project page is at https://www.codesynthesis.com/projects/xsd/.
-
-Send bug reports or any other feedback to the xsd-users@codesynthesis.com
-mailing list.
diff --git a/libxsd-tests/README.md b/libxsd-tests/README.md
new file mode 100644
index 0000000..9e275a3
--- /dev/null
+++ b/libxsd-tests/README.md
@@ -0,0 +1,4 @@
+# libxsd-tests - tests for XSD runtime library
+
+This package contains tests for `libxsd`, the XML Schema to C++ data binding
+compiler's runtime library.
diff --git a/libxsd-tests/buildfile b/libxsd-tests/buildfile
index e783791..7259a1f 100644
--- a/libxsd-tests/buildfile
+++ b/libxsd-tests/buildfile
@@ -1,4 +1,4 @@
 # file      : buildfile
 # license   : GNU GPL v2 + exceptions; see accompanying LICENSE file
 
-./: {*/ -build/} doc{README} legal{GPLv2 LICENSE FLOSSE} manifest
+./: {*/ -build/} doc{README.md} legal{GPLv2 LICENSE FLOSSE} manifest
diff --git a/libxsd-tests/manifest b/libxsd-tests/manifest
index af755b8..c2e17a5 100644
--- a/libxsd-tests/manifest
+++ b/libxsd-tests/manifest
@@ -6,7 +6,7 @@ type: tests
 language: c++
 summary: XML Schema to C++ data binding compiler runtime library tests
 license: other: GPL-2.0-only with Xerces-C++ linking exception and FLOSS exception
-description-file: README
+description-file: README.md
 url: https://www.codesynthesis.com/projects/xsd/
 doc-url: https://www.codesynthesis.com/projects/xsd/
 src-url: https://git.codesynthesis.com/cgit/xsd/xsd/tree/libxsd-tests/
diff --git a/libxsd/README b/libxsd/README
deleted file mode 100644
index 00f8e1d..0000000
--- a/libxsd/README
+++ /dev/null
@@ -1,13 +0,0 @@
-libxsd is a runtime library for language mappings generated by CodeSynthesis
-XSD, a W3C XML Schema to C++ data binding compiler.
-
-See the LICENSE file for distribution conditions.
-
-See the INSTALL file for prerequisites and installation instructions.
-
-See the doc/ directory for documentation.
-
-The project page is at https://www.codesynthesis.com/projects/xsd/
-
-Send bug reports or any other feedback to the xsd-users@codesynthesis.com
-mailing list.
diff --git a/libxsd/README.md b/libxsd/README.md
new file mode 100644
index 0000000..c0afe68
--- /dev/null
+++ b/libxsd/README.md
@@ -0,0 +1,12 @@
+# libxsd - runtime library for XML Schema to C++ data binding compiler
+
+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, including licensing conditions, documentation, and
+binary packages, refer to the [XSD project
+page](https://codesynthesis.com/products/xsd/).
diff --git a/libxsd/buildfile b/libxsd/buildfile
index adba28a..90a32e1 100644
--- a/libxsd/buildfile
+++ b/libxsd/buildfile
@@ -2,6 +2,6 @@
 # license   : GNU GPL v2 + exceptions; see accompanying LICENSE file
 
 ./: {*/ -build/} \
-    doc{README PACKAGE-README.md NEWS} \
+    doc{README.md PACKAGE-README.md NEWS} \
     legal{GPLv2 LICENSE FLOSSE} \
     manifest
diff --git a/libxsd/manifest b/libxsd/manifest
index 4b5398a..5a50288 100644
--- a/libxsd/manifest
+++ b/libxsd/manifest
@@ -7,7 +7,7 @@ language: c++
 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
+description-file: README.md
 package-description-file: PACKAGE-README.md
 changes-file: NEWS
 url: https://www.codesynthesis.com/projects/xsd/
diff --git a/xsd-examples/README b/xsd-examples/README
deleted file mode 100644
index 023334d..0000000
--- a/xsd-examples/README
+++ /dev/null
@@ -1,21 +0,0 @@
-This package contains a number of examples that show how to use XSD, the
-XML Schema to C++ data binding compiler and the generated C++ Tree and
-Parser classes. See the README files in example directories for more
-information on each example.
-
-The package source code is in the public domain.
-
-The project page is at https://www.codesynthesis.com/projects/xsd/.
-
-The easiest way to build this package is with the bpkg package manager:
-
-$ mkdir xsd-examples/
-$ cd xsd-examples/
-$ bpkg create cc
-$ bpkg build xsd-examples@https://pkg.cppget.org/1/stable
-
-But if you don't want to use the package manager, then you can also build it
-manually using the standard build2 build system.
-
-Send bug reports or any other feedback to the xsd-users@codesynthesis.com
-mailing list.
diff --git a/xsd-examples/README.md b/xsd-examples/README.md
new file mode 100644
index 0000000..e55a3ee
--- /dev/null
+++ b/xsd-examples/README.md
@@ -0,0 +1,11 @@
+# xsd-examples - examples for XSD compiler
+
+This package contains examples for `xsd`, the XML Schema to C++ data binding
+compiler.
+
+The C++/Tree and C++/Parser mapping examples can be found in the `cxx/tree/`
+and `cxx/parser/` subdirectories, respectively. For the summary of available
+examples for each mapping, see `cxx/tree/README` and `cxx/parser/README`,
+respectively. Each example also comes with its own `README` file that provides
+a detailed description of the functionality shown as well as the steps to
+build and run it.
diff --git a/xsd-examples/buildfile b/xsd-examples/buildfile
index 3f8fb1b..f9b2d06 100644
--- a/xsd-examples/buildfile
+++ b/xsd-examples/buildfile
@@ -1,4 +1,4 @@
 # file      : buildfile
 # license   : not copyrighted - public domain
 
-./: {*/ -build/} doc{README} legal{UNLICENSE} manifest
+./: {*/ -build/} doc{README.md} legal{UNLICENSE} manifest
diff --git a/xsd-examples/manifest b/xsd-examples/manifest
index 7e02b59..c3528e8 100644
--- a/xsd-examples/manifest
+++ b/xsd-examples/manifest
@@ -6,7 +6,7 @@ type: examples
 language: c++
 summary: XML Schema to C++ data binding compiler examples
 license: Unlicence
-description-file: README
+description-file: README.md
 url: https://www.codesynthesis.com/projects/xsd/
 doc-url: https://www.codesynthesis.com/projects/xsd/
 src-url: https://git.codesynthesis.com/cgit/xsd/xsd/tree/xsd-examples/
diff --git a/xsd-tests/README b/xsd-tests/README
deleted file mode 100644
index 1b529ab..0000000
--- a/xsd-tests/README
+++ /dev/null
@@ -1,8 +0,0 @@
-This package contains tests for the XSD to C++ data binding compiler.
-
-See the LICENSE file for distribution conditions.
-
-The project page is at https://www.codesynthesis.com/projects/xsd/.
-
-Send bug reports or any other feedback to the xsd-users@codesynthesis.com
-mailing list.
diff --git a/xsd-tests/README.md b/xsd-tests/README.md
new file mode 100644
index 0000000..409c447
--- /dev/null
+++ b/xsd-tests/README.md
@@ -0,0 +1,4 @@
+# xsd-tests - tests for XSD compiler
+
+This package contains tests for `xsd`, the XML Schema to C++ data binding
+compiler.
diff --git a/xsd-tests/buildfile b/xsd-tests/buildfile
index e783791..7259a1f 100644
--- a/xsd-tests/buildfile
+++ b/xsd-tests/buildfile
@@ -1,4 +1,4 @@
 # file      : buildfile
 # license   : GNU GPL v2 + exceptions; see accompanying LICENSE file
 
-./: {*/ -build/} doc{README} legal{GPLv2 LICENSE FLOSSE} manifest
+./: {*/ -build/} doc{README.md} legal{GPLv2 LICENSE FLOSSE} manifest
diff --git a/xsd-tests/manifest b/xsd-tests/manifest
index 7b6bc6f..fefc84c 100644
--- a/xsd-tests/manifest
+++ b/xsd-tests/manifest
@@ -6,7 +6,7 @@ type: tests
 language: c++
 summary: XML Schema to C++ data binding compiler tests
 license: other: GPL-2.0-only with Xerces-C++ linking exception and FLOSS exception
-description-file: README
+description-file: README.md
 url: https://www.codesynthesis.com/projects/xsd/
 doc-url: https://www.codesynthesis.com/projects/xsd/
 src-url: https://git.codesynthesis.com/cgit/xsd/xsd/tree/xsd-tests/
diff --git a/xsd/README b/xsd/README
deleted file mode 100644
index dc1d4db..0000000
--- a/xsd/README
+++ /dev/null
@@ -1,29 +0,0 @@
-CodeSynthesis XSD is a W3C XML Schema to C++ data binding compiler.
-It generates vocabulary-specific, statically-typed C++ mappings (also
-called bindings) from XML Schema definitions. XSD supports two C++
-mappings: in-memory C++/Tree and event-driven C++/Parser.
-
-The C++/Tree mapping consists of types that represent the given
-vocabulary, a set of parsing functions that convert XML instance
-documents to a tree-like in-memory object model, and a set of
-serialization functions that convert the object model back to XML.
-
-The C++/Parser mapping provides parser templates for data types
-defined in XML Schema. Using these parser templates you can build
-your own in-memory representations or perform immediate processing
-of XML instance documents.
-
-Note also that the xsd executable provides build2 metadata.
-
-See the NEWS file for the user-visible changes from the previous release.
-
-See the LICENSE file for distribution conditions.
-
-See the INSTALL file for prerequisites and installation instructions.
-
-See the doc/ directory for documentation.
-
-The project page is at https://www.codesynthesis.com/projects/xsd/.
-
-Send bug reports or any other feedback to the xsd-users@codesynthesis.com
-mailing list.
diff --git a/xsd/README.md b/xsd/README.md
new file mode 100644
index 0000000..e2b2887
--- /dev/null
+++ b/xsd/README.md
@@ -0,0 +1,12 @@
+# xsd - XML Schema to C++ data binding compiler
+
+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, including licensing conditions, documentation, and
+binary packages, refer to the [XSD project
+page](https://codesynthesis.com/products/xsd/).
diff --git a/xsd/buildfile b/xsd/buildfile
index 2550da0..b0121dd 100644
--- a/xsd/buildfile
+++ b/xsd/buildfile
@@ -2,7 +2,7 @@
 # license   : GNU GPL v2 + exceptions; see accompanying LICENSE file
 
 ./: {*/ -build/} \
-    doc{README PACKAGE-README.md NEWS} \
+    doc{README.md PACKAGE-README.md NEWS} \
     legal{GPLv2 LICENSE FLOSSE} \
     manifest
 
diff --git a/xsd/manifest b/xsd/manifest
index c7a1a76..34259ab 100644
--- a/xsd/manifest
+++ b/xsd/manifest
@@ -5,7 +5,7 @@ language: c++
 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
+description-file: README.md
 package-description-file: PACKAGE-README.md
 changes-file: NEWS
 url: https://www.codesynthesis.com/projects/xsd/