Corrections to text

Fixed errors such as changing "specification" to "Standard" to match the ECMA-427 PDF text. Documented some formatting differences in README-docs.md.

Author: mjherzog

docs/README-docs.md

@@ -2,21 +2,28 @@ 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:
+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:
 
-- About this specification: `about.md`
 - Introduction: `introduction.md`
+- About this specification: `about.md`
 - Clause 1 Scope: `scope.md`
 - Clause 2 Conformance: `conformance.md`
-- Clause 3 Normative references: `refererences.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 PURL
-Specification standard. The source for this documentation is located at:
-https://github.com/Ecma-TC54/ECMA-427/blob/main/spec.html. The text stored in
+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
@@ -26,15 +33,17 @@ 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.
+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 `purl-spec/docs` 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.
+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/standard/conformance.md

@@ -1,29 +1,29 @@
 # 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.
 
@@ -34,8 +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.

docs/standard/overview.md

@@ -19,8 +19,10 @@ meet the needs of diverse package ecosystems without compromising its
 universal applicability.
 
 The primary audience for this Standard includes developers, tool implementers,
-and organisations involved in software composition analysis, dependency management, and supply chain security. PURL is foundational to a variety of 
-use cases, from software bill of materials (SBOM) generation and license compliance to vulnerability tracking and software artefact exchange.
+and organisations involved in software composition analysis, dependency 
+management, and supply chain security. PURL is foundational to a variety of 
+use cases, from software bill of materials (SBOM) generation and license 
+compliance to vulnerability tracking and software artefact exchange.
 
 While this document serves as the authoritative reference for implementing
 PURL, it is complemented by various ecosystem-specific guidance documents,
@@ -29,4 +31,4 @@ and practical insights for leveraging PURL effectively.
 
 This overview is non-normative and serves to provide context for the
 specification’s intent, purpose, and audience. For detailed requirements and
-conformance criteria, refer to the normative sections of this Standard.
+conformance criteria, refer to the normative clauses of this Standard.

docs/standard/specification.md

@@ -8,11 +8,11 @@ A PURL is a URL composed of seven components:
 
 Components are separated by a specific character for unambiguous parsing.
 
-Table 1: Components of a PURL
+Table 1 —  Components of a PURL
 
 | Component  | Requirement | Description|
 | ---------- | ----------- |:------------------------------------------------------ |
-| scheme     | Required    | The URL scheme with the constant value of "pkg". One of the primary reasons for this single scheme is to facilitate the future official registration of the "pkg" scheme for package URLs. |
+| scheme     | Required    | The URL scheme with the constant value of "pkg". One of the primary reasons for this single scheme is to facilitate the future official registration of the "pkg" scheme for Package-URLs. |
 | type       | Required    | The package "type" or package "protocol" such as maven, npm, nuget, gem, pypi, etc. |
 | namespace  | Optional    | A name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization. Namespace is type-specific. |
 | name       | Required    | The name of the package. |
@@ -84,11 +84,11 @@ as defined in Python pip or SPDX download locations are not valid PURL types.
 A canonical PURL is composed of these permitted ASCII characters:
 
 - the Alphanumeric Characters: **A to Z**, **a to z**, **0 to 9**,
-- the Punctuation Characters: **.-_~** (period '.',
-  dash '-', underscore '_' and tilde '~'),
-- the Percent Character: **%** (percent sign '%'), and
+- the Punctuation Characters: **.-_~** (period '.'
+  dash '-', underscore '_' and tilde '~')
+- the Percent Character: **%** (percent sign '%')
 - the Separator Characters **:/@?=&#** (colon ':', slash '/', at sign '@',
-  question mark '?', equal sign '=', ampersand '&' and hash sign '#').
+  question mark '?', equal sign '=', ampersand '&' and hash sign '#')
 
 
 ## Separator characters
@@ -132,11 +132,11 @@ This is how each of the Separator Characters is used:
 
 - Where the space ' ' is permitted, it shall be percent-encoded as '%20'.
 - With the exception of the percent-encoding mechanism, the rules regarding
-  percent-encoding are defined by this specification alone.
+  percent-encoding are defined by this Standard alone.
 
 ## Case folding
 
-References to "lowercase" in this specification refer to the 
+References to "lowercase" in this Standard refer to the 
 **culture-invariant** full case mapping defined in
 [Section 3.13.2 of the Unicode Standard](https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-3/#G34078).
 
@@ -149,13 +149,13 @@ All other ASCII characters remain unchanged.
 
 A PURL string is an ASCII URL string composed of seven components.
 
-Except as expressly stated otherwise in this section, each component:
+Except as expressly stated otherwise in this Clause, each component:
 
-- may be composed of any of the characters defined in the "Permitted
-  characters" section
-- shall be encoded as defined in the "Character encoding" section
+- may be composed of any of the characters defined in the _Permitted
+  characters_ clause
+- shall be encoded as defined in the _Character encoding_ clause
 
-The "lowercase" rules are defined in the "Case folding" clause.
+The "lowercase" rules are defined in the Case folding clause.
 
 The rules for each component are:
 
@@ -185,7 +185,7 @@ stripped in the canonical form. They are not part of the **namespace**.
     - shall not contain any slash '/' characters
     - shall not be empty
     - may contain any Unicode character other than '/' unless the package's
-**type** definition provides otherwise.
+**type** definition provides otherwise
 - A URL host or Authority shall not be used as a **namespace**. Use instead a
 **repository_url** qualifier. Note however, that for some types, the
 **namespace** may look like a host.
@@ -222,7 +222,7 @@ This '&' separator is not part of an individual **qualifier**.
     - A **key** shall not be percent-encoded.
     - Each **key** shall be unique among all the keys of the **qualifiers**    component.
     - A **value** may contain any Unicode character and all characters shall 
-    be encoded as described in the "Character encoding" section.
+    be encoded as described in the _Character encoding_ clause.
 
 ### Subpath
 - The **subpath** string is prefixed by a '#' separator when not empty.
@@ -234,8 +234,8 @@ in the canonical form.
 - When percent-decoded, a segment:
     - shall not contain any slash '/' characters
     - shall not be empty
-    - Shall not be any of '..' or '.'
-    - May contain any Unicode character other than '/' unless the package's       **type** definition provides otherwise.
+    - shall not be any of '..' or '.'
+    - may contain any Unicode character other than '/' unless the package's       **type** definition provides otherwise.
 - The **subpath** shall be interpreted as relative to the root of the package.