246 lines
7.2 KiB
Text
246 lines
7.2 KiB
Text
\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
|