docs: cover detached signatures in the getOriginalXmlWithIds() deprecation

README.md

@@ -301,7 +301,7 @@ To sign xml documents:
     - `existingPrefixes` - A hash of prefixes and namespaces `prefix: namespace` that shouldn't be in the signature because they already exist in the xml
 - `getSignedXml()` - returns the original xml document with the signature in it, **must be called only after `computeSignature`**
 - `getSignatureXml()` - returns just the signature part, **must be called only after `computeSignature`**
-- `getOriginalXmlWithIds()` - **[deprecated]** returns the original xml with Id attributes added on relevant elements, **must be called only after `computeSignature`**. Use the `location` option of `computeSignature()` to place the signature, then `getSignedXml()`. See [how to specify the location of the signature](#how-to-specify-the-location-of-the-signature).
+- `getOriginalXmlWithIds()` - **[deprecated]** returns the original xml with Id attributes added on relevant elements, **must be called only after `computeSignature`**. Use the `location` option of `computeSignature()` to place the signature, then `getSignedXml()`. See [how to specify the location of the signature](#how-to-specify-the-location-of-the-signature). For a detached signature, put an ID attribute the signer recognizes on each referenced element (`wsu:Id` for WS-Security), sign that document, and send it alongside `getSignatureXml()`. Make sure each reference XPath still selects its intended element once those IDs are present, for example by selecting on the ID itself.
 
 Every reference XPath is evaluated against the input document before any IDs or the signature
 are added, so the order of `addReference()` calls does not change what a reference selects. A

src/signed-xml.ts

@@ -31,7 +31,7 @@ type SigningReferenceTarget = { node: Element; digestValue?: string };
 
 const warnOriginalXmlWithIds = deprecate(
   () => {},
-  "`getOriginalXmlWithIds()` is deprecated and will be removed in a future version. Use the `location` option of `computeSignature()` to place the signature, then `getSignedXml()`.",
+  "`getOriginalXmlWithIds()` is deprecated and will be removed in a future version. Use the `location` option of `computeSignature()` to place the signature, then `getSignedXml()`. For a detached signature, put an ID attribute the signer recognizes on each referenced element (`wsu:Id` for WS-Security), sign that document, and send it alongside `getSignatureXml()`.",
   "XML_CRYPTO_GET_ORIGINAL_XML_WITH_IDS",
 );
 
@@ -1472,7 +1472,9 @@ export class SignedXml {
    *
    * @returns The original XML with IDs.
    * @deprecated Will be removed in a future version. Use the `location` option of
-   * {@link computeSignature} to place the signature, then {@link getSignedXml}.
+   * {@link computeSignature} to place the signature, then {@link getSignedXml}. For a detached
+   * signature, put an ID attribute the signer recognizes on each referenced element (`wsu:Id` for
+   * WS-Security), sign that document, and send it alongside {@link getSignatureXml}.
    */
   getOriginalXmlWithIds(): string {
     warnOriginalXmlWithIds();