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 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
* 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, Copying This Manual, 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 Copying This Manual, Index, Usage, 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