Provided by: xara-gtk_1.0.31build1_amd64 bug

NAME

       xara - GTK2 interface for the above

SYNOPSIS

   Graphical interface (GTK2):
       xara

       The  graphical  interface  allows  the user to input queries and browse the results.  Menu
       options are provided for installing and removing the selected packages using apt-get.  The
       packages the user is interested in may be bookmarked.

       Command-line interface (GTK2): A command-line interface, ara(1), is provided by the Debian
       package ara.

   Query syntax
       See the EXAMPLES section for a quick introduction ; xara  has  some  built-in  help.   The
       syntax is described in detail below.

DESCRIPTION

       ara and xara allow the user to search the Debian software package database (which includes
       installed and uninstalled packages) using powerful queries made of boolean combinations of
       regular expressions acting on fields given by patterns.

       For example, the query section=utils & depends:(gtk or tk8 or xlibs or kde or gnome or qt)
       & debian & package will  display  packages  in  the  section  utils  that  have  graphical
       interfaces  (because  they  depend  on  graphical  toolkits  or  X11 libraries), and whose
       description contains the words debian and package.

RATIONALE

       Debian users can easily install software with the commands  dselect  or  apt-get  install.
       They  can  choose  (on  Debian 3.1 unstable) from over 30,000 packages.  Finding the right
       package can be quite difficult.  Although packages  are  categorized  in  crude  sections,
       there are still too many packages and reading all descriptions is out of the question.

       The  database  files  are  huge  and their mail-like syntax makes them hard to search with
       line-oriented  tools  like  grep.   There  exist  commands  such  as  dpkg-iasearch(1)  or
       dpkg-dctrl(1) but their capabilities are limited.  Graphical package management tools such
       as aptitude or synaptic have search capabilities.  Although ara can call apt to install or
       remove  packages, its orientation is that of a powerful search tool.  Indeed, the name ara
       comes from the imperative form of the Turkish verb aramak which means "to search".

THE DEBIAN PACKAGE DATABASE

       The database of Debian packages is a huge  text  file  at  /var/lib/dpkg/available  (or  a
       collection  of  text  files under /var/lib/apt/lists/).  These files are in a mailbox-like
       format, and a typical entry looks like this:

       Priority: required
       Section: base
       Installed-Size: 460
       Origin: debian
       Maintainer: Dpkg Development <debian-dpkg@lists.debian.org>
       Bugs: debbugs://bugs.debian.org
       Architecture: i386
       Source: dpkg
       Version: 1.10.24
       Replaces: dpkg (<< 1.10.3)
       Depends: libc6 (>= 2.3.2.ds1-4), ....
       Filename: pool/main/d/dpkg/dselect_1.10.24_i386.deb
       Size: 119586
       MD5sum: c740f7f68dab08badf4f60b51a33500a
       Description: a user tool to manage Debian packages
        dselect is the primary user interface for installing, removing and
        managing Debian packages. It is a front-end to dpkg.

       Each package is thus described by a set of fields (like Package, Description, Version...).

QUERY SYNTAX AND SEMANTICS

       Here we describe the query syntax in some detail.  As of version 1.0, ara introduces  new,
       simplified  syntax which is quite traditional and should be familiar to anyone having used
       search engines.  Search terms are simply combined with AND, OR and NOT boolean  operators.
       Having  a  look  at  the  EXAMPLES  section at the end of this manual should provide you a
       starting point.

       Consider  the  set  D   of   Debian   package   descriptions   contained   in   the   file
       /var/lib/dpkg/available  (or  in  files under /var/lib/apt/lists/).  Each description is a
       set of couples of the form (f,v) where f and v are strings: f is the  name  of  the  field
       (namely,  Package, Description, Filename, Depends, etc.); v is its value.  Thus D is a set
       of set of couples, forming the universe.   Queries  select  subsets  of  the  universe  D.
       Output  options  select  which fields of the selected part of the universe to display, and
       how to display them.

   Queries
       A query is a boolean combination of atomic expressions.  An atomic  expression  selects  a
       subset  of the set D of descriptions.  I call this set the meaning of the expression; if e
       denotes an atomic expression, its meaning is denoted by [e].  The  meaning  of  a  boolean
       combination  of  atomic  expressions is just the boolean combination of the meaning of its
       constituents.  In other words, if e1 and e2 are atomic expressions, then  e1  &  e2  is  a
       query,  whose meaning is the intersection of the meanings of e1 and e2; and the meaning of
       e1 | e2 is the union of the meanings of e1 and e2.

   Atomic expressions
       Atomic expressions can  be  of  the  forms  pattern,  /regexp/,  quoted_string,  fieldspec
       operator1 string, or fieldspec operator2 regexp.

   Boolean operators and constants
       e1 & e2 (also e1 AND e2, e1 and e2)
              This  is  logical conjunction (set intersection).  Returns the intersection of [e1]
              and [e2], i.e. packages satisfying both e1 and e2.

       e1 | e2 (also e1 OR e2, e1 or e2)
              This is logical disjunction (set union).  Union of [e1]  and  [e2],  i.e.  packages
              satisfying e1, e2 or both.

       !e1 (also NOT e1, not e1)
              This  is logical negation (set complementation).  Complement of [e1], i.e. packages
              not satisfying e1.

              Please note that ~ stands for the current default field specifier  and  is  not  an
              alias for the complementation operator.

       true (also all)
              The set of all descriptions, i.e. all packages.

       false (also none)
              The empty set, i.e. no packages.

   Field specifiers
       A field specifier fieldspec is a comma-separated list of field patterns.

       Field  patterns are like simple shell patterns and they may contain star characters (which
       stand for anything) or question marks (which stand for any single  character).   They  are
       case-insensitive.  They specify a set of fields.

       For example description and Description specify the set of fields { Description }, whereas
       de* specifies { Description, Depends }.

       The special specifier ~ denotes the current default specifier (see below).

   Current fields specifiers and simplified atomic expressions
       The need to repeat the field specifier can make the above syntax cumbersome.  That is  why
       there  is  a  current  field  specifier.   The  current  field  specified  is, by default,
       Description,Package.  Simplified atomic expressions are simply words or  simplified  shell
       expressions  (which  do not need to be enclosed in double quotes) and they are searched in
       fields in the current field specifier.  They can be made of letters, digits,  underscores,
       dashes and periods.  They may contain stars of question marks which are interpreted as for
       field patterns (i.e., as simplified shell expressions).  If double quotes are used,  other
       characters and spaces can be used.

       The  default  field  specifier  in  a  query  query  can be changed to fieldspec by simply
       prefixing the query with fieldspec:.  This gives fieldspec:query.   However  if  query  is
       complex   (i.e.,  contains  binary  boolean  operators)  you  need  to  enclose  query  in
       parentheses, as in fieldspec:(query1 or query2).

   String literals
       String literals can be given with or without double quotes;  without  double  quotes,  the
       syntax  is  as  for  C  identifiers, except that you can use dashes, you must start with a
       latin letter ([a-zA-Z]) and you  can  continue  with  Latin  letters,  decimal  digits  or
       underscore  ([a-zA-Z0-9_]).   Inside  double  quotes,  all  characters are allowed, except
       double quotes, which must be preceded by a backslash.

   Variables
       Results of queries can be stored in variables, which may be recalled  later.   This  isn't
       very useful in batch mode but is useful in interactive and graphical modes.

       Variable  names start with a dollar and follow usual conventions for variables, i.e., they
       can be any mix of alphanumeric characters and symbols such as underscore, dash, etc.

       Variable names are case-sensitive so that $Installed and $installed are different.

       To assign the result of a query (which is a set of packages) a  variable  named  $variable
       just  execute  the  query  $variable := query.  You may then recall this particular set by
       simply writing $variable.

       Example: $installed := status:(installed & !not-installed)

   Operators
       Hierarchical comparison operators can be negated by changing the direction  of  the  angle
       brackets  and  adding or removing an equality sign at end (<= becomes >).  Other operators
       are negated as follows: = becomes != and =~ becomes !~.

       fieldspec=string
              Atomic expression selecting packages having a field in fieldspec having a  value  a
              value exactly equal to string.

       fieldspec<string (fieldspec<=string, fieldspec>string, fieldspec>=string)
              Atomic  expression  selecting  packages  having a field in fieldspec whose value is
              strictly less than string.  The order used is the Debian  versioning  order.   This
              order  is  compatible  with  the  natural order on integers and with Debian version
              numbers.  When comparing strings not containing special  characters,  letters  sort
              before numbers, as opposed to lexicographic ASCII order we are used to.  This means
              that hexadecimal numbers (such as MD5 sums) will not have their usual order.

              Note that string must be on the right side of the operator (i.e., you cannot  write
              1000 < Size).

       fieldspec=~/expression/ (also fieldspec:/expression/)
              Selects  descriptions  whose  field named fieldspec exists and whose value matches,
              case-sensitively, the regular expression expression.

       fieldspec=~/expression/i (also fieldspec:/expression/i)
              Same as above, but the regular expression is case-insensitive.

       fieldspec=~/expression/w (also fieldspec:/expression/w)
              Same as above, but the regular expression is case-sensitive  and  matches  only  at
              word  boundaries.   Note  that  letters-to-digit or digit-to-letter transitions are
              considered to be word boundaries.

       fieldspec=~/expression/iw (also fieldspec:/expression/iw)
              The regular expression here is case-insensitive and matched at word boundaries.

   Regular expressions
       Regular expressions are given between a pair of slashes; the last slash can be followed by
       a  commutative sequence of letters denoting flags.  Regular expression syntax is sed-like:
       grouping parentheses and alternation must be  backslashed.   For  more  details,  see  the
       Objective  Caml  manual  chapter  on  the  Str module.  In short (x,x1,x2 are meta-symbols
       denoting regular expressions):

       /./    Any character.

       /toto/ Literal string toto.

       /x1x2/ Concatenation.

       /x1\|x2/
              Alternation.

       \(x1\)*
              Star closure.

       [c-d]  Character range.

       \b     Word boundaries.

       /x/i   Case insensitive.

       /x/w   At word boundaries.

   Remark
       Most queries will contain an appreciable amount of  shell  metacharacters.   For  example,
       logical  disjunction  is denoted by the pipe character, which is used by all known shells.
       The problem is aggravated by the fact that names of real commands are likely to appear  in
       the  used  expressions;  successfully  setting  up  a  UNIX pipeline by error is therefore
       plausible.

       When calling ara from the command line in batch mode, You are strongly  urged  to  protect
       your  queries  by  surrounding  them  with  simple  quotes; never write something like ara
       Pack*=~/halt|reboot|shutdown/ as  this  will  very  likely  reboot  your  system  (and  is
       incorrect regular expression syntax, if halt or reboot or shutdown is meant: pipes must be
       backslashed).  Instead, one should write ara 'Pack*=~/halt\|reboot\|shutdown /'

OPTIONS

       None.

EXAMPLES

       Section=utils
              List the name of every package in section utils.

       Section=utils and !Depends:(gnome|kde|gtk)
               ... except those whose dependency field matches the regexp gnome\|kde\|gtk

       Section=utils and Status:(installed & !not-installed)
              List all installed packages in section utils.

       section=utils and !depends:(gtk|gnome|kde) and priority=optional
               ... show only optional packages.

       section=utils & (!depends:(gtk|gnome|kde) | size<100000) & priority=optional
              Well, exclude gtk,gnome or kde stuff only if 100000 bytes or greater.

       Section=games and not (Depends:(gtk|sdl|kde|opengl|gnome|qt)
                  or /shoot\|kill\|destroy\|blast\|race\|bomb/iw
                  or /multi\(-\|\)player\|strategy\|conquest\|3\(-\|\)d/iw)
                  and Depends:(xlibs or vga)
                  and Size <= 1000000

       Display all packages in the games section whose size does not exceeding one million bytes,
       and  which  do  not  depend on fancy stuff like GTK, SDL, KDE, OpenGL, Qt or Gnome, do not
       mention some form of violence (to shoot, to kill, etc.)  in  their  description,  are  not
       described  as  multi-player,  strategy,  conquest  or three-dimensional, and yet depend on
       either xlibs or svga to exclude console-based games.

SPEED

       xara reads the whole database into memory and then processes queries. Since  the  database
       is  usually  big,  this  takes some time. However, queries then run quite fast. So specify
       multiple queries or use the -interactive option  to  amortize  the  cost  of  reading  the
       database.

LICENSE

       xara  is  released  under  the  GNU  General Public License, version 2, a copy of which is
       included in the source distribution.

THANKS

       Many thanks to George Danchev, Thomas  Schoepf  and  Sven  Luther  for  doing  the  Debian
       packaging of ara and many helpful comments.

CONFIGURATION FILES

       The  system-wide  configuration  file  for  xara is /etc/xara.config.  Its syntax is self-
       evident and follows the Ocaml lexical conventions.

       Values in the user-specific configuration file $HOME/.ara/xara.config  override  those  of
       /etc/xara.config.

       The  user  configuration  file  can be edited from the Configure menu item in the Settings
       menu.  GUI parameters such as window sizes and checkbox states are saved at exit  in  that
       file.

OTHER FILES

       Bookmarks are saved into $HOME/.ara/bookmarks.  $HOME/.ara/bookmarks

       The following databases are loaded by default:

       /var/lib/dpkg/available
       /var/lib/dpkg/status
       /var/lib/apt/lists/*_Packages
       /var/lib/apt/lists/*_Sources

SEE ALSO

       ara(1),     apt-cache(8),     aptitude(8),    dpkg(8),    dselect(8),    grep-aptavail(1),
       grep-available(1),   grep-dctrl(1),   grep-status(1),   grep-dctrl(1),   packagesearch(1),
       synaptic(1).

AUTHOR

       Oguz Berke Durak <berke-dev@ouvaton.org> http://abaababa.ouvaton.org/ara/

                                         November 1, 2004                                 XARA(1)