clark/doc/clark.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename clark.info
@settitle CLark User Manual
@c %**end of header
@copying
The user manual for CLark.

Copyright @copyright{} 2013  Tom Willemse

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.

A copy of the license is also available from the Free Software
Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}.

@end quotation

The document was typeset with
@uref{http://www.texinfo.org/, GNU Texinfo}.

@end copying

@titlepage
@title CLark User Manual
@subtitle The user manual for CLark
@author Tom Willemse
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@dircategory Individual utilities
@direntry
* CLark: (clark).     Keeps bookmarks.
@end direntry

@c Output the table of the contents at the beginning.
@contents


@ifnottex
@node Top, Usage, (dir), (dir)
@top CLark User Manual

@insertcopying
@end ifnottex

@c Generate the nodes for this menu with `C-c C-u C-m'.
@menu
* Usage::                       How to use CLark
* Customization::               Customizing CLark
* Interaction::                 Interacting with other programs.
* Copying This Manual::
* Index::

@detailmenu
 --- The Detailed Node Listing ---

How to use

* Querying::                    Getting bookmarks from the database.
* Management::                  Maintaining bookmarks in the database.
* Miscellaneous::               Other things that can be done.

Interacting with other programs

* Conkeror::                    Interacting with the Conkeror web browser

Copying This Manual

* GNU Free Documentation License::  License for copying this manual.

@end detailmenu
@end menu


@c Update all node entries with `C-c C-u C-n'.
@c Insert new nodes with `C-c C-c n'.
@node Usage, Customization, Top, Top
@chapter How to use

For the moment CLark is a simple program, it has only a few functions.

@menu
* Querying::                    Getting bookmarks from the database.
* Management::                  Maintaining bookmarks in the database.
* Miscellaneous::               Other things that can be done.
@end menu


@node Querying, Management, Usage, Usage
@section Getting bookmarks from the database.

In order to view a list of all your bookmarks you can use:

@example
clark
@end example

@noindent
This will show the list of all stored bookmarks, showing the URL, name
and description. This list is unsorted and unpaged. There are also a
few other things we can ask CLark to do:

@deffn Command exists URL
Check the database to see if @var{url} can be found. Outputs
@samp{yes} if @var{url} was found in the database, or @samp{no} when
it was not.
@end deffn

@deffn Command search STR
Look through the database for any bookmarks that have @var{str}
anywhere in their name, or have a tag @var{str}. Outputs the same list
as when no commands are given, but filtered by either of these
conditions.
@end deffn

@deffn Command random [TAG]
Look through the database for a random bookmark. If @var{tag} is
specified, limit the results to bookmarks having the given tag. Simply
prints the url of the selected bookmark.
@end deffn


@node Management, Miscellaneous, Querying, Usage
@section Maintaining bookmarks in the database.

CLark has a few commands that may be used to manage bookmarks in the
database.

@deffn Command add URL NAME DESCRIPTION [TAGS...]
Adds @var{url} to the database with @var{name} and @var{description}.
Also adds references between @var{url} and any @var{tags} that were
specified. If @var{tags} is not passed to this command, no references
are made.

Any tags found in @var{tags}, but not yet present in the database get
added.
@end deffn

@deffn Command edit URL [--name NAME] [--description DESCRIPTION]
Edits @var{url} replacing the bookmark's name if @var{name} is
specified and replacing the bookmark's description if
@var{description} is specified. Either option, or both, may be
specified.
@end deffn

@deffn Command remove URL
Removes the bookmark for @var{url} from the database, also deleting
any references to any tags it has, but not deleting any tags from the
database.
@end deffn

@deffn Command set-tags URL [TAGS...]
Replace @var{url}'s tags with @var{tags}. @var{tags} may be omitted,
in which case all the tags for @var{url} are removed.
@end deffn

@deffn Command remove-tags URL [TAGS...]
Remove @var{tags} from @var{url}'s tag list. If @var{tags} is omitted,
remove all tags from @var{url}'s tag list.
@end deffn


@node Miscellaneous,  , Management, Usage
@section Other things that can be done

There are a few commands that help you to work with, or interact with
through other programs, CLark.

@deffn Command help [COMMAND]
Provides help. Normally outputs a help message giving a short
description of how CLark works, but when @var{command} is specified it
provides help for that command.
@end deffn

@deffn Command version
Shows the version of CLark.
@end deffn

There is also one command-line switch. Switches can be used with
either @samp{-} or @samp{--}:

@deffn Switch script
Causes the output of some commands to become more geared towards other
programs, not using newlines and indentation but instead using the
unit separator (@code{^_}) and record separator (@code{^^})
characters. This is to make it easy for other programs to parse the
data sent to them.

The commands currently affected by this are @samp{search} and the
default behavior when no commands are passed to CLark.
@end deffn


@node Customization, Interaction, Usage, Top
@chapter Customizing CLark

During start-up CLark looks for a file named @file{rc.lisp} either int
@code{@var{xdg_config_dir}/clark} or in
@code{@var{home}/.config/clark}. If it finds one it loads it. This
allows for customization to happen.

At the moment CLark offers very little customization. The only thing
that can be done at the moment is write your own commands. For
example, to easily show all your ``to read'' bookmarks, you could add
the following to your @file{rc.lisp}:

@lisp
(defcommand toread ()
  "Show bookmarks to read."
  "Usage: clark toread

Show all bookmarks that I should still read."
  (call-command search "toread"))
@end lisp

@noindent
assuming that you tag them with ``toread''. The syntax is fairly
simple, if you're familiar with Lisp:

@deffn Macro defcommand NAME ARGS SHORT-DOC LONG-DOC BODY...
Defines a command @var{name}, which is callable from the command line.

@var{args} is a lambda-list like the ones found in regular lisp
@code{defun} calls. It gets pasted into a @code{defun}, so technically
it supports anything @code{defun} does, but @code{&keys} arguments are
not practically usable at the moment.

The @var{short-doc} gets used as the command's docstring and is the
short message you will see in the output of the general @samp{help}
command.

The @var{long-doc} is used to generate the @samp{help <command>} help
message, it does not yet automatically print any usage information, it
is your responsibility to provide this in this string.

@var{body} is the body of the command, which is just like a regular
Lisp function. It has access to the arguments as defined in @var{args}
and anything any regular Lisp function does.
@end deffn


@node Interaction, Copying This Manual, Customization, Top
@chapter Interacting with other programs

CLark is meant to interact with other tools. Most of the time, using
the command-line to keep track of your bookmarks won't be very useful,
as copying an URL, pasting it in your terminal, copying the title,
pasting it in your terminal, and so on, take long and gets annoying
very fast.

@menu
* Conkeror::                    Interacting with the Conkeror web browser
@end menu


@node Conkeror,  , Interaction, Interaction
@section Interacting with the Conkeror web browser

Conkeror is a web browser that is based on the idea of Emacs. It is
very customizable. CLark has a module to work with this browser, it
offers most commands available on the command line. To use it you
should first add it to your load path and then load it:

@example
load_paths.push("file:///path/to/clark/js/");
require("clark");
@end example

After this you may wish to bind the clark keymap to an easy to use
key, like:

@example
define_key(content_buffer_normal_keymap, "b", clark_keymap);
@end example

You may even wish to show whether or not the current url has been
saved or not:

@example
add_hook("mode-line-hook", mode_line_adder(clark_bookmarked_widget), true);
@end example

The conkeror module only offers a little customization at the moment:

@defopt clark_program
In case you haven't installed CLark in your @var{path}, you can
specify its real location.
@end defopt

@defopt clark_bookmarked_string
What to show in the minibuffer when the current URL has been
bookmarked with CLark. Default is @samp{+}.
@end defopt

@defopt clark_not_bookmarked_string
What to show in the minibuffer when the current URL has not been
bookmarked with CLark. Default is @samp{-}.
@end defopt


@node Copying This Manual, Index, Interaction, Top
@appendix Copying This Manual

@menu
* GNU Free Documentation License::  License for copying this manual.
@end menu


@c Get fdl.texi from http://www.gnu.org/licenses/fdl.html
@node GNU Free Documentation License,  , Copying This Manual, Copying This Manual
@appendixsec GNU Free Documentation License
@include fdl.texi


@node Index,  , Copying This Manual, Top
@unnumbered Index

@printindex cp

@bye

@c clark.texi ends here