\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 Willemsen

@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 Willemsen
@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
* 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.

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

@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

@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:

@table @samp
@item --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 table

@node Customization, Copying This Manual, 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 Copying This Manual, Index, Customization, 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
@include fdl.texi

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

@printindex cp

@bye

@c clark.texi ends here