#+title: archwiki.el
#+author: Lucien Cartier-Tilet
#+email: lucien@phundrak.com
* Introduction
~archwiki.el~ is a utility for navigating the Arch Wiki from Emacs. It
is strongly advised for users of ArchLinux and ArchLinux derivates to
install the ~arch-wiki-docs~ package[fn:1].

This package is geared towards ArchLinux in particular, but any Linux
distribution that has a local copy of the Arch Wiki can be compatible
with this package.

* Table of Contents                                                :TOC_2_gh:noexport:
- [[#introduction][Introduction]]
- [[#installation][Installation]]
- [[#customizing][Customizing]]
- [[#contributing][Contributing]]
- [[#license][License]]
- [[#footnotes][Footnotes]]

* Installation
As mentioned above, you will absolutely need a local copy of the Arch
Wiki available to Emacs. You can install the ~arch-wiki-docs~ package if
you are running ArchLinux or a derivate Linux distribution (ArcoLinux,
ArchCraft, Manjaro,…), or refer to the readme of [[https://github.com/lahwaacz/arch-wiki-docs][its repository]].

A couple of options are available for installing ~archwiki.el~. The
first one is to clone the repository in your ~load-path~ and add the
following to your ~.emacs~ or your ~init.el~:
#+begin_src emacs-lisp
  (require 'archwiki)
#+end_src

In my case, I prefer using ~use-package~ with ~straight~:
#+begin_src emacs-lisp
  (use-package eshell-info-banner
    :ensure t
    :defer t
    :straight (archwiki :type git
                        :host nil
                        :repo "https://labs.phundrak.com/phundrak/archwiki.el"))
#+end_src

I personally also added ~:build t~ in the straight recipe to ensure
Emacs compiles my package, both to ~.elc~ and ~.eln~ files (I am on Emacs
28.0, ~feature/native-comp~ got merged into ~master~!)

There is probably a similar way to install it with pure ~straight.el~ or
~quelpa~, but I’m not knowledgable enough for that, feel free to create
a PR to add some more installation instructions!

There is currently no plans of making this package available on MELPA
or non-gnu elpa.

* Customizing
A couple of variables can be edited by the user in order to configure
~archwiki.el~:
- ~archwiki-local-path~ :: Where your local copy of the Arch Wiki is located.

  Default value: ~"/usr/share/doc/arch-wiki/html/en/"~
- ~archwiki-use-eww~ :: If non ~nil~, use the /Emacs Web Wowser/ for viewing
  the Arch Wiki pages, otherwise use an external program.

  Default value: ~t~
- ~archwiki-external-browser~ :: External program to use to view the
  Arch Wiki pages. If the value is ~nil~ or an empty string, or if the
  executable cannot be found by Emacs, use ~xdg-open~, otherwise use
  this program. This can be a path to an executable or the name of an
  executable available on your ~$PATH~.

  Default value: ~""~

* Contributing
See [[file:CONTRIBUTING.org]].

* License
~archwiki.el~ is available under the GNU GPL-3.0 license. You can find
the full text in [[file:LICENSE.md][LICENSE.md]].

* Footnotes

[fn:1] [[https://archlinux.org/packages/community/any/arch-wiki-docs/]]