more cleanup on podcast:verify #342

proposal-docs/verify/verify.md

@@ -39,8 +39,8 @@ Additional benefits are:
 ## 1. Check that quick-claiming is enabled in the RSS feed
 ```xml
 <podcast:verify
-auth="https://hostingprovider.com/claiming/" 
+  auth="https://hostingprovider.com/claiming/" 
-pub="MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9q9UU8I5mEovUf86QZ7kOBIjJwqnzD1omageEHWwHdBO6B+dFabmdT9POxg=="
+  pub="MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9q9UU8I5mEovUf86QZ7kOBIjJwqnzD1omageEHWwHdBO6B+dFabmdT9POxg=="
 />
 ```
 
@@ -49,9 +49,12 @@ public key you will use later to check the authenticity of the hosting provider'
 
 <br>
 
-## 2. Give the podcaster a Quick Claim button
+## 2. Give the podcaster a "Quick Claim" button
 
-You will redirect your user to the auth url present in the podcaster's RSS feed, with 1 to 3 URL parameters :
+You will redirect your user to the `auth` url present in the podcaster's RSS feed, with 1 to 3 URL parameters, as
+defined below.
+
+<br>
 
 ### Param: `consumer`
 Your directory/service base URL of the return_path.
@@ -65,48 +68,62 @@ for open graph data while ensuring the return path is tied to the hostname and i
 
 #### Examples:
 
-`consumer=https://podcastindex.org`
+`consumer=https://podcastindex.org` ⤵
-```
+```html
 PodcastIndex.org (podcastindex.org) 
 The Podcast Index is here to preserve, protect and extend the open, independent podcasting ecosystem.
 
 This service would like to verify you are the owner of this podcast. Do you want us to confirm ?
 ```
 
-`consumer=https://podcastindex.org/quick_claim`
+`consumer=https://podcastindex.org/quick_claim` ⤵
-```
+```html
 🗼PodcastIndex Quick Claiming (podcastindex.org) 
 Claiming your podcast into The Podcast Index directory gives you cool stuff !
 
 This service would like to verify you are the owner of this podcast. Do you want us to confirm ?
 ```
 
+<br>
+
 ### Param: `return_path`
-A path relative to consumer parameter, to redirect with the result of the authentication.
+A path relative to the `consumer` parameter, to redirect with the result of the authentication.  If the consumer is enough, 
-If the consumer is enough, you can omit it.
+you can omit it.
 
 #### Examples:
 
-`consumer=https://podcastindex.org/quick_claim` (no return path)
+These are example calculations of what the return url will be with different inputs:
-➡️ full return url will be `https://podcastindex.org/quick_claim?token=[token]`
 
-`consumer=https://podcastindex.org/quick_claim&return_path=/claimed.php`
+`consumer=https://podcastindex.org/quick_claim` (no return path) ⤵ <br>
-➡️ full return url will be `https://podcastindex.org/quick_claim/claimed.php?token=[token]`
+```curl
+https://podcastindex.org/quick_claim?token=[token]
+```
 
-`consumer=https://podcastindex.org/quick_claim&return_path=../claim.php`
+`consumer=https://podcastindex.org/quick_claim&return_path=/claimed.php` ⤵ <br>
-➡️ full return url will be `https://podcastindex.org/claim.php?token=[token]`
+```curl
+https://podcastindex.org/quick_claim/claimed.php?token=[token]
+```
+
+`consumer=https://podcastindex.org/quick_claim&return_path=../claim.php` ⤵ <br>
+```curl
+https://podcastindex.org/claim.php?token=[token]
+```
+
+<br>
 
 ### Param: `guid`
-If a `podcast:guid` is present in the RSS feed it SHOULD be included. If it's not we omit it or send an empty string.
+If a [`<podcast:guid>`](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid) is present in the RSS feed it SHOULD be included. If it's not we omit it or send an empty string.
 
 We keep it simple, we should trust the users of our spec (in this case the hosting providers) : if they don't include 
-a `podcast:guid`, I don't see the point to calculate it and give it to them, as they most likely don't have it on their 
+a [`<podcast:guid>`](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid), I don't see the point to calculate it and give it to them, as they most likely don't have it on their 
 hand and probably don't use it. If they would, it would be included in the feed.
 
-If we don't have any podcast:guid, maybe the hosting provider has only partial support of the podcasting 2.0 spec. Maybe
+If we don't have any [`<podcast:guid>`](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid), maybe the hosting provider has only partial support of the podcasting 2.0 spec. Maybe
 they only support claiming and include the guid in the auth url. Perhaps it's a Wordpress extension and there is only 
 one podcast and no need to "select a podcast" when you're logged in. We can't know and guess all usages.
 
+<br>
+
 ### PHP Example
 
 Here's a simple example, in PHP, of a quick claim button:
@@ -150,6 +167,7 @@ private key, and it can be verified using the `pub` attribute of the tag (put th
 
 You can verify the signature in PHP with a JWT library. If it fails to decode, it means the signature is wrong or the 
 token has expired:
+
 ```php
 $result = JWT::decode($quickClaimResponse, $feed["podcast:lock"]["pub"]);
 ```
@@ -175,7 +193,7 @@ If you're a podcast host wanting to add quick claiming for your customers, then
 
 <br>
 
-## 1. Add the `podcast:verify` tag to your RSS feeds
+## 1. Add the `<podcast:verify>` tag to your RSS feeds
 
 The tag needs two attributes :
 
@@ -345,12 +363,16 @@ if the user agreed.
 
 ## Full Workflow Example
 
-This section will summarize everything into one big example.
+This section will summarize everything into one big example.  Here are the defined terms we will use in this example:
 
-Say **DIRECTORY** is a podcast directory, **HOST** is a podcast hosting service, **PODCAST** is a show 
+- **DIRECTORY**: a podcast directory platform
-and **CREATOR** is a member of this show, allowed to claim the **PODCAST** on directories.
+- **HOST**: a podcast hosting service
+- **PODCAST** is a show with an RSS feed 
+- **CREATOR** is an owner of the **PODCAST** who is allowed to claim it 
 
-**HOST** adds this to the RSS feed:
+<br>
+
+**HOST** adds these elements to the RSS feed:
 
 ```xml
 <podcast:guid>ead4c236-bf58-58c6-a2c6-a6b28d128cb6</podcast:guid>
@@ -360,10 +382,12 @@ and **CREATOR** is a member of this show, allowed to claim the **PODCAST** on di
 />
 ```
 
-**DIRECTORY** presents a button labeled "Quick Claim".
+**DIRECTORY** presents a button labeled "Quick Claim" on the page of every **PODCAST**.
 
-When **CREATOR** clicks on it, they are redirected to **HOST** with this URL :
+When **CREATOR** clicks on the "Quick Claim" button on the page belonging to their **PODCAST**, they are redirected 
-```
+to their **HOST** with this URL:
+
+```yaml
 https://host.com/studio/quick_claim/?guid=ead4c236-bf58-58c6-a2c6-a6b28d128cb6&consumer=https://directory.com/quick_claiming/ead4c236-bf58-58c6-a2c6-a6b28d128cb6&return_path=/return
 ```
 
@@ -386,16 +410,15 @@ authenticating the **CREATOR** decision.
 ```
 
 #### Signed JWT: 
-```json
+```base64
 eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJndWlkIjoiZWFkNGMyMzYtYmY1OC01OGM2LWEyYzYtYTZiMjhkMTI4Y2I2IiwiYWNjZXB0ZWQiOnRydWV9.eOXYFi9uUSUAKWcI8GdJ15RIhjoCvR0l9TUCPsqhsTYqaGFTwbH6zXzYqIqhxmtSotvL8ZLumP64LRFBjHX5Mw
 ```
 
-<details>
-<summary>Note : You can follow along and "translate" online</summary>
-
 Decode/Encode online with : https://jwt.io/
 
-Private Key
+#### Key Details
+
+- Private Key
 ```
 -----BEGIN PRIVATE KEY-----
 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgevZzL1gdAFr88hb2
@@ -404,7 +427,7 @@ OF/2NxApJCzGCEDdfSp6VQO30hyhRANCAAQRWz+jn65BtOMvdyHKcvjBeBSDZH2r
 -----END PRIVATE KEY-----
 ```
 
-Public Key
+- Public Key
 ```
 -----BEGIN PUBLIC KEY-----
 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9
@@ -412,7 +435,7 @@ q9UU8I5mEovUf86QZ7kOBIjJwqnzD1omageEHWwHdBO6B+dFabmdT9POxg==
 -----END PUBLIC KEY-----
 ```
 
-</details>
+<br><br>
 
 **CREATOR** are redirected to the **DIRECTORY** with this URL: