Tom Willemse
a6e2d9b620
Since texinfo files can start to look like a big jumble of letters these control characters help in keeping visual distinction between nodes and make navigating the file in Emacs easier by splitting it up in pages.
330 lines
9.5 KiB
Text
330 lines
9.5 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 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
|