Merge pull request #770 from package-url/Update-documentation-to-match-ECMA-427

Update docs/standard documentation to match ECMA-427 PDF.
Added docs/README-docs.md to document the process for matching our markdown file content to the PDF with some formatting differences.
Merging without other approvals after thorough review by @johnmhoran.

Author: mjherzog

PURL-SPECIFICATION.rst

@@ -1,5 +1,4 @@
 The contents of this file: purl-spec/PURL-SPECIFICATION.rst have been moved
-to markdown files in `purl-spec/docs/ <docs/>`__. See the file: `purl-specification.md <purl-specification.md>`__ at
-the root of this repository for the most current version of content equivalent
-to PURL-SPECIFICATION.rst as generated from the current documentation files in
-purl-spec/docs/ .
+to markdown files in `purl-spec/docs/ <docs/>`__. See also the Package-URL
+Specification 1st Edition standard at: 
+https://ecma-international.org/publications-and-standards/standards/ecma-427/.

docs/README-docs.md

@@ -0,0 +1,49 @@
+This README explains the organization of documentation files for the PURL 
+specification.
+
+## ECMA-427 documentation
+The `purl-spec/docs/standard` folder has markdown files with text that match 
+the content of [ECMA-427](https://ecma-international.org/publications-and-standards/standards/ecma-427/) 
+which is the first edition of the Package-URL Specification standard. These 
+files map to ECMA-427 document as follows:
+
+- Introduction: `introduction.md`
+- About this specification: `about.md`
+- Clause 1 Scope: `scope.md`
+- Clause 2 Conformance: `conformance.md`
+- Clause 3 Normative references: `references.md`
+- Clause 4 Overview: `overview.md`
+- Clause 5 Package-URL specification: `specification.md`
+- Clause 6 Package-URL Type Definition Schema: `type-definition-schema.md`
+
+ECMA-427 is the official documention for the 1st edition of the Package-URL 
+(PURL) Specification standard. The source for this documentation is located 
+at: https://github.com/Ecma-TC54/ECMA-427/blob/main/spec.html. The text from 
+this HTML file is processed with several Ecma tools to produce a PDF file that
+ is available from: https://tc54.org/purl/. We validated the text in the files
+in the `purl-spec/docs/standard` folder against the PDF.
+
+The text stored in
+purl-spec/docs/standard/` matches the official text with following exceptions:
+- The text does not include the clause numbering from ECMA-427. This 
+numbering is automatically added by the Ecma tools for publishing an Ecma
+standard.
+- `docs/standard/type-definition-schema.md` only has the introductory text
+from ECMA-427 Clause 6 because Clause 6 presents the PURL Type Definition 
+Schema in a "human-friendly" format that is difficult to reproduce in
+markdown. The equivalent information is in this repository in JSON Schema 
+format: at `purl-spec/schemas/purl-type-definition.schema-1.0.json`
+- There are some minor formatting differences such as the examples in Clause 5 
+and the use of italics instead of intra-document links.
+
+The purpose of keeping a copy of the ECMA-427 text here is to make it easier
+to track any proposed changes to the PURL specification that will affect
+the ECMA-427 Standard. Any such changes need to be tracked and approved for
+a future 2nd edition of the ECMA-427 Standard.
+
+## PURL specification documentation
+The other files in the `purl-spec/docs` folder are also specification 
+documentation, but they are not part of the ECMA-427 1st edition Standard. 
+Most of the documents provide information to support implementation of the 
+PURL Specification in other software or databases.
+

docs/purl-spec-toc.md

@@ -1,22 +1,22 @@
 # About this Specification
 
-The document at [https://tc54.org/ecmaXXX/](https://tc54.org/ecmaXXX/) is the
+The document at [https://tc54.org/ecm427/](https://tc54.org/ecma427/) is the
 most accurate and up-to-date Package-URL specification.
 
-This document is available as [a single page](https://ecma-tc54.github.io/ECMA-xxx-PURL/)
-and as [multiple pages](https://ecma-tc54.github.io/ECMA-xxx-PURL/multipage/).
+This document is available as [a single page](https://ecma-tc54.github.io/ECMA-427/)
+and as [multiple pages](https://ecma-tc54.github.io/ECMA-427/multipage/).
 
 # Contributing to this Specification
 
 This specification is developed on GitHub with the help of the Package-URL
 community. There are a number of ways to contribute to the development of
 this specification:
 
-* GitHub Repository: [https://github.com/Ecma-TC54/ECMA-xxx-PURL](https://github.com/Ecma-TC54/ECMA-xxx-PURL)
-* Issues: [All Issues](https://github.com/Ecma-TC54/ECMA-xxx-PURL/issues),
-  [File a New Issue](https://github.com/Ecma-TC54/ECMA-xxx-PURL/issues/new)
-* Pull Requests: [All Pull Requests](https://github.com/Ecma-TC54/ECMA-xxx-PURL/pulls),
-  [Create a New Pull Request](https://github.com/Ecma-TC54/ECMA-xxx-PURL/pulls/new)
+* GitHub Repository: [https://github.com/Ecma-TC54/ECMA-xxx-PURL](https://github.com/Ecma-TC54/ECMA-427)
+* Issues: [All Issues](https://github.com/Ecma-TC54/ECMA-427/issues),
+  [File a New Issue](https://github.com/Ecma-TC54/ECMA-427/issues/new)
+* Pull Requests: [All Pull Requests](https://github.com/Ecma-TC54/ECMA-427/pulls),
+  [Create a New Pull Request](https://github.com/Ecma-TC54/ECMA-427/pulls/new)
 * Editors:
   * [John Horan](mailto:jmhoran@aboutcode.org)
   * [Michael Herzog](mailto:mjherzog@aboutcode.org)
@@ -25,5 +25,5 @@ this specification:
 * Community:
   * Chat: [Slack Channel](https://cyclonedx.slack.com/archives/C06KTE3BWEB)
 
-Refer to the [colophon](https://ecma-tc54.github.io/ECMA-xxx-PURL/#sec-colophon)
+Refer to the [colophon](https://ecma-tc54.github.io/ECMA-427/#sec-colophon)
 for more information on how this document was created.

docs/standard/about.md

@@ -1,51 +1,29 @@
-# 2 Conformance
+# Conformance
 
-## 2.1 Requirements Terminology
-
-In this standard, the words that are used to define the significance of each
-requirement are detailed below. These words are used in accordance with their
-definitions in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt), and their
-respective meanings are reproduced below:
-
-* Must: This word, or the adjective “required” and the auxiliary verb
-  "shall", means that the item is an absolute requirement of the standard.
-* Should: This word, or the adjective “recommended”, means that there might
-  exist valid reasons in particular circumstances to ignore this item, but
-  the full implications should be understood and the case carefully weighed
-  before making an implementation decision.
-* May: This word, or the adjective “optional”, means that this item is truly
-  optional.
-
-The words "must not", "shall not", "should not", and "not recommended", are
-the negative forms of "must", "shall", "should", and "recommended",
-respectively. There is no negative form of "may".
-
-## 2.2 Implementation Conformance
-
-A conforming implementation of Package-URL (PURL) must fully implement and
-support all elements defined within this specification, including the syntax,
+A conforming implementation of Package-URL (PURL) shall fully implement and
+support all elements defined within this Standard, including the syntax,
 components, and semantic requirements for constructing and interpreting valid
 PURLs.
 
-A conforming implementation of PURL must adhere to the syntax defined in this
-specification, ensuring that all PURLs are parsed, constructed, and validated
-according to the prescribed rules. The implementation must provide full
+A conforming implementation of PURL shall adhere to the syntax defined in this
+Standard, ensuring that all PURLs are parsed, constructed, and validated
+according to the prescribed rules. The implementation shall provide full
 support for ecosystem-agnostic behaviour, enabling PURLs to function
 consistently and reliably across diverse environments.
 
-All required components of a PURL, such as the scheme, type, and name, must
+All required components of a PURL, such as the scheme, type, and name, shall
 be present and validated according to the rules defined in this
-specification. Additionally, optional components, including qualifiers and
-subpaths, must be handled appropriately if provided, in full compliance with
+Standard. Additionally, optional components, including qualifiers and
+subpaths, shall be handled appropriately if provided, in full compliance with
 their specified behaviours.
 
-Implementations must ensure that equivalent PURLs are consistently resolved
+Implementations shall ensure that equivalent PURLs are consistently resolved
 to the same canonical representation. This includes strict adherence to
-normalisation and equivalence rules. Furthermore, implementations must
+normalisation and equivalence rules. Furthermore, implementations shall
 process URI encoding and decoding for PURL components according to the
 standards outlined in RFC 3986.
 
-Invalid PURLs that fail to conform to the specification must be identified
+Invalid PURLs that fail to conform to the specification shall be identified
 and rejected by any conforming implementation. This guarantees the integrity
 and reliability of PURLs in all supported contexts.
 
@@ -56,19 +34,8 @@ implementations may offer auxiliary tools or features, such as utilities for
 constructing or validating PURLs, provided they align with the standard's
 requirements.
 
-A conforming implementation must not redefine or alter the core syntax,
-components, or semantics defined by this specification. Any prohibited
-extensions explicitly identified in the specification must not be
+A conforming implementation shall not redefine or alter the core syntax,
+components, or semantics defined by this Standard. Any prohibited
+extensions explicitly identified in the specification shall not be
 implemented. Furthermore, behaviours that compromise the interoperability of
-PURLs across tools, platforms, or ecosystems are strictly disallowed.
-
-A conforming implementation of Package-URL may choose to implement or not
-implement Normative Optional subclauses. If any Normative Optional behaviour
-is implemented, all of the behaviour in the containing Normative Optional
-clause must be implemented. A Normative Optional clause is denoted in this
-specification with the words "Normative Optional" in a coloured box, as shown
-below.
-
-## 2.3 Example Normative Optional Clause Heading
-
-Example clause contents.
+PURLs across tools, platforms, or ecosystems are strictly disallowed.