Fix documentation issues (#718)

Author: mickael-menu

docs/Guides/Content.md

@@ -37,7 +37,7 @@ This is an expensive operation, proceed with caution and cache the result if you
 The individual `Content` elements can be iterated through with a regular `for` loop by converting it to a sequence:
 
 ```swift
-for (element in content.sequence()) {
+for element in content.sequence() {
     // Process element
 }
 ```

docs/Guides/Getting Started.md

@@ -112,7 +112,7 @@ let assetRetriever = AssetRetriever(
     httpClient: httpClient
 )
 let publicationOpener = PublicationOpener(
-    publicationParser: DefaultPublicationParser(
+    parser: DefaultPublicationParser(
         httpClient: httpClient,
         assetRetriever: assetRetriever,
         pdfFactory: DefaultPDFDocumentFactory()

docs/Guides/Navigator/EPUB Fonts.md

@@ -1,6 +1,6 @@
 # Font families in the EPUB navigator
 
-Readium allows users to customize the font family used to render a reflowable EPUB, by changing the [EPUB navigator preferences](Navigator%20Preferences.md).
+Readium allows users to customize the font family used to render a reflowable EPUB, by changing the [EPUB navigator preferences](Preferences.md).
 
 > [!NOTE]
 > You cannot change the default font family of a fixed-layout EPUB (with zoomable pages), as it is similar to a PDF or a comic book.

docs/Guides/Navigator/Input.md

@@ -12,12 +12,12 @@ Here's an example of a simple `InputObserving` implementation that logs all key
 navigator.addObserver(InputObserver())
 
 @MainActor final class InputObserver: InputObserving {
-    func didReceive(_ event: PointerEvent) -> Bool {
+    func didReceive(_ event: PointerEvent) async -> Bool {
         print("Received pointer event: \(event)")
         return false
     }
-    
-    func didReceive(_ event: KeyEvent) -> Bool {
+
+    func didReceive(_ event: KeyEvent) async -> Bool {
         print("Received key event: \(event)")
         return false
     }
@@ -47,7 +47,7 @@ navigator.addObserver(.click(modifiers: [.shift]) { event in
 
 ## Observing keyboard events
 
-Similarly, the `KeyboardObserver` implementation provides an easy method to intercept keyboard events.
+Similarly, the `KeyObserver` implementation provides an easy method to intercept keyboard events.
 
 ```swift
 navigator.addObserver(.key { event in

docs/Guides/Navigator/Navigator.md

@@ -111,13 +111,13 @@ class MyNavigatorDelegate: NavigatorDelegate {
 
     override func navigator(_ navigator: Navigator, locationDidChange locator: Locator) {
         if let position = locator.locations.position {
-            print("At position \(position) on \(publication.positions.count)")
+            print("At position \(position)")
         }
         if let progression = locator.locations.progression {
-            return "Progression in the current resource: \(progression)%"
+            print("Progression in the current resource: \(progression.formatted(.percent))")
         }
         if let totalProgression = locator.locations.totalProgression {
-            return "Total progression in the publication: \(progression)%"
+            print("Total progression in the publication: \(totalProgression.formatted(.percent))")
         }
 
         // Save the position in your bookshelf database
@@ -151,8 +151,8 @@ To display a percentage-based progression slider, use the `locations.totalProgre
 Given a progression from 0 to 1, you can obtain a `Locator` object from the `Publication`. This can be used to navigate to a specific percentage within the publication.
 
 ```swift
-if let locator = publication.locate(progression: 0.5) {
-    navigator.go(to: locator)
+if let locator = await publication.locate(progression: 0.5) {
+    await navigator.go(to: locator)
 }
 ```
 
@@ -161,9 +161,7 @@ if let locator = publication.locate(progression: 0.5) {
 > [!NOTE]
 > Readium does not have the concept of pages, as they are not useful when dealing with reflowable publications across different screen sizes. Instead, we use [**positions**](https://readium.org/architecture/models/locators/positions/) which remain stable even when the user changes the font size or device.
 
-Not all Navigators provide positions, but most `VisualNavigator` implementations do. Verify if `publication.positions` is not empty to determine if it is supported.
-
-To find the total positions in the publication, use `publication.positions.count`. You can get the current position with `navigator.currentLocation?.locations.position`.
+Not all Navigators provide positions, but most `VisualNavigator` implementations do. To find the total positions in the publication, use `try await publication.positions().get().count`. You can get the current position with `navigator.currentLocation?.locations.position`.
 
 ## Navigating with edge taps and keyboard arrows
 

docs/Guides/Readium LCP.md

@@ -224,30 +224,25 @@ Users need to import a License Document into your application to download the pr
 The `LCPService` offers an API to retrieve the full publication from an LCPL on the filesystem.
 
 ```swift
-let acquisition = lcpService.acquirePublication(
-    from: lcplURL,
+let result = await lcpService.acquirePublication(
+    from: .file(lcplURL),
     onProgress: { progress in
         switch progress {
             case .indefinite:
                 // Display an activity indicator.
             case .percent(let percent):
                 // Display a progress bar with percent from 0 to 1.
         }
-    },
-    completion: { result in
-        switch result {
-        case let .success(publication):
-            // Import the `publication.localURL` file as any publication.
-        case let .failure(error):
-            // Display the error message
-        case .cancelled:
-            // The acquisition was cancelled before completion.
-        }
     }
 )
-```
 
-If the user wants to cancel the download, call `cancel()` on the object returned by `LCPService.acquirePublication()`.
+switch result {
+case let .success(publication):
+    // Import the `publication.localURL` file as any publication.
+case let .failure(error):
+    // Display the error message.
+}
+```
 
 After the download is completed, import the `publication.localURL` file into the bookshelf like any other publication file.
 
@@ -308,7 +303,7 @@ The `allowUserInteraction` and `sender` arguments are forwarded to the `LCPAuthe
 When importing the publication to the bookshelf, set `allowUserInteraction` to `false` as you don't need the passphrase for accessing the publication metadata and cover. If you intend to present the publication using a Navigator, set `allowUserInteraction` to `true` as decryption will be required.
 
 > [!TIP]
-> To check if a publication is protected with LCP before opening it, you can use `LCPService.isLCPProtected()`.
+> To check if an asset is protected with LCP before opening it, you can use `asset.format.conformsTo(.lcp)`.
 
 ### Using the opened `Publication`
 
@@ -370,36 +365,30 @@ An LCP License Document contains metadata such as its expiration date, the remai
 Use the `LCPService` to retrieve the `LCPLicense` instance for a publication.
 
 ```swift
-lcpService.retrieveLicense(
-    from: publicationURL,
+let result = await lcpService.retrieveLicense(
+    from: asset,
     authentication: LCPDialogAuthentication(),
     allowUserInteraction: true,
     sender: hostViewController
-) { result in
-    switch result {
-    case .success(let lcpLicense):
-        if let lcpLicense = lcpLicense {
-            if let user = lcpLicense.license.user.name {
-                print("The publication was acquired by \(user)")
-            }
-            if let endDate = lcpLicense.license.rights.end {
-                print("The loan expires on \(endDate)")
-            }
-            if let copyLeft = lcpLicense.charactersToCopyLeft {
-                print("You can copy up to \(copyLeft) characters remaining.")
-            }
-        } else {
-            // The file was not protected by LCP.
-        }
-    case .failure(let error):
-        // Display the error.
-    case .cancelled:
-        // The operation was cancelled.
+)
+
+switch result {
+case .success(let lcpLicense):
+    if let user = lcpLicense.license.user.name {
+        print("The publication was acquired by \(user)")
     }
+    if let endDate = lcpLicense.license.rights.end {
+        print("The loan expires on \(endDate)")
+    }
+    if let copyLeft = await lcpLicense.charactersToCopyLeft() {
+        print("You can copy up to \(copyLeft) characters remaining.")
+    }
+case .failure(let error):
+    // Display the error.
 }
 ```
 
-If you have already opened a `Publication` with the `Streamer`, you can directly obtain the `LCPLicense` using `publication.lcpLicense`.
+If you have already opened a `Publication` with the `PublicationOpener`, you can directly obtain the `LCPLicense` using `publication.lcpLicense`.
 
 ## Managing a loan
 
@@ -410,12 +399,12 @@ Readium LCP allows borrowing publications for a specific period. Use the `LCPLic
 Some loans can be returned before the end date. You can confirm this by using `lcpLicense.canReturnPublication`. To return the publication, execute:
 
 ```swift
-lcpLicense.returnPublication { error in
-    if let error = error {
-        // Present the error.
-    } else {
-        // The publication was returned.
-    }
+let result = await lcpLicense.returnPublication()
+switch result {
+case .success:
+    // The publication was returned.
+case .failure(let error):
+    // Present the error.
 }
 ```
 
@@ -431,17 +420,17 @@ Readium LCP supports [two types of renewal interactions](https://readium.org/lcp
 You need to support both interactions by implementing the `LCPRenewDelegate` protocol. A default implementation is available with `LCPDefaultRenewDelegate`.
 
 ```swift
-lcpLicense.renewLoan(
+let result = await lcpLicense.renewLoan(
     with: LCPDefaultRenewDelegate(
         presentingViewController: hostViewController
     )
-) { result in
-    switch result {
-    case .success, .cancelled:
-        // The publication was renewed.
-    case let .failure(error):
-        // Display the error.
-    }
+)
+
+switch result {
+case .success:
+    // The publication was renewed.
+case let .failure(error):
+    // Display the error.
 }
 ```
 
@@ -453,7 +442,7 @@ For an example, [take a look at the Test App](https://github.com/readium/swift-t
 
 ## Using the SwiftUI LCP Authentication dialog
 
-If your application is built using SwiftUI, you cannot use `LCPAuthenticationDialog` because it requires a UIKit view controller as its host. Instead, use an `LCPObservableAuthentication` combined with our SwiftUI `LCPDialog` presented as a sheet.
+If your application is built using SwiftUI, you cannot use `LCPDialogAuthentication` because it requires a UIKit view controller as its host. Instead, use an `LCPObservableAuthentication` combined with our SwiftUI `LCPDialog` presented as a sheet.
 
 ```swift
 @main

docs/Migration Guide.md

@@ -435,16 +435,16 @@ let navigator = try EPUBNavigatorViewController(
 
 ### Upgrading to the new Preferences API
 
-The 2.5.0 release introduces a brand new user preferences API for configuring the EPUB and PDF Navigators. This new API is easier and safer to use. To learn how to integrate it in your app, [please refer to the user guide](Guides/Navigator%20Preferences.md).
+The 2.5.0 release introduces a brand new user preferences API for configuring the EPUB and PDF Navigators. This new API is easier and safer to use. To learn how to integrate it in your app, [please refer to the user guide](Guides/Navigator/Preferences.md).
 
 If you integrated the EPUB navigator from a previous version, follow these steps to migrate:
 
-1. Get familiar with [the concepts of this new API](Guides/Navigator%20Preferences.md#overview).
+1. Get familiar with [the concepts of this new API](Guides/Navigator/Preferences.md#overview).
 2. Migrate the local HTTP server from your app, [as explained in the previous section](#migrating-the-http-server).
-3. Adapt your user settings interface to the new API using preferences editors. The [Test App](https://github.com/readium/swift-toolkit/blob/2.5.0/TestApp/Sources/Reader/Common/Preferences/UserPreferences.swift) and the [user guide](Guides/Navigator%20Preferences.md#build-a-user-settings-interface) contain examples using SwiftUI.
-4. [Handle the persistence of the user preferences](Guides/Navigator%20Preferences.md#save-and-restore-the-user-preferences). The settings are not stored in the User Defaults by the toolkit anymore. Instead, you are responsible for persisting and restoring the user preferences as you see fit (e.g. as a JSON file).
+3. Adapt your user settings interface to the new API using preferences editors. The [Test App](https://github.com/readium/swift-toolkit/blob/2.5.0/TestApp/Sources/Reader/Common/Preferences/UserPreferences.swift) and the [user guide](Guides/Navigator/Preferences.md#build-a-user-settings-interface) contain examples using SwiftUI.
+4. [Handle the persistence of the user preferences](Guides/Navigator/Preferences.md#save-and-restore-the-user-preferences). The settings are not stored in the User Defaults by the toolkit anymore. Instead, you are responsible for persisting and restoring the user preferences as you see fit (e.g. as a JSON file).
     * If you want to migrate the legacy EPUB settings, you can use the helper `EPUBPreferences.fromLegacyPreferences()` which will create a new `EPUBPreferences` object after translating the existing user settings.
-5. Make sure you [restore the stored user preferences](Guides/Navigator%20Preferences.md#setting-the-initial-navigator-preferences-and-app-defaults) when initializing the EPUB navigator.
+5. Make sure you [restore the stored user preferences](Guides/Navigator/Preferences.md#setting-the-initial-navigator-preferences-and-app-defaults) when initializing the EPUB navigator.
 
 Please refer to the following table for the correspondence between legacy settings (from `UserSettings`) and new ones (`EPUBPreferences`).