Update pypandoc and related code, structure and output #581

- Includes updating the content and location of the two pypandoc output
  files, purl-specification.md and purl-standard.md.

Reference: #581
Signed-off-by: John M. Horan <johnmhoran@gmail.com>

Author: johnmhoran

docs/standard/purl-is-url.md

@@ -19,3 +19,33 @@ Table 1: Components of a PURL
 Components are separated by a specific character for unambiguous parsing. Components are designed such that they form a hierarchy from the most significant on the left to the least significant on the right.
 
 A ``purl`` must NOT contain a URL Authority. i.e. there is no support for ``username``, ``password``, ``host`` and ``port`` components. A ``namespace`` segment may sometimes look like a ``host`` but its interpretation is specific to a ``type``.
+
+## A ``purl`` is a URL
+
+- A ``purl`` is a valid URL and URI that conforms to the URL definitions or
+  specifications at:
+  - https://tools.ietf.org/html/rfc3986
+  - https://en.wikipedia.org/wiki/URL#Syntax
+  - https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#Syntax
+  - https://url.spec.whatwg.org/
+- This is a valid URL because it is a locator even though it has no Authority
+  URL component: each ``type`` has a default repository location when defined.
+- The ``purl`` components are mapped to these URL components:
+  - ``purl`` ``scheme``: this is a URL ``scheme`` with a constant value: ``pkg``
+  - ``purl`` ``type``, ``namespace``, ``name`` and ``version`` components: these are
+    collectively mapped to a URL ``path``
+  - ``purl`` ``qualifiers``: this maps to a URL ``query``
+  - ``purl`` ``subpath``: this is a URL ``fragment``
+  - In a ``purl`` there is no support for a URL Authority (e.g. NO
+    ``username``, ``password``, ``host`` and ``port`` components).
+- Special URL schemes as defined in https://url.spec.whatwg.org/ such as
+  ``file://``, ``https://``, ``http://`` and ``ftp://`` are NOT valid ``purl`` types.
+  They are valid URL or URI schemes but they are not ``purl``.
+  They may be used to reference URLs in separate attributes outside of a ``purl``
+  or in a ``purl`` qualifier.
+- Version control system (VCS) URLs such ``git://``, ``svn://``, ``hg://`` or as
+  defined in Python pip or SPDX download locations are NOT valid ``purl`` types.
+  They are valid URL or URI schemes but they are not ``purl``.
+  They are a closely related, compact and uniform way to reference VCS URLs.
+  They may be used as references in separate attributes outside of a ``purl`` or
+  in a ``purl`` qualifier.

docs/standard/specification-summary.md

@@ -81,28 +81,6 @@ A `purl` must NOT contain a URL Authority. i.e. there is no support for
 segment may sometimes look like a `host` but its interpretation is
 specific to a `type`.
 
-## Some `purl` examples
-
-> pkg:bitbucket/birkenfeld/pygments-main@244fd47e07d1014f0aed9c
->
-> pkg:deb/debian/curl@7.50.3-1?arch=i386&distro=jessie
->
-> pkg:gem/ruby-advisory-db-check@0.12.4
->
-> pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c
->
-> pkg:golang/google.golang.org/genproto#googleapis/api/annotations
->
-> pkg:maven/org.apache.xmlgraphics/batik-anim@1.9.1?packaging=sources
->
-> pkg:npm/foobar@12.3.1
->
-> pkg:nuget/EnterpriseLibrary.Common@6.0.1304
->
-> pkg:pypi/django@1.11.1
->
-> pkg:rpm/fedora/curl@7.50.3-1.fc25?arch=i386&distro=fedora-25
-
 ## A `purl` is a URL
 
 - A `purl` is a valid URL and URI that conforms to the URL definitions
@@ -134,6 +112,28 @@ specific to a `type`.
   reference VCS URLs. They may be used as references in separate
   attributes outside of a `purl` or in a `purl` qualifier.
 
+## Some `purl` examples
+
+> pkg:bitbucket/birkenfeld/pygments-main@244fd47e07d1014f0aed9c
+>
+> pkg:deb/debian/curl@7.50.3-1?arch=i386&distro=jessie
+>
+> pkg:gem/ruby-advisory-db-check@0.12.4
+>
+> pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c
+>
+> pkg:golang/google.golang.org/genproto#googleapis/api/annotations
+>
+> pkg:maven/org.apache.xmlgraphics/batik-anim@1.9.1?packaging=sources
+>
+> pkg:npm/foobar@12.3.1
+>
+> pkg:nuget/EnterpriseLibrary.Common@6.0.1304
+>
+> pkg:pypi/django@1.11.1
+>
+> pkg:rpm/fedora/curl@7.50.3-1.fc25?arch=i386&distro=fedora-25
+
 ## Rules for each `purl` component
 
 A `purl` string is an ASCII URL string composed of seven components.