Merge pull request #2 from OP-TED/feature/TEDXDC-95-final-changes-for…

…-first-release

Feature/tedxdc 95 final changes for first release

CHANGELOG.md

@@ -1,3 +1,23 @@
-# TED XML Data Converter 0.1
+# TED XML Data Converter 0.2.0 Release Notes
+Below is a list of the major updates made to the Converter repository in this release. There was no substantial change to the XSLT code.
+
+## Folder names changed
+The four root folders were renamed to more clearly reflect their contents and purposes.
+
+## Removal of unnecessary files
+A number of files that were used during initial development, but are now no longer required, were removed.
+
+## File names changed
+The names of the Markdown files were changed to "kebab-case", to improve readability.
+
+## Markdown documentation
+The documentation in the various Markdown files was re-written to improve understanding of the different topics.
+A README.md file was added to every main folder to describe the contents of the folder.
+
+## Converted development test files
+The test notices in folder development-notices/ted-xml were all converted using this version of the converter, updating the output files in folder development-notices/eforms-files.
+
+## XSLT template location
+Some XSLT templates used in more than one location were moved into a new XSLT file, common.xslt. 
+
 
-This is the first release of the TED XML Data Converter. In future releases, this file will list the changes made between each release.

README.md

@@ -1,67 +1,52 @@
 
 # Disclaimer
-This project is currently under development. We may update the current version and replace it with a new version at any time. In this case, we recommend you retrieve the latest version in order to ensure technical compliance. The Publications Office cannot guarantee the accuracy, adequacy, validity, reliability, availability or completeness of this information and accepts no responsibility for any use you may make of this project’s component parts.
+This project is currently under development. We may update the current version and replace it with a new version at any time. For this reason, we recommend you retrieve the latest version in order to ensure technical compliance. The Publications Office of the European Union cannot guarantee the accuracy, adequacy, validity, reliability, availability or completeness of this information and accepts no responsibility for any use you may make of this project’s component parts.
 
 The code and data in this repository is created by the Publications Office of the European Union and is licensed under the terms of the [EUPL-1.2 license](LICENSE).
 
-# Purpose
+# Summary
 
-The purpose of the TED XML Data Converter is to assist eSenders in the migration to eForms. 
+This project is managed by the Publications Office of the European Union to assist organisations publishing procurement notices in their migration from TED XML to eForms. 
 
-An eSender may wish to switch the production of notices in their system from the TED schemas to the eForms schema on a single date. In this case, they will have published some initial notices (PIN, Contract Notice, etc.) for an ongoing Procedure using the TED schemas. They will want to publish following notices, continuing the Procedure, using the eForms schema. 
+An organisation publishing procurement notices may wish to switch the production of notices in their system from the TED schemas to the eForms schema at a point in time. In this case, they will have published some initial notices (PIN, Contract Notice, etc.) for an ongoing Procedure using the TED schemas. They will want to publish following notices, continuing the Procedure, using the eForms schema. 
 
-The TED XML Data Converter is designed to help with this process, by converting a notice published in the TED schemas, to a draft form of the same notice in eForms. The eSender can then correct and complete this notice, and use it as a basis for creating a following notice in eForms.
+The TED XML Data Converter is designed to help with this process, by converting a notice published in the TED schemas, to a draft form of the same notice in eForms. The publisher can then correct and complete this notice, and use it as a basis for creating a following notice in eForms.
 
-# How to use
-
-The code for the TED XML Data Converter is contained in this repository. Basic usage instructions for developers to run the code in their own system is available [here](Usage-Information.md).
-An API will be developed for the converter. A user will specify the TED notice number, and the API will retrieve the published TED notice XML, convert it to eForms XML and return it to the user.
-
-# About the converter
-
-## XML output will be incomplete and invalid.
-
-The XML output from the TED XML Data Converter will not be complete, and will also contain some errors. It will not pass all the eForms Schematron checks. This is because:
+The repository contains the following folders:
 
-* Some information required by eForms is not used in the TED schemas (for example: Internal ID (BT-22) has no equivalent in the TED schema )
-* Some information present in the TED XML is in a different format from that required by eForms (for example: a textual description in TED XML, a specific code from a codelist in eForms XML)
+| Folder | Purpose |
+| --- | --- |
+| `xslt` | The xslt and data for the conversion |
+| `development-notices` | Sample source TED XML files used for testing during development and their equivalent converted eForms XML files |
+| `eforms-structure-files` | Sample files for the structure of eForms XML |
+| `test-notices` | Sample notices in TED schema XML to be used for testing the converter |
 
-The TED XML Data Converter will report these issues as comments and application-level warnings.
+The repository contains the following documentation files in Markdown format:
 
+| File | Purpose |
+| --- | --- |
+| [README.md](README.md) | This file |
+| [usage-information.md](usage-information.md) | General information on usage of this repository |
+| [installation.md](installation.md) | Basic instructions on installation in a Unix environment |
+| [development-methodology.md](development-methodology.md) | The technical approach to developing this conversion |
+| [CHANGELOG.md](CHANGELOG.md) | The list of changes made since the last release |
 
-## Limited Scope
+Each folder also contains a README.md file listing the files in that folder and their purpose.
 
-The current version of the TED XML Data Converter will only convert a limited subset of published TED notices:
 
-* TED Schema: only TED schema R.2.0.9 is supported. Notices published under Directive 23 cannot be converted with this version of the Converter.
-* TED Schema version: only the latest version of the TED schema R.2.0.9 (S05) is supported. Notices published under earlier versions of the schema may be converted, but may contain more errors.
-* Document Types: only Contract Notices are currently supported:
-    * All elements in TED XML form F02 are supported
-    * Most elements in TED XML forms F05, F12 and the Contract Notice variants of forms F21, F22, F23 and F24 are supported
-* Languages: currently the converter only converts the main (original) language of each notice. Other languages which may be present in the TED XML are not included.
-
-## HTML Comments in output eForms XML
-
-Each leaf element in the output eForms XML will be preceded by an HTML comment naming the Business Term it is associated with.
-Where an XML element or Business Term is mandatory for an eForms notice, and the source TED XML does not contain the required information:
+# How to use
 
-* The eForms XML element associated with the mandatory Business Term will be included in the output.
-* An HTML comment will precede the XML element stating that required information was not found in the source TED XML.
-* In some cases, such as dates, valid values will be added to make the XML schema-valid.
+Basic usage instructions for developers to run the code in their own system is available [here](usage-information.md).
 
 
 ## Versioning scheme
 
 The versioning scheme which will be adopted for the TED XML Data Converter will be similar to that for the [eForms SDK](https://docs.ted.europa.eu/eforms/latest/versioning.html).
 
-## Developer information
-
-Information about the code and associated files, and brief information on how to use them, can be found [here](Usage-Information.md).
-
 
 ## Feedback
 
-Feedback on this converter is welcome. Please address questions, comments and bug reports using the [Contact details on SIMAP](https://simap.ted.europa.eu/contact). Please ensure you include "TEDXDC Converter" in the Subject line.
+Feedback on this converter is welcome. Please address questions, comments and bug reports using [Github Discussions](https://github.com/OP-TED/ted-xml-data-converter/discussions).
 
 ## What's next?
 Work on conversion of the remaining Contract Notice TED XML forms (F05, F12, F21, F22, F23 and F24) is ongoing.