# Copyright (C) 2013 Tom Willemsen <tom at ryuslash dot org>
#
# This file is part of CLark
#
# CLark is free software: you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# CLark is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with CLark. If not, see <http://www.gnu.org/licenses/>.

#+TITLE: Conkeror
#+STARTUP: showall

[[http://conkeror.org][Conkeror]] is an awesome xulrunner-based web browser with Emacs-like
functionality. It is easily extended and if you like Emacs, a
pleasure to use. It does not seem to have great bookmark management
capabilities, unless you use firefox's bookmarking tools. This is one
of the reasons CLark was written.

* Set-up

  To use the CLark Conkeror module you need to put its location in
  Conkeror's load path, afterwards you should load or require it. So
  in your ~.conkerorrc~ you should put:
  #+BEGIN_EXAMPLE
    load_paths.push("file:///path/to/clark/js/");
    require("clark");
  #+END_EXAMPLE

  If you don't have the CLark executable in your path you should set
  the =clark_program= user variable to the location of the CLark
  executable:
  #+BEGIN_EXAMPLE
    clark_program = "/path/to/clark";
  #+END_EXAMPLE

  Once that is done you kan either bind the available functions to
  the keys you like, or you could bind =clark_keymap= to a key, for
  example:
  #+BEGIN_EXAMPLE
    define_key(content_buffer_normal_keymap, "b", clark_keymap);
  #+END_EXAMPLE

  If you would like to see whether or not you've bookmarked the
  current URL, you could add the =clark_bookmarked_widget= to your
  Conkeror mode-line:
  #+BEGIN_EXAMPLE
    add_hook("mode_line_hook", mode_line_adder(clark_bookmarked_widget), true);
  #+END_EXAMPLE

  If you don't like the way the =clark_bookmarked_widget= shows you
  whether or not the current URL has been bookmarked, you can
  customize these by setting either or both of the variables
  =clark_bookmarked_string= and =clark_not_bookmarked_string=.

* Usage

  The Conkeror module is written to mirror the functionality found in
  CLark, here's a list of its commands:

  - =clark-exists-p= :: Prints an indication of whether or not the
                      current URL has been bookmarked. Uses the same
                      command the =clark_bookmarked_widget= does, only
                      requires the user to explicitly call it.

  - =clark-add= :: Add the curren URL to CLark. Asks for a title,
                 description and any tags you wish to assign it.

  - =clark-add-link= :: Does the same thing =clark-add= does, except it
                      also asks which link found on the current page
                      to bookmark, instead of using the current URL.

  - =clark-edit= :: Edit the current URL's data. Asks for a name and a
                  description, if either one is left empty, it is not
                  sent to CLark and thus not changed.

  - =clark-find-url= :: Calls =find-url= with completions gathered from
                      CLark. Uses the =search= command, so any text
                      typed into the minibuffer gets matched as a
                      substring of a bookmark's title, or a tag.

  - =clark-find-url-new-buffer= :: Does thee same thing =clark-find-url=
       does, except it opens the URL in a new buffer, instead of the
       current buffer.

  - =clark-remove= :: Removes the current URL from CLark.

  - =clark-set-tags= :: Replace or remove the tags for the current url's
                      bookmark. If any tags are given they replace the
                      bookmark's old tags, if the field is left empty,
                      all tags are removed.

  All of these are included in the =clark_keymap=.