README.org

   1 <a href="https://melpa.org/#/kiwix"><img alt="MELPA"
   2 src="https://melpa.org/packages/kiwix-badge.svg"></a>
   3
   4 <a href="https://www.gnu.org/licenses/gpl-3.0"><img
   5 src="https://img.shields.io/badge/License-GPLv3-blue.svg" alt="License: GPL v3" /></a>
   6
   7 <a href="https://cla-assistant.io/stardiviner/kiwix.el"><img
   8 src="https://cla-assistant.io/readme/badge/stardiviner/kiwix.el" alt="CLA
   9 assistant" /></a>
  10
  11 * Intro
  12
  13 Searching offline Wikipedia through Kiwix.
  14
  15 [[kiwix.el Ivy async completion.png]]
  16
  17 [[kiwix.el with EWW.png]]
  18
  19 This =kiwix.el= supports query =kiwix-tools='s =kiwix-serve= server through URL API.
  20
  21 The =kiwix-serve= server can be started from command-line if you have =kiwix-tools=
  22 installed, or from Docker container [fn:1].
  23
  24 * License & Contribution
  25
  26 This kiwix.el is under GPLv3 license. If you want to contribute or Pull Request,
  27 you need to have signed FSF copyright paper. Here is the start
  28
  29 https://www.gnu.org/prep/maintain/maintain.html#Copyright-Papers
  30
  31 * Install
  32
  33 ** Install Kiwix
  34
  35 *** Docker
  36
  37 Reference this issue as background info: https://github.com/kiwix/kiwix-tools/issues/257
  38
  39 #+begin_src sh :eval no
  40 docker pull kiwix/kiwix-serve
  41 #+end_src
  42
  43 *** Flatpak
  44     :PROPERTIES:
  45     :URL:      https://wiki.kiwix.org/wiki/Flatpak
  46     :END:
  47
  48 #+begin_src org
  49 ,#+begin_src sh :dir /sudo::/tmp
  50 # Install Flatpak (on Debian/Ubuntu)
  51 sudo pacman -S flatpak
  52
  53 # Install Flathub (for the dependencies)
  54 flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
  55
  56 # Download the Kiwix Desktop Flatpak
  57 wget https://download.kiwix.org/release/kiwix-desktop/org.kiwix.desktop.2.0-beta2.flatpak
  58 ,#+end_src
  59
  60 ,#+begin_src sh :dir /tmp :eval no
  61 # Install Kiwix Desktop
  62 flatpak install org.kiwix.desktop.2.0-beta2.flatpak
  63 ,#+end_src
  64
  65 ,#+begin_src sh :eval no
  66 # Run Kiwix Desktop (but Kiwix should be available through your app launcher anyway)
  67 flatpak run org.kiwix.desktop
  68 ,#+end_src
  69 #+end_src
  70
  71 *** Download
  72
  73 - https://sourceforge.net/projects/kiwix
  74 - http://www.kiwix.org/wiki/Software
  75
  76 *** Linux
  77
  78 **** Arch
  79
  80 #+begin_src org
  81 ,#+begin_src sh :dir /sudo:: :results none
  82 aurman -S --noconfirm kiwix-bin
  83 ,#+end_src
  84 #+end_src
  85
  86 *** Web Browser
  87
  88 **** Firefox
  89
  90 https://addons.mozilla.org/en-US/firefox/addon/kiwix-offline/
  91
  92 **** Chrome
  93
  94 https://chrome.google.com/webstore/detail/kiwix/donaljnlmapmngakoipdmehbfcioahhk
  95
  96 ** GNU ELPA & MELPA
  97
  98 kiwix.el now is available on GNU ELPA & MELPA.
  99
 100 - https://elpa.gnu.org/packages/kiwix.html
 101 - https://melpa.org/#/kiwix
 102
 103 #+begin_src emacs-lisp :eval no
 104 (use-package kiwix
 105   :ensure t
 106   :after org
 107   :commands (kiwix-launch-server kiwix-at-point)
 108   :custom ((kiwix-server-use-docker t)
 109            (kiwix-server-port 8089)
 110            (kiwix-default-library "wikipedia_en_all_2016-02.zim"))
 111   :hook (org-load . org-kiwix-setup-link))
 112 #+end_src
 113
 114 * Setup kiwix-serve
 115
 116 If you use kiwix-serve Docker container, you can create an Systemd unit service
 117 to auto start Docker container. Here is the systemd unit config file:
 118
 119 ** Dockerize kiwix-tools (kiwix-serve, etc)
 120    :PROPERTIES:
 121    :URL:      https://hub.docker.com/r/kiwix/kiwix-serve
 122    :ISSUE:    https://github.com/kiwix/kiwix-tools/issues/257
 123    :Pull-Request: https://github.com/kiwix/kiwix-tools/pull/268
 124    :Attachments: screenshot_1.png screenshot_2.png
 125    :ID:       e82e194f-2cc8-45eb-a378-f8bd6d7c6b1a
 126    :END:
 127
 128 #+begin_src sh :async
 129 docker pull kiwix/kiwix-serve
 130 #+end_src
 131
 132 #+RESULTS[<2019-03-24 08:33:29> ace542940af6e465f90f0a3a8515e876fd267ad5]:
 133 #+begin_example
 134 Using default tag: latest
 135 latest: Pulling from kiwix/kiwix-serve
 136 8e402f1a9c57: Pulling fs layer
 137 7024865ce0e2: Pulling fs layer
 138 ad4c9cfc45dc: Pulling fs layer
 139 c4d62acdb073: Pulling fs layer
 140 c4d62acdb073: Waiting
 141 8e402f1a9c57: Verifying Checksum
 142 8e402f1a9c57: Download complete
 143 7024865ce0e2: Verifying Checksum
 144 7024865ce0e2: Download complete
 145 8e402f1a9c57: Pull complete
 146 7024865ce0e2: Pull complete
 147 c4d62acdb073: Verifying Checksum
 148 c4d62acdb073: Download complete
 149 ad4c9cfc45dc: Verifying Checksum
 150 ad4c9cfc45dc: Download complete
 151 ad4c9cfc45dc: Pull complete
 152 c4d62acdb073: Pull complete
 153 Digest: sha256:8837effa1a4fce750dc373d58b47063b368228331ccacb267c6ae7d3e311e66c
 154 Status: Downloaded newer image for kiwix/kiwix-serve:latest
 155 #+end_example
 156
 157 https://github.com/kiwix/kiwix-tools/blob/master/docker/server/Dockerfile
 158
 159 #+begin_src org
 160 ,#+begin_src dockerfile
 161 FROM alpine:latest
 162 LABEL maintainer Emmanuel Engelhart <kelson@kiwix.org>
 163
 164 # Install kiwix-serve
 165 WORKDIR /
 166 RUN apk add --no-cache curl bzip2
 167 RUN curl -kL https://download.kiwix.org/release/kiwix-tools/kiwix-tools_linux-x86_64-1.1.0.tar.gz | tar -xz && \
 168     mv kiwix-tools*/kiwix-serve /usr/local/bin && \
 169     rm -r kiwix-tools*
 170
 171 # Configure kiwix-serve
 172 VOLUME /data
 173 ENV PORT 80
 174 EXPOSE $PORT
 175
 176 # Run kiwix-serve
 177 WORKDIR /data
 178 ENTRYPOINT ["/usr/local/bin/kiwix-serve", "--port", "$PORT"]
 179 ,#+end_src
 180 #+end_src
 181
 182 How to run?
 183
 184 Given =wikipedia.zim= ([[#ZIM][Zim database files]]) resides in =/tmp/zim/=, execute the
 185 following command:
 186
 187 #+begin_src sh :eval no
 188 # if you don't have libraries index file "library.xml"
 189 docker container run -d --name kiwix-serve -v /tmp/zim:/data -p 8080:80 kiwix/kiwix-serve wikipedia.zim
 190 # if you have libraries index file "library.xml"
 191 docker container run -d --name kiwix-serve -v /tmp/zim:/data -p 8080:80 kiwix/kiwix-serve --library library.xml
 192 #+end_src
 193
 194 *NOTE*: You can generate the libraries index file "library.xml" with following command:
 195
 196 #+begin_src sh
 197 cd ~/.www.kiwix.org/kiwix/nsz6b6tr.default/data/library/
 198
 199 for zim in $(ls *.zim); do
 200   kiwix-manage library.xml add $zim
 201 done
 202 #+end_src
 203
 204 *NOTE*: Using the libraries index file method, you can have all libraries served
 205 in Docker container instead of just one library.
 206
 207 If you put ZIM files in other places not =/tmp/zim/=, you can use follow my command:
 208
 209 #+NAME: create kiwix-serve container with custom port
 210 #+begin_src sh :session "*kiwix-serve*"
 211 docker container run -d \
 212        --name kiwix-serve \
 213        -v ~/.www.kiwix.org/kiwix/nsz6b6tr.default/data/library:/data \
 214        -p 8089:80 \
 215        kiwix/kiwix-serve wikipedia_zh_all_2015-11.zim
 216 #+end_src
 217
 218 Visit http://localhost:8080 or http://localhost:8089 (if you exposed different
 219 port).
 220
 221 For easy launch the docker run command, you can add command alias in shell profile:
 222
 223 #+begin_src shell :eval no
 224 alias kiwix-docker-wikipedia_zh_all="docker container run --name kiwix-serve -d -v ~/.www.kiwix.org/kiwix/nsz6b6tr.default/data/library:/data -p 8089:80 kiwix/kiwix-serve wikipedia_zh_all_2015-11.zim"
 225 alias kiwix-docker-wikipedia="docker container run --name kiwix-serve -d -v ~/.www.kiwix.org/kiwix/nsz6b6tr.default/data/library:/data -p 8089:80 kiwix/kiwix-serve wikipedia.zim"
 226 #+end_src
 227
 228 *** create a systemd unit for kiwix-serve Docker service
 229
 230 #+begin_src org
 231 ,#+begin_src systemd :tangle "~/.config/systemd/user/kiwix-serve.timer"
 232 [Unit]
 233 Description=Start kiwx-serve Docker container server at system startup after 5 minutes
 234
 235 [Timer]
 236 OnBootSec=2min
 237 Unit=kiwix-serve.service
 238
 239 [Install]
 240 WantedBy=default.target
 241 ,#+end_src
 242
 243 ,#+begin_src systemd :tangle "~/.config/systemd/user/kiwix-serve.service"
 244 [Unit]
 245 Description=kiwix-serve Docker server
 246 After=docker.service
 247
 248 [Service]
 249 Type=simple
 250 ExecStart=/usr/bin/docker container start -i kiwix-serve
 251 ExecStop=/usr/bin/docker container stop kiwix-serve
 252
 253 [Install]
 254 WantedBy=default.target
 255 ,#+end_src
 256 #+end_src
 257
 258 *NOTE*: You need to use option =-i= for =docker container start= command to avoid
 259 systemd auto exit and stop =kiwix-serve= container.
 260
 261 #+begin_src sh :results output
 262 systemctl --user enable kiwix-serve.timer
 263 systemctl --user status kiwix-serve.timer | cat
 264 #+end_src
 265
 266 #+RESULTS[<2019-03-24 11:45:40> 6470584177f091e79067f9fd96a97c340e00a41f]:
 267 : ● kiwix-serve.timer - Start kiwx-serve Docker container server at system startup after 5 minutes
 268 :    Loaded: loaded (/home/stardiviner/.config/systemd/user/kiwix-serve.timer; enabled; vendor preset: enabled)
 269 :    Active: inactive (dead)
 270 :   Trigger: n/a
 271
 272 #+begin_src sh
 273 systemctl --user start kiwix-serve.service
 274 #+end_src
 275
 276 #+begin_src sh
 277 systemctl --user status kiwix-serve.service | cat
 278 #+end_src
 279
 280 #+RESULTS[<2019-03-24 12:00:49> 10a33f8521fa2c72e8c1107559e1fb18b58d7da2]:
 281 : ● kiwix-serve.service - kiwix-serve Docker server
 282 :    Loaded: loaded (/home/stardiviner/.config/systemd/user/kiwix-serve.service; disabled; vendor preset: enabled)
 283 :    Active: active (running) since Sun 2019-03-24 12:00:14 CST; 34s ago
 284 :  Main PID: 2587 (docker)
 285 :    CGroup: /user.slice/user-1000.slice/user@1000.service/kiwix-serve.service
 286 :            └─2587 /usr/bin/docker container start -i kiwix-serve
 287 :
 288 : Mar 24 12:00:14 dark systemd[694]: Started kiwix-serve Docker server.
 289
 290 *NOTE*: Because =kiwix-serve.service= use command =docker container start
 291 kiwix-serve=, so that the container =kiwix-serve= must already been created by
 292 [[create kiwix-serve container with custom port][this command]], you can check whether the container is created:
 293
 294 #+begin_src sh :results output
 295 docker container ls | head -n 1
 296 docker container ls --all | grep "kiwix-serve" | cat
 297 #+end_src
 298
 299 #+RESULTS[<2019-03-24 11:50:36> e28015e8e78015623bd53ae596015949dc80c549]:
 300 : CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
 301 : b47533ecd7f6        kiwix/kiwix-serve               "/usr/local/bin/kiwi…"   3 hours ago         Exited (137) 2 minutes ago                                      kiwix-serve
 302 : e2f201e655ac        kiwix/kiwix-serve               "/usr/local/bin/kiwi…"   3 hours ago         Created                                                         distracted_hofstadter
 303
 304 * Config
 305
 306 ** use-package
 307
 308 #+begin_src emacs-lisp
 309 (use-package kiwix
 310   :ensure t
 311   :after org
 312   :custom ((kiwix-server-use-docker t)
 313            (kiwix-server-port 8089)
 314            (kiwix-default-library "wikipedia_en_all_2016-02.zim") ; "wikipedia_zh_all_2015-11.zim"
 315            (kiwix-default-browser-function 'eww))
 316   :commands (kiwix-launch-server kiwix-at-point)
 317   :init (require 'org-kiwix)
 318   :config (add-hook 'org-load-hook #'org-kiwix-setup-link))
 319 #+end_src
 320
 321 * Usage
 322
 323 ** Use in Emacs
 324
 325 =[M-x kiwix-at-point]=
 326
 327 ** Org Mode integration
 328
 329 #+begin_src emacs-lisp
 330 (require 'org-kiwix)
 331 #+end_src
 332
 333 =[C-c C-l]= to insert link.
 334
 335 The link format is like this:
 336
 337 #+BEGIN_EXAMPLE
 338 [[wikipedia:(library):search][description]]
 339 #+END_EXAMPLE
 340
 341 The =(library)= can be =wikipedia_en=, =wikipedia_zh=, =wiktionary_en=, or =en=, =zh= etc.
 342
 343 ** EWW integration
 344
 345 Set following option in your config to use EWW in Emacs as your default _for
 346 Kiwix only_.
 347
 348 #+begin_src emacs-lisp
 349 (setq kiwix-default-browser-function 'eww-browse-url)
 350 #+end_src
 351
 352 #+RESULTS[<2019-10-15 18:32:09> 3b9749599d792fb0ea5cd3566095ae16f1fc7f30]:
 353 : eww-browse-url
 354
 355 [[kiwix.el with EWW.png]]
 356
 357 ** Async search completion keywords candidates
 358
 359 [[kiwix.el Ivy async completion.png]]
 360
 361 * Changelog
 362
 363 ** DONE implemented async instantly input suggestion completion in Ivy
 364    CLOSED: [2019-10-08 Tue 22:07]
 365    :LOGBOOK:
 366    - State "DONE"       from              [2019-10-08 Tue 22:07]
 367    :END:
 368
 369 This feature is very subtle :)
 370
 371 * Test
 372
 373 - [[wikipedia:Operations%20Research][Operations Research]] :: query contains space.
 374 - [[wikipedia:Operations%20research][Operations research]] :: the second word is not capitalized.
 375 - [[wikipedia:%E4%B8%AD%E5%9B%BD][中国]] :: non-english query
 376 - [[wikipedia:meta-circular%20interpreter][meta-circular interpreter]] :: only capitalize the first word.
 377
 378 * How does this extension work?
 379
 380 ** integrate with Emacs
 381
 382 *** core
 383
 384 I found Kiwix will return a URL like this:
 385
 386 #+BEGIN_EXAMPLE
 387 http://127.0.0.1:8000/wikinews_en_all_2015-11/A/Big_Linux_Beta_3_released.html
 388 ____________________  _____________________  __  _____________________________
 389
 390 < server address >    < library >                <one of the returned results>
 391 #+END_EXAMPLE
 392
 393 *** steps
 394
 395 1. auto start ~kiwix-serve~ HTTP server.
 396 2. query/search on kiwix server.
 397    1. open kiwix server index page to input to search. (But this is slow, waste time)
 398    2. use http language binding library to query on kiwix HTTP server.
 399       1. select library in library list page.
 400       2. after load a library, simulate type query string in the search input
 401          box, the submit to search.
 402       3. return the result page HTML or page URL.
 403       4. view the result with page URL or page HTML with Emacs browser.
 404
 405 *** auto start kiwix HTTP server
 406
 407 Here is a simple script, you can put it in Linux "*auto-start*".
 408
 409 #+begin_src org
 410 ,#+BEGIN_SRC sh :tangle "~/scripts/kiwix-server.sh"
 411 #!/usr/bin/env sh
 412
 413 /usr/lib/kiwix/bin/kiwix-serve --library --port=8000 --daemon ~/.www.kiwix.org/kiwix/8ip89lik.default/data/library/library.xml
 414 ,#+END_SRC
 415 #+end_src
 416
 417 *** search
 418
 419 1. kiwix-search command -> return a list of results.
 420
 421    #+begin_src org
 422    ,#+BEGIN_SRC sh
 423    /usr/lib/kiwix/bin/kiwix-search ~/.www.kiwix.org/kiwix/8ip89lik.default/data/index/wikinews_en_all_2015-11.zim.idx linux
 424    ,#+END_SRC
 425    #+end_src
 426
 427 2. use one element of list as part of the URL.
 428
 429    http://127.0.0.1:8000/wikinews_en_all_2015-11/A/Big_Linux_Beta_3_released.html
 430
 431    #+begin_src org
 432    ,#+BEGIN_SRC emacs-lisp
 433    (browse-url (concat "http://127.0.0.1:8000/" "LIBRARY" "/A/" "RESULT"))
 434    ,#+END_SRC
 435    #+end_src
 436
 437 *** more advanced?
 438
 439 If you want more advanced functions, you can use communicate kiwix HTTP server
 440 with RESTful API.
 441
 442 - I don't know what Emacs library to use.
 443 - Or you can use other language to do this, like Ruby or Python etc.
 444
 445 * Footnotes
 446
 447 [fn:1] https://github.com/kiwix/kiwix-tools/issues/257