epubgrep/README.adoc

= epubgrep
:showtitle:
:toc: preamble
:project: epubgrep
:uri-base: https://schlomp.space/tastytea/{project}
:uri-branch-main: {uri-base}/src/branch/main

:uri-gcc: https://gcc.gnu.org/
:uri-clang: https://clang.llvm.org/
:uri-cmake: https://cmake.org/
:uri-catch: https://github.com/catchorg/Catch2
:uri-boost: https://www.boost.org/
:uri-gettext: https://www.gnu.org/software/gettext/
:uri-libarchive: https://www.libarchive.org/
:uri-fmt: https://github.com/fmtlib/fmt
:uri-asciidoc: http://asciidoc.org/
:uri-termcolor: https://termcolor.readthedocs.io/

:license: https://schlomp.space/tastytea/{project}/src/branch/main/LICENSE
:license-termcolor: https://schlomp.space/tastytea/{project}/src/branch/main/dist/termcolor/LICENSE

*{project}* is a search tool for EPUB e-books. It does not operate on lines, but
on whole files. All newlines will be replaced by spaces and HTML will be
stripped. This means you can search for text spanning multiple lines and don't
have to worry about HTML tags in the text.

{project} is licensed under the link:{license}[AGPL-3.0-only]. The bundled
link:{uri-termcolor}[Termcolor] is licensed under the
link:{license-termcolor}[BSD-3-Clause] license.

== Usage

[alt="Screenshot of epubgrep, showing the output of 2 book searches."]
image::{uri-base}/raw/branch/main/screenshot.png[]

See
https://schlomp.space/tastytea/{project}/src/branch/main/man/{project}.1.adoc[man
page] for more information.

== Install

[alt="Packaging status" link=https://repology.org/project/epubgrep/versions]
image::https://repology.org/badge/vertical-allrepos/epubgrep.svg[]

=== Gentoo

[source,shell]
--------------------------------------------------------------------------------
sudo eselect repository enable guru
echo 'app-text/epubgrep' | sudo tee -a /etc/portage/package.accept_keywords/epubgrep
sudo emaint sync -r guru
sudo emerge -a app-text/epubgrep
--------------------------------------------------------------------------------

=== Debian and Ubuntu

This repository works for Debian buster (10) and Ubuntu focal (20.04). It _may_
work for other versions, I have not tested it. It does not work for Ubuntu
bionic (18.04).

[source,shell]
--------------------------------------------------------------------------------
wget -O - https://tastytea.de/tastytea.asc | sudo apt-key add -
sudo add-apt-repository 'deb https://apt.schlomp.space/debian buster main'
sudo apt install epubgrep
--------------------------------------------------------------------------------

[TIP]
If you get the error message that `add-apt-repository` was not found, install
`software-properties-common`.

=== From source

==== Dependencies

* Tested OS: Linux
* C\++ compiler with C++17 support (tested: link:{uri-gcc}[GCC] 8/10,
  link:{uri-clang}[clang] 6/11)
* link:{uri-cmake}[CMake] (at least: 3.12)
* link:{uri-boost}[Boost] (tested: 1.75.0 / 1.65.0)
* link:{uri-gettext}[gettext] (tested: 0.21 / 0.19)
* link:{uri-libarchive}[libarchive] (tested: 3.5 / 3.2)
* link:{uri-fmt}[fmt] (tested: 7.0 / 4.0)
* link:{uri-asciidoc}[AsciiDoc] (tested: 9.0 / 8.6)
* link:{uri-termcolor}[Termcolor] (tested: 2.0) (If not found, the bundled
  version is used.)
* Optional
  ** Tests: link:{uri-catch}[Catch] (tested: 2.13 / 1.10)

===== Install dependencies in Debian or Ubuntu

Or distributions that are derived from Debian or Ubuntu. You will need at least
Debian buster (10) or Ubuntu focal (20.04), unless you install a newer version
of CMake.

[source,shell]
--------------------------------------------------------------------------------
sudo apt install build-essential cmake libboost-program-options-dev libboost-locale-dev libboost-regex-dev gettext libarchive-dev libfmt-dev asciidoc
--------------------------------------------------------------------------------

==== Get sourcecode

===== Release

Download the current release at link:{uri-base}/releases[schlomp.space].

===== Development version

[source,shell]
--------------------------------------------------------------------------------
git clone https://schlomp.space/tastytea/epubgrep.git
--------------------------------------------------------------------------------

==== Compile

In a terminal, go to the directory where you unpacked / cloned the source code
and then:

[source,shell]
--------------------------------------------------------------------------------
mkdir -p build && cd build
cmake ..
cmake --build . -- --jobs=$(nproc --ignore=1)
--------------------------------------------------------------------------------

To install, run `sudo make install`. To run the tests, run `cd tests &&
ctest`.

[TIP]
If you are using Debian or Ubuntu, or a distribution that is derived from these,
you can run `cpack -G DEB` in the build directory to generate a .deb-file. You
can then install it with `apt install ./epubgrep-*.deb`.

.CMake options:
* `-DCMAKE_BUILD_TYPE=Debug` for a debug build.
* `-DWITH_TESTS=YES` if you want to compile the tests.
* `-DXGETTEXT_CMD=String` The program to use instead of `xgettext`.
* `-DFALLBACK_BUNDLED=NO` if you don't want to fall back on bundled libraries.

include::{uri-base}/raw/branch/main/CONTRIBUTING.adoc[]