Update documentation about document decryption

README.md

@@ -1413,35 +1413,26 @@ See also [MAINTAINERSHIP.md#communication](docs/MAINTAINERSHIP.md#communication)
 
 ## Encryption Handling
 
-**`pdf-lib` does not currently support encrypted documents.** You should not use `pdf-lib` with encrypted documents. However, this is a feature that could be added to `pdf-lib`. Please [create an issue](https://github.com/Hopding/pdf-lib/issues/new) if you would find this feature helpful!
+**`pdf-lib` does support encrypted documents.**
 
-When an encrypted document is passed to `PDFDocument.load(...)`, an error will be thrown:
+To load a document, use this:
 
-<!-- prettier-ignore -->
 ```js
-import { PDFDocument, EncryptedPDFError } from 'pdf-lib'
-
-const encryptedPdfBytes = ...
-
-// Assignment fails. Throws an `EncryptedPDFError`.
-const pdfDoc = PDFDocument.load(encryptedPdfBytes)
+// Load a random document you know nothing about:
+const doc = PDFDocument.load(content, { ignoreEncryption: true })
+// Check if the document is encrypted:
+const isEncrypted = doc.isEncrypted
+// If isEncrypted is true, you know the you need to ask the user for the password.
 ```
 
-This default behavior is usually what you want. It allows you to easily detect if a given document is encrypted, and it prevents you from trying to modify it. However, if you really want to load the document, you can use the `{ ignoreEncryption: true }` option:
+If you know the password of the document, or if it was provided by the user, you can now open the document with it:
 
 ```js
-import { PDFDocument } from 'pdf-lib'
-
-const encryptedPdfBytes = ...
-
-// Assignment succeeds. Does not throw an error.
-const pdfDoc = PDFDocument.load(encryptedPdfBytes, { ignoreEncryption: true })
+// Load an encrypted document with its password:
+const password = "The password"
+const doc = PDFDocument.load(content, { ignoreEncryption: true, password })
 ```
 
-Note that **using this option does not decrypt the document**. This means that any modifications you attempt to make on the returned `PDFDocument` may fail, or have unexpected results.
-
-**You should not use this option.** It only exists for backwards compatibility reasons.
-
 ## Contributing
 
 We welcome contributions from the open source community! If you are interested in contributing to `pdf-lib`, please take a look at the [CONTRIBUTING.md](docs/CONTRIBUTING.md) file. It contains information to help you get `pdf-lib` setup and running on your machine. (We try to make this as simple and fast as possible! :rocket:)