From 225d177a4bc10dfc6bc3e73353c9176913d0bf16 Mon Sep 17 00:00:00 2001 From: daveajones Date: Sun, 4 Jun 2023 09:18:02 -0500 Subject: [PATCH] formatting cleanup done --- docs/1.0.md | 188 +++++++++++++++++++++++++++++++++------------------- 1 file changed, 120 insertions(+), 68 deletions(-) diff --git a/docs/1.0.md b/docs/1.0.md index da93659..556b4e3 100644 --- a/docs/1.0.md +++ b/docs/1.0.md @@ -1033,9 +1033,12 @@ A complete example: https://example.com/images/live/pci_avatar-small.jpg 300w, https://example.com/images/live/pci_avatar-tiny.jpg 150w" /> - Adam Curry - Dave Jones - Becky Smith + Adam Curry + Dave Jones + Becky Smith @@ -1061,12 +1064,14 @@ A bare bones example:



## Content Link ``

-The `contentLink` tag is used to indicate that the content begin delivered by the parent element can be found at an external location -instead of, or in addition to, being delivered directly to the tag itself within an app. In most instances it is used as a fallback link for the user -to use when the app itself can't handle a certain content delivery directly. +The `contentLink` tag is used to indicate that the content begin delivered by the parent element can be found at an +external location instead of, or in addition to, being delivered directly to the tag itself within an app. In most +instances it is used as a fallback link for the user to use when the app itself can't handle a certain content +delivery directly. -For instance, perhaps a podcast feed specifies a `` to deliver a live stream to apps. The feed may also give a `` -pointing to YouTube and Twitch versions of the live stream as well, just in case the listener uses an app that doesn't fully support live streaming content. +For instance, perhaps a podcast feed specifies a `` to deliver a live stream to apps. The feed +may also give a `` pointing to YouTube and Twitch versions of the live stream as well, just in +case the listener uses an app that doesn't fully support live streaming content. Currently this tag is only indicated for use in the `` tag. In the future, its use will be expanded. @@ -1077,7 +1082,8 @@ Currently this tag is only indicated for use in the `` tag. I   Multiple ### Node Value -The node value is a free form string meant to explain to the user where this content link points and/or the nature of it's purpose. +The node value is a free form string meant to explain to the user where this content link points and/or the nature +of it's purpose. ### Attributes - **href** (required) A string that is the uri pointing to content outside of the application. @@ -1096,17 +1102,18 @@ The node value is a free form string meant to explain to the user where this con



## Social Interact ``

-The `socialInteract` tag allows a podcaster to attach the url of a "root post" of a comment thread to an episode. This "root post" -is treated as the canonical location of where the comments and discussion around this episode will take place. This can be thought -of as the "official" social media comment space for this episode. If a protocol such as "activitypub" is used, or some other -protocol that allows programmatic API access, these comments can be directly pulled into the app, and replies can be posted back to -the thread from the app itself. +The `socialInteract` tag allows a podcaster to attach the url of a "root post" of a comment thread to an episode. +This "root post" is treated as the canonical location of where the comments and discussion around this episode will +take place. This can be thought of as the "official" social media comment space for this episode. If a protocol +such as "activitypub" is used, or some other protocol that allows programmatic API access, these comments can be +directly pulled into the app, and replies can be posted back to the thread from the app itself. -If multiple `socialInteract` tags are given for an ``, the `priority` attribute is strongly recommended to give the app an -indication as to which comments to display first. +If multiple `socialInteract` tags are given for an ``, the `priority` attribute is strongly recommended to +give the app an indication as to which comments to display first. -This tag can also be used as a signal to platforms and apps that the podcaster does not want public comments shown alongside this -episode. For this purpose a `protocol` value of "disabled" can be specified, with no other attributes or node value present. +This tag can also be used as a signal to platforms and apps that the podcaster does not want public comments shown +alongside this episode. For this purpose a `protocol` value of "disabled" can be specified, with no other +attributes or node value present. ### Parent   `` @@ -1119,19 +1126,35 @@ episode. For this purpose a `protocol` value of "disabled" can be specified, wi - **protocol** (required) The [protocol](/socialprotocols.txt) in use for interacting with the comment root post. - **accountId** (recommended) The account id (on the commenting platform) of the account that created this root post. - **accountUrl** (optional) The public url (on the commenting platform) of the account that created this root post. -- **priority** (optional) When multiple socialInteract tags are present, this integer gives order of priority. A - lower number means higher priority. +- **priority** (optional) When multiple socialInteract tags are present, this integer gives order of priority. A + lower number means higher priority. Example (simple): ```xml - + ``` Example (complex): ```xml - - + + ``` Example (disabled): @@ -1139,18 +1162,20 @@ Example (disabled): ``` -* For **activitypub**, Mastodon or Pleroma's posting API returns a URI (a fully-formed URL with a GUID in it), and a URL (the HTML page where the comment lives). While both of these are acceptable values for the `uri` field referenced in the `socialInteract` specification, we'd recommend using the URI value. +* For **activitypub**, Mastodon or Pleroma's posting API returns a URI (a fully-formed URL with a GUID in it), and a + URL (the HTML page where the comment lives). While both of these are acceptable values for the `uri` field + referenced in the `socialInteract` specification, we'd recommend using the URI value.



## Block ``

-This element allows a podcaster to express which platforms are allowed to publicly display this feed and its contents. -In its basic form, it is a direct drop-in replacement for the `` tag, but allows for greater flexibility -by the inclusion of the `id` attribute and by including multiple copies of itself in the feed. +This element allows a podcaster to express which platforms are allowed to publicly display this feed and its +contents. In its basic form, it is a direct drop-in replacement for the `` tag, but allows for greater +flexibility by the inclusion of the `id` attribute and by including multiple copies of itself in the feed. -Platforms should not ingest a feed for public display/use if their slug exists in the `id` of a `yes` block tag, or if -an unbounded `yes` block tag exists (meaning block all public ingestion). Conversely, if a platform finds their slug in -the `id` of a `no` block tag, they are free to ingest that feed for public display/usage. +Platforms should not ingest a feed for public display/use if their slug exists in the `id` of a `yes` block tag, or +if an unbounded `yes` block tag exists (meaning block all public ingestion). Conversely, if a platform finds their +slug in the `id` of a `no` block tag, they are free to ingest that feed for public display/usage. In plain language, the sequence of discovery an ingesting platform should use is as follows: @@ -1166,7 +1191,8 @@ In plain language, the sequence of discovery an ingesting platform should use is   Multiple ### Attributes - - **id** (optional) A single entry from the [service slug list](https://github.com/Podcastindex-org/podcast-namespace/blob/main/serviceslugs.txt). + - **id** (optional) A single entry from the [service slug list](https://github. + com/Podcastindex-org/podcast-namespace/blob/main/serviceslugs.txt). ### Node value   The node value must be "yes" or "no". @@ -1200,9 +1226,11 @@ In plain language, the sequence of discovery an ingesting platform should use is



## Txt ``

-This element holds free-form text and is modeled after the DNS "[TXT](https://en.wikipedia.org/wiki/TXT_record)" record. It's meant to allow for usages that might be -niche or otherwise not rise to the level of needing a dedicated tag. Just like TXT records in DNS allowed for new things -like [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework#Implementation) to evolve, this tag can allow novel techniques to be created and sandboxed without a formalization process. +This element holds free-form text and is modeled after the DNS "[TXT](https://en.wikipedia.org/wiki/TXT_record)" +record. It's meant to allow for usages that might be niche or otherwise not rise to the level of needing a +dedicated tag. Just like TXT records in DNS allowed for new things like [SPF](https://en.wikipedia. +org/wiki/Sender_Policy_Framework#Implementation) to evolve, this tag can allow novel techniques to be created and +sandboxed without a formalization process. ### Parent   `` or `` @@ -1211,23 +1239,23 @@ like [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework#Implementation)   Multiple ### Attributes -- **purpose** (optional) A service specific string that will be used to denote what purpose this tag serves. This could - be something like "example.com" if it's a third party hosting platform needing to insert this - data, or something like "verify", "release" or any other free form bit of info that is - useful to the end consumer that needs it. The free form nature of this tag requires that this - attribute is also free formed. This value should not exceed `128 characters`. +- **purpose** (optional) A service specific string that will be used to denote what purpose this tag serves. This + could be something like "example.com" if it's a third party hosting platform needing to insert this data, or + something like "verify", "release" or any other free form bit of info that is useful to the end consumer that + needs it. The free form nature of this tag requires that this attribute is also free formed. This value should not + exceed `128 characters`. ### Purposes -The following are a list of strings known to be in common use. This list is in no way exhaustive. As new purposes come into -common use, this list will be updated by the community to reflect that. +The following are a list of strings known to be in common use. This list is in no way exhaustive. As new purposes +come into common use, this list will be updated by the community to reflect that. -- `verify` - The node value is expected to contain a string that is given by a third party platform to a podcaster in - order to prove that they are the owner of the feed and are in control of it. This is meant to replace the - need for emails to exist in feeds. See example section below. +- `verify` - The node value is expected to contain a string that is given by a third party platform to a podcaster + in order to prove that they are the owner of the feed and are in control of it. This is meant to replace the need + for emails to exist in feeds. See example section below. ### Node value -  This is a free form string. Please do not exceed `4000 characters` for the node value or it may be truncated by - aggregators. +  This is a free form string. Please do not exceed `4000 characters` for the node value or it may be +truncated by aggregators. ### Examples ```xml @@ -1247,15 +1275,15 @@ common use, this list will be updated by the community to reflect that.



## Remote Item ``

-This element provides a way to "point" to another feed or an `` in another feed in order to obtain some sort of -data that the other feed or feed item has. This allows a podcast app to know where to go and fetch the data being -requested. What data is being requested is determined by the parent item. For instance, if the parent item is a -`` element, then the remote feed's `` metadata is needed. +This element provides a way to "point" to another feed or an `` in another feed in order to obtain some sort +of data that the other feed or feed item has. This allows a podcast app to know where to go and fetch the data +being requested. What data is being requested is determined by the parent item. For instance, if the parent item +is a `` element, then the remote feed's `` metadata is needed. -Using the `feedGuid` attribute is the preferred way to address a remote feed since, but there are times when an app may -not have access to a list of resolvable ``'s. In that case, it can be beneficial to include the `feedUrl` -attribute for those cases as a fallback. If both are present and the app is capable the `feedGuid` should be resolved -and used. +Using the `feedGuid` attribute is the preferred way to address a remote feed since, but there are times when an app +may not have access to a list of resolvable ``'s. In that case, it can be beneficial to include the +`feedUrl` attribute for those cases as a fallback. If both are present and the app is capable the `feedGuid` should +be resolved and used. ### Parent   `` or `` or `` @@ -1267,11 +1295,11 @@ and used. - **feedGuid** (required) The `` of the remote feed being pointed to. - **feedUrl** (optional) The url of the remote feed being pointed to. - **itemGuid** (optional) If this remote item element is intended to point to an `` in the remote feed, this - attribute should contain the value of the `` of that ``. -- **medium** (optional) If the feed being pointed to is not of medium type 'podcast', this attribute should contain it's - `` type from the [list](#medium) of types available in this document. The - reason this is helpful is to give the app a heads up on what type of data this is expected to be - since that may affect the way it approaches fetch and display. + attribute should contain the value of the `` of that ``. +- **medium** (optional) If the feed being pointed to is not of medium type 'podcast', this attribute should contain + it's `` type from the [list](#medium) of types available in this document. The reason this is + helpful is to give the app a heads up on what type of data this is expected to be since that may affect the way it + approaches fetch and display. ### Examples ```xml @@ -1299,7 +1327,7 @@ and used.



## Podroll ``

-This element allows for a podcaster to include references to one or more podcasts in it's `` as a way of +This element allows for a podcaster to include references to one or more podcasts in it's `` as a way of "recommending" other podcasts to their listener. ### Parent @@ -1332,42 +1360,66 @@ This element allows a podcaster to express their intended release schedule as st Single ### Node value -The node value is a free-form string, which might be displayed alongside other information about the podcast. Please do not exceed `128 characters` for the node value or it may be truncated by aggregators. +The node value is a free-form string, which might be displayed alongside other information about the podcast. Please +do not exceed `128 characters` for the node value or it may be truncated by aggregators. ## Attributes -* **complete (optional):** Boolean specifying if the podcast has no intention to release further episodes. If not set, this should be assumed to be false. -* **dtstart (optional):** The `date` or `datetime` the recurrence rule begins as an [ISO8601-fornmatted](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) string. If the `rrule` contains a value for `COUNT`, then this attribute is required. If the `rrule` contains a value for `UNTIL`, then the value of this attribute must be formatted to the same date/datetime standard. -* **rrule (recommended):** A recurrence rule as defined in [iCalendar RFC 5545 Section 3.3.10](https://www.rfc-editor.org/rfc/rfc5545#section-3.3.10). +* **complete (optional):** Boolean specifying if the podcast has no intention to release further episodes. If not + set, this should be assumed to be false. +* **dtstart (optional):** The `date` or `datetime` the recurrence rule begins as an [ISO8601-fornmatted] + (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) string. If the + `rrule` contains a value for `COUNT`, then this attribute is required. If the `rrule` contains a value for `UNTIL`, + then the value of this attribute must be formatted to the same date/datetime standard. +* **rrule (recommended):** A recurrence rule as defined in [iCalendar RFC 5545 Section 3.3.10](https://www. + rfc-editor.org/rfc/rfc5545#section-3.3.10). ## Examples Recreating most of Apple Podcasts Connect’s “Update Frequency” values is easily achieved: ```xml Daily + Weekly + Biweekly + Monthly + Bimonthly + Monthly + Yearly ``` However, greater precision can be easily communicated: ```xml Every weekday + Every Monday and Wednesday + Every friday the 13th -Every year on American Thanksgiving + + + Every year on American Thanksgiving + ``` Limited-run podcasts can indicate when they’ll go on hiatus by setting an UNTIL date or a COUNT: ```xml -Every other Monday for 10 episodes starting on Aug 28, 2023 -Every Monday until Dec 31, 2023 + + Every other Monday for 10 episodes starting on Aug 28, 2023 + + + + Every Monday until Dec 31, 2023 + ``` Podcasts currently on hiatus can indicate their intention to resume production by setting a DTSTART value in the future: ```xml -Weekly, starting in 2025 + + Weekly, starting in 2025 + ``` Complete podcasts with no intention to release further episodes: