The PMP resource key is the file name in the tag's URL

ci/generate-documentation.ps1

@@ -23,17 +23,42 @@ Write-Host "::group::Cloning API docs"
 $env:GIT_LFS_SKIP_SMUDGE = 1
 # use PR target branch if we're running in a PR, or the current CI branch, or main
 $ref = $env:GITHUB_BASE_REF ? $env:GITHUB_BASE_REF : $env:GITHUB_REF_NAME ? $env:GITHUB_REF_NAME : 'main'
+
+# An API repo is cloned at $ref where it has a branch of that name, so a
+# documentation change can be previewed against the API change it describes.
+# Where it has no such branch, main is used. Without the fallback the clone
+# fails and the whole preview fails, which is what a documentation branch
+# raised against another documentation branch always hits, because the name
+# of a documentation branch means nothing in an API repo.
+function Resolve-Ref($url, $preferred) {
+    if ($preferred -eq 'main') {
+        return 'main'
+    }
+    # ls-remote exits 0 with no output where the branch is absent, so the
+    # emptiness of the output is the test rather than the exit code.
+    $found = git ls-remote --heads $url $preferred
+    return $found ? $preferred : 'main'
+}
+
 $repoMap = & $PSScriptRoot/apis.ps1
 # repos have to be cloned here since they expect documentation repo to be two levels above them
 $apis = New-Item -Force -ItemType Directory "apis"
 # some repos want documentation at the same level as them, in addition(!) to two levels above
 New-Item -ItemType SymbolicLink -Force -Target $PWD -Path $apis/documentation | Out-Null
 foreach ($_ in $repoMap.GetEnumerator()) {
     $repo, $examples = $_.Key, $_.Value
-    git clone -b $ref --depth=1 --recurse-submodules --shallow-submodules "https://github.com/$env:GITHUB_REPOSITORY_OWNER/$repo.git" "$apis/$repo"
+    # Each repo is asked about on its own, because a branch can exist in one
+    # and not in the next, and an examples repo is a separate repo again.
+    $repoUrl = "https://github.com/$env:GITHUB_REPOSITORY_OWNER/$repo.git"
+    $repoRef = Resolve-Ref $repoUrl $ref
+    Write-Host "$repo at $repoRef"
+    git clone -b $repoRef --depth=1 --recurse-submodules --shallow-submodules $repoUrl "$apis/$repo"
     if ($examples) {
         # clone examples inside their main repo
-        git clone -b $ref --depth=1 "https://github.com/$env:GITHUB_REPOSITORY_OWNER/$examples.git" "$apis/$repo/$examples"
+        $examplesUrl = "https://github.com/$env:GITHUB_REPOSITORY_OWNER/$examples.git"
+        $examplesRef = Resolve-Ref $examplesUrl $ref
+        Write-Host "$examples at $examplesRef"
+        git clone -b $examplesRef --depth=1 $examplesUrl "$apis/$repo/$examples"
     }
 }
 Write-Host "::endgroup::"

src/identifiers/fodid.md

@@ -123,7 +123,7 @@ The block that does this is rendered into your script only when your Resource Ke
 
 ### The two sources, in order
 
-1. **The 51Degrees Preference Management Platform**, if it is on the page. The script reads the answer in force through the platform's getter, listens for the platform's window event, and falls back to the platform's own stored answer. All three answers count, `non-marketing` included, and each is sent as a stated `id.usage`. See @ref Identifiers_PMP.
+1. **The 51Degrees Preference Management Platform**, if it is on the page. The script reads the answer in force through the PMP's getter, listens for the PMP's window event, and falls back to the PMP's own stored answer. All three answers count, `non-marketing` included, and each is sent as a stated `id.usage`. See @ref Identifiers_PMP.
 2. **A Transparency and Consent Framework consent management platform**, through `window.__tcfapi`. The script registers a listener at construction and takes the string from a callback reporting `tcloaded` or `useractioncomplete`, sending it as `tcstring`. See @ref Identifiers_PMP_CmpWiring.
 
 The first source that has an answer wins and the rest are ignored, and the cloud applies the same order when the request arrives. A Global Privacy Platform string is never read by either side, because the Model Terms for Marketing at <https://m4ow.uk/mtm/2.txt> do not map it.

src/identifiers/fodid/gpp.md

@@ -10,7 +10,7 @@ The Global Privacy Platform is the IAB Tech Lab container that carries
 several consent signals in one string, one section per signal. The US
 Privacy string is the older signal written for the California Consumer
 Privacy Act, which IAB Tech Lab deprecated on 31 January 2024 and tells its
-users to replace with the platform.
+users to replace with the Global Privacy Platform.
 
 # What Happens to a Request Carrying One
 
@@ -41,11 +41,13 @@ Consent Framework's purposes onto standard marketing and personalized
 marketing, and maps no other signal, so a platform string can be a real
 signal and still say nothing a usage could be built from.
 
-This is not a special case for the platform. A framework string that grants
+This is not a special case for the Global Privacy Platform. A framework
+string that grants
 too little for either usage produces no identifier either, for the same
 reason, which is that the signal does not say what the usage values say.
 
-Mapping the platform needs a new version of the Model Terms and a cloud
+Mapping the Global Privacy Platform needs a new version of the Model Terms
+and a cloud
 release that reads it, so there is no setting on a resource key or a
 parameter on a request that turns this on.
 

src/identifiers/fodid/pmp.md

@@ -5,7 +5,7 @@ Terms for Marketing question and keeps the answer. That answer reaches the
 cloud as a stated `id.usage`, so the cloud works nothing out and the
 @ref Identifiers_51Did records that the usage was stated.
 
-The platform itself, being the tag, the dialog and the shared answer, is
+The PMP itself, being the tag, the dialog and the shared answer, is
 @ref Identifiers_PMP. This page is the part between the answer and the
 identifier.
 
@@ -30,7 +30,7 @@ own environment.
 
 You write no code for this.
 
-1. The visitor answers the dialog. The platform stores the answer,
+1. The visitor answers the dialog. The PMP stores the answer,
    announces it on the window as a `51d-pmp-preference` event and holds it
    behind `window.__51d_pmp.preference()`.
 2. The 51Degrees client script hears the announcement, or reads the getter
@@ -40,20 +40,20 @@ You write no code for this.
    produced, so the identifier is created after everything else about the
    page is known.
 
-The platform also serves a Transparency and Consent Framework surface of
+The PMP also serves a Transparency and Consent Framework surface of
 its own, so the client script can see both an answer and a string on the
-same page. The script asks the platform first and the framework second, and
+same page. The script asks the PMP first and the framework second, and
 the cloud applies the same order when the request arrives, so the answer is
 what travels and the string beside it is never examined. That is why an
-identifier made on a page running this platform records a stated usage. The
+identifier made on a page running the PMP records a stated usage. The
 other order, where a string is all there is, is
 @ref Identifiers_51Did_Tcf.
 
 # The Identifier Says the Usage Was Stated
 
 Bit 3 of the flags byte is the signal source bit, described under *Payload
 layout* on @ref Identifiers_51Did. It is clear on an identifier made from an
-answer given to this platform, because the caller stated the usage, and set
+answer given to the PMP, because the caller stated the usage, and set
 on one whose usage 51Degrees worked out from a consent string.
 
 The bit does not grade the two routes. It tells a recipient which one
@@ -76,8 +76,8 @@ reading anything into how few identifiers a site produces.
 
 # Find Out More
 
-- The platform, the dialog and the shared answer: @ref Identifiers_PMP
-- How the platform compares with a consent management platform:
+- The PMP, the dialog and the shared answer: @ref Identifiers_PMP
+- How the PMP compares with a consent management platform:
   @ref Identifiers_PMP_CmpComparison
 - The three answers, where each is kept and how to read the one in force:
   @ref Identifiers_PMP_Preferences

src/identifiers/fodid/tcf.md

@@ -6,9 +6,9 @@ records what a visitor consented to. The cloud reads that string, works out
 the usage of the @ref Identifiers_51Did from the purposes the string grants,
 and records inside the identifier that the usage came that way.
 
-Putting the platform and the 51Degrees client script on a page is
-@ref Identifiers_PMP_CmpWiring. This page is what the cloud does with the
-string once it arrives.
+Putting a consent management platform and the 51Degrees client script on
+a page is @ref Identifiers_PMP_CmpWiring. This page is what the cloud does
+with the string once it arrives.
 
 # Sending the String
 
@@ -120,7 +120,8 @@ See *Usage policies and licensing* on @ref Identifiers_51Did.
 - IAB Europe, the Framework Policies, which say which purposes may be
   claimed under legitimate interest:
   <https://iabeurope.eu/iab-europe-transparency-consent-framework-policies/>
-- IAB Tech Lab, the TC string format and the platform API:
+- IAB Tech Lab, the TC string format and the consent management platform
+  API:
   <https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework>
 - The client script that gathers the string:
   <https://github.com/51Degrees/javascript-templates>