From 9a01010d287b0a3d6d05e8ea92f0002d81c88cff Mon Sep 17 00:00:00 2001 From: Matthieu Gautier Date: Mon, 25 Nov 2024 11:34:20 +0100 Subject: [PATCH] Improve README --- README.md | 99 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 55 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index be344e4..8a62083 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,86 @@ -Zim to Waj -========== +# Zim2Waj: Zim to Waj Converter +**A command-line tool to convert Zim archives to the Waj (Web Archive Jubako) format.** -A tool to convert a Zim file into a Waj file. +Waj, a format based on Jubako, is designed for storing web content (static websites). +Like ZIM files, Waj archives can contain HTML, CSS, and JavaScript resources. The key advantage of Waj (as Zim) is that its content can be served directly by a local webserver without prior extraction, enhancing speed and convenience. Unlike ZIM, Waj omits metadata, full-text indexes, and title indexes, focusing solely on web resources. -Waj (Web Archive Jubako) is a format based on Jubako to store web content (aka static website). +However, Waj can store binary content in a separated pack, which allow to have text only archive than can be upgraded to +full archive only by adding the binary content. -As ZIM files, a Waj can contains web resources (html, css, js). -The content can be directly served as a local webserver without extracting the archive content first. +## Installation -Contrarly to ZIM, Waj contains only web resources. -It doesn't contain a fulltext index nor a title index. So it is not possible to search content in it [TODO] +zim2waj relies on the `zim-rs` and `zim-sys` crates, which in turn depend on the `libzim` library. You must have `libzim` installed before compiling `zim2waj`. -`zim2waj` tool read a ZIM archive and create a Waj archive, excluding Metadata, fulltext index and title index. +**1. Install libzim:** +* **Linux (using package managers):** -Installing zim2waj ------------------- + ```bash + sudo dnf install libzim-devel # Fedora/CentOS/RHEL + ``` + or -To read zim content, zim2waj is based on [zim-rs](https://crates.io/crates/zim-rs) and [zim-sys](https://crates.io/crates/zim-sys) -which in turn, use [libzim](https://github.com/openzim/libzim) library. + ```bash + sudo apt-get install libzim-dev # Debian/Ubuntu + ``` -You need to have libzim installed to be able to compile `zim2waj` +* **Linux (or other systems) using pre-built binaries:** Download pre-built binaries from [https://download.openzim.org/release/libzim/](https://download.openzim.org/release/libzim/). You will need to set the `PKG_CONFIG_PATH` and `LD_LIBRARY_PATH` environment variables to point to the correct directories containing the libzim library and header files respectively. For example: -On linux, you can install libzim from standard package manangement: -``` -$ sudo dnf install libzim-devel -``` - -or + ```bash + export PKG_CONFIG_PATH=/path/to/libzim/lib/pkgconfig:$PKG_CONFIG_PATH + export LD_LIBRARY_PATH=/path/to/libzim/lib:$LD_LIBRARY_PATH + ``` -``` -$ apt-get install libzim-dev -``` + Replace `/path/to/libzim` with the actual path to your extracted libzim directory. -You can also use prebuild binaries from https://download.openzim.org/release/libzim/. -In this case, you will have to set `PKG_CONFIG_PATH` and `LD_LIBRARY_PATH` to point to correctly directories. +**2. Install zim2waj:** +Once `libzim` is installed, install `zim2waj` using Cargo: -Then you can install `zim2waj` with: - -``` -$ cargo install --git https://github.com/jubako/zim2waj +```bash +cargo install --git https://github.com/jubako/zim2waj ``` -Running zim2waj ---------------- +## Usage -Simply run: +**Basic Conversion:** -``` -$ zim2waj --outfile +```bash +zim2waj --outfile ``` -For better performance, I advice you to increase the internal cluster cache of libzim to avoid some (a lot of) clusters uncompressions. +For optimal performance, increase the internal cluster cache of `libzim` to reduce cluster decompression overhead: -``` +```bash ZIM_CLUSTERCACHE=128 zim2waj --outfile ``` -Splitting content ------------------ +** Splitting Content:** + +To separate binary content into a separate pack file, use the `--split` option: + +```bash +zim2waj --outfile --split +``` + +This creates an additional file `.binary.jbkc`. The main `` will function correctly even without the binary pack, albeit without the binary assets. If you move the main Waj file, ensure the binary pack remains in the same directory. + Alternatively, use `jbk locate` (from the `jubako` crate, installable via `cargo install jubako`) to update the binary pack location within the main Waj file. + + +## Contributing + +Contributions are welcome! Please open an issue or submit a pull request. + +## Sponsoring -Contrarly to Zim archive, Waj archive can store binary content (image, video) in a separated file (pack) than main content. -To do so, pass the `--split` option to `zim2waj`. +I ([@mgautierfr](https://github.com/mgautierfr)) am a freelance developer. All jubako projects are created in my free time, which competes with my paid work. +If you want me to be able to spend more time on Jubako projects, please consider [sponsoring me](https://github.com/sponsors/jubako). +You can also donate on [liberapay](https://liberapay.com/jubako/donate) or [buy me a coffee](https://buymeacoffee.com/jubako). -It will create an extra file `.binary.jbkc`. You can serve only `` without the binary content and you will -have a working waj file (without image obviously). +## License -If you move `` be sure to keep the binary pack in the same directory. -Or use `jbk locate` (`$ cargo install jubako`) to update location of binary pack in ``. +This project is licensed under the MIT License - see the [LICENSE-MIT](LICENSE-MIT) file for details.