Complete markdown conversion

pombredanne · pombredanne · commit 53e186000d73 · 2025-08-13T19:34:35.000+02:00
Signed-off-by: Philippe Ombredanne &lt;pombredanne@aboutcode.org&gt;
diff --git a/docs/how-to-build.md b/docs/how-to-build.md
@@ -1,5 +1,4 @@
-How to build `purl` string from its components
-==============================================
+## How to build a `purl` string from its components
 
 Building a `purl` ASCII string works from left to right, from `type` to
 `subpath`.
diff --git a/docs/how-to-parse.md b/docs/how-to-parse.md
@@ -1,5 +1,4 @@
-How to parse a `purl` string in its components
-==============================================
+## How to parse a `purl` string into its components
 
 Parsing a `purl` ASCII string into its components works from right to left,
 from `subpath` to `type`.
diff --git a/docs/known-qualifiers.md b/docs/known-qualifiers.md
@@ -1,5 +1,4 @@
-Known `qualifiers` key/value pairs
-==================================
+## Known `purl` `qualifiers` key/value pairs
 
 Note: Do not abuse `qualifiers`: it can be tempting to use many qualifier
 keys but their usage should be limited to the bare minimum for proper package
@@ -13,7 +12,7 @@ With this warning, the known `key` and `value` defined here are valid for use in
 all package types:
 
 - `vers` allows the specification of a version range.
-  The value MUST adhere to the [Version Range Specification](VERSION-RANGE-SPEC.rst).
+  The value MUST adhere to the `Version Range Specification`.
   This qualifier is mutually exclusive with the `version` component.
   For example:
 
@@ -41,6 +40,6 @@ all package types:
   comma-separated list. Each item in the `value` is in form of
   `lowercase_algorithm:hex_encoded_lowercase_value` such as
   `sha1:ad9503c3e994a4f611a4892f2e67ac82df727086`.
-  For example (with checksums truncated for brevity) :
+  For example (with checksums truncated for brevity):
 
     checksum=sha1:ad9503c3e994a4f,sha256:41bf9088b3a1e6c1ef1d
diff --git a/docs/purl-spec-toc.md b/docs/purl-spec-toc.md
@@ -1,5 +1,4 @@
-Package URL specification v1.0.X
-================================
+# Package-URL Specification
 
 The Package URL core specification defines a versioned and formalized format,
 syntax, and rules used to represent and validate `purl`.
@@ -11,5 +10,5 @@ A `purl` is a URL string used to identify and locate a software package in a
 mostly universal and uniform way across programming languages, package managers,
 packaging conventions, tools, APIs and databases.
 
-Such a package URL is useful to reliably reference the same software package
+A `purl` is useful to reliably reference the same software package
 using a simple and expressive syntax and conventions based on familiar URLs.
diff --git a/docs/standard/characters-and-encoding.md b/docs/standard/characters-and-encoding.md
@@ -1,5 +1,4 @@
-Permitted characters
-====================
+## Permitted characters
 
 A canonical `purl` is composed of these permitted ASCII characters:
 
@@ -11,8 +10,7 @@ A canonical `purl` is composed of these permitted ASCII characters:
   question mark '?', equal sign '=', ampersand '&' and pound sign '#').
 
 
-`purl` separators
-=================
+## Separators
 
 This is how each of the Separator Characters is used:
 
@@ -27,16 +25,15 @@ This is how each of the Separator Characters is used:
   `key=value` pair)
 - '#' (number sign) is the separator before `subpath`
 
-Character encoding
-==================
+## Character encoding
 
 - In the "Rules for each `purl` component" section, each component
   defines when and how to apply percent-encoding and decoding to its content.
 - When percent-encoding is required by a component definition, the component
   string MUST first be encoded as UTF-8.
 - In the component string, each "data octet" MUST be replaced by the
   percent-encoded "character triplet" applying the percent-encoding mechanism
-  defined in RFC 3986 section 2.1 (<https://datatracker.ietf.org/doc/html/rfc3986#section-2.1>),
+  defined in [RFC 3986 section 2.1](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1),
   including the RFC definition of "data octet" and "character triplet",
   and using these definitions for RFC's "allowed set" and "delimiters":
 
@@ -56,8 +53,7 @@ Character encoding
 - With the exception of the percent-encoding mechanism, the rules regarding
   percent-encoding are defined by this specification alone.
 
-Case folding
-============
+## Case folding
 
 References to "lowercase" in this specification refer to the **culture-invariant**
 full case mapping defined in
diff --git a/docs/standard/components.md b/docs/standard/components.md
@@ -1,14 +1,13 @@
-Rules for each `purl` component
-===============================
+## Rules for each `purl` component
 
 A `purl` string is an ASCII URL string composed of seven components.
 
 Except as expressly stated otherwise in this section, each component:
 
-- MAY be composed of any of the characters defined in the "[Permitted characters]()" section
-- MUST be encoded as defined in the "[Character encoding]()" section
+- MAY be composed of any of the characters defined in the "Permitted characters" section
+- MUST be encoded as defined in the "Character encoding" section
 
-The "lowercase" rules are defined in the "[Case folding]()" section.
+The "lowercase" rules are defined in the "Case folding" section.
 
 The rules for each component are:
 
diff --git a/docs/standard/references.md b/docs/standard/references.md
@@ -1,8 +1,12 @@
-Definitions
-===========
+# 3 Normative References
 
-ASCII See, e.g.,
+The following referenced documents are indispensable for the application of this document.
+For dated references, only the edition cited applies. For undated references, the latest
+edition of the referenced document (including any amendments) applies.
 
-- American National Standards Institute, "Coded Character Set -- 7-bit
-  American Standard Code for Information Interchange", ANSI X3.4, 1986.
-- <https://en.wikipedia.org/wiki/ASCII>.
+ASCII, *American National Standards Institute, "Coded Character Set -- 7-bit American
+Standard Code for Information Interchange", ANSI X3.4, 1986*
+https://en.wikipedia.org/wiki/ASCII
+
+RFC 3986, ​*Uniform Resource Identifier (URI): Generic Syntax*​.
+[https://datatracker.ietf.org/doc/html/rfc3986](https://datatracker.ietf.org/doc/html/rfc3986)
diff --git a/docs/standard/summary.md b/docs/standard/summary.md
@@ -1,3 +1,5 @@
+## What is a `purl`?
+
 `purl` stands for **package URL**.
 
 A `purl` is a URL composed of seven components:
@@ -32,8 +34,7 @@ A `purl` must NOT contain a URL Authority i.e. there is no support for
 sometimes look like a `host` but its interpretation is specific to a `type`.
 
 
-Some `purl` examples
-====================
+## Some `purl` examples
 
     pkg:bitbucket/birkenfeld/pygments-main@244fd47e07d1014f0aed9c
     pkg:deb/debian/curl@7.50.3-1?arch=i386&distro=jessie
@@ -47,8 +48,7 @@ Some `purl` examples
     pkg:rpm/fedora/curl@7.50.3-1.fc25?arch=i386&distro=fedora-25
 
 
-A `purl` is a URL
-=================
+## A `purl` is a URL
 
 - A `purl` is a valid URL and URI that conforms to the URL definitions or
   specifications at:
diff --git a/docs/tests.md b/docs/tests.md
@@ -1,5 +1,4 @@
-Tests
-=====
+## Tests
 
 To support the language-neutral testing of `purl` implementations, a test suite
 is provided as JSON document named `test-suite-data.json`. This JSON document
