From 190473fdcbc5ecd21a9b70663ece3ab9c2e7e603 Mon Sep 17 00:00:00 2001
From: MohitMali <futuretechnoworld.mohit@gmail.com>
Date: Fri, 11 Aug 2023 14:56:32 +0530
Subject: [PATCH] Update README with additional instructions for loading ZIM
 files and articles.

This commit updates the README file to include additional instructions for loading ZIM files and accessing articles in the Kiwix content archive using the `java-libkiwix` library.

Changes made in the README:
- Added a section explaining how to load a ZIM file by creating an `Archive` object.
- Clarified the description of the `mainPage` property, detailing its behavior when dealing with redirects and non-existent entries.
- Provided code snippets and instructions for loading articles via title and path, including a reminder to properly decode the URL path before passing it to `hasEntryByPath`.

These changes aim to improve the documentation and assist developers in effectively utilizing the `java-kibkiwix` library to work with zim files.
---
 README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/README.md b/README.md
index e4a2874..149481f 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,68 @@ Library for accessing [libkiwix](https://github.com/kiwix/libkiwix) and [libzim]
 
 AAR file will be generated in directory `lib/build/outputs/aar`
 
+### Load zim file
+
+To load a ZIM file you need to create an `Archive` object.
+
+```kotlin
+val archive = Archive("your-file-path")
+```
+
+### Load main page
+
+The `mainPage` property is used to retrieve the path of the main entry page for a Kiwix content archive.
+If the main entry is a redirect, it will fetch the path of the redirected item;
+otherwise, it will return the path of the main entry itself.
+If the main entry is not found, the archive will throw an `EntryNotFoundException`.
+
+```kotlin
+val mainPage: String?
+    get() =
+        try {
+            archive.mainEntry.getItem(true).path
+        } catch (entryNotFoundException: EntryNotFoundException) {
+            // Return `null` if the main entry is not present in the archive.
+            null
+        } catch (exception: Exception) {
+            // Other exception will thrown here e.g. the file is corrupted or any other error happened.
+            null
+        }
+```
+
+### Load an article via title
+
+```kotlin
+    try {
+        // If the article with the specified title exists in the archive,
+        // retrieve its path using the `getEntryByTitle` method.
+        archive.getEntryByTitle(title).path
+    } catch (entryNotFoundException: EntryNotFoundException) {
+        // If the article with the specified title does not exist in the archive,
+        // return `null`.
+        null
+    }
+```
+
+### Load an Article via Path
+
+Ensure that the URL path is properly decode before passing it to `hasEntryByPath`,
+as `Libzim` does not support encoded URLs.
+
+```kotlin
+    val decodedPath = URLDecoder.decode(actualpath, "UTF-8")
+    try {
+        // If the article with the specified URL exists in the archive,
+        // retrieve its actual path using the `getEntryByPath` method.
+        archive.getEntryByPath(decodedPath)
+            .getItem(true)
+            .path
+    } catch (entryNotFoundException: EntryNotFoundException) {
+        // If the article with the specified URL does not exist in the archive,
+        // return `null`.
+        null
+    }
+```
 
 # License