Provided by: tagcoll_2.0.14-1build1_amd64 bug

NAME

       tagcoll - Perform various operations on a tagged collection

SYNOPSIS

       tagcoll [options] <command> [options and arguments]

DESCRIPTION

       tagcoll is a commandline utility to manage tagged collections.

       A  tagged collection is a set of items in which each item is associated with a set of zero
       or more tags, in no particular order.

       tagcoll can take a tagged collection and perform various complex operations  on  it,  like
       applying  transformations, finding implicit implications between tags and building a smart
       intuitive hierarchy to navigate the items.

COMMANDS

       tagcoll accepts a non-switch argument, that indicates what is the operation that should be
       performed:

       help [command]
              With  no arguments, print a summary of available commands.  If given a command name
              as argument, print detailed informations about that command.

       copy or cat [files...]
              Output the normalized collection on standard output,  applying  transformations  if
              requested.   This  is  the  default  action  if  no other switches are provided.  A
              normalized collection is a collection in which an item appears in just one line.

       reverse [files...]
              Output the inbound collection "reversed" from the tags  point  of  view,  that  is,
              associating to each tag the list of items associated to it in the input.
              The  --untagged-tag  switch  can  be used to provide a name to which untagged items
              will be associated in the output.

       diff <file1> <file2>
              Output a tag patch file with the differences between two files (requires  two  file
              arguments).
              The  output  tag  patch file can then be applied when reading a collection with the
              --patch-with option.

       related <item> [files...]
              Output a list of the items that are related to the given item or list of items.  If
              more than one items are to be specified, separate them with commas.
              The  --distance  option can be used to control how closely related the output items
              shold be from the item(s) specified.

       implications [files...]
              Output a list of all implicit implications between tags contained in the hierarchy.
              Implication is defined such that tag A implies tag B if every item tagged with A is
              also tagged with B.
              Implications can be used to discover implicit  hierarchical  relationships  between
              tags.
              The  output  is  one  line per tag, with just tags that have implications, with the
              name of the package, a colon and a comma-separated list of all implied tags.

       hierarchy [files...]
              Organize the collection in an intuitively navigable hierarchy.  The output  is  one
              line  per  package,  with the package name prepended by the path to the item in the
              hierarchy.
              A detailed description of the  hierarchy  generation  algorithm  is  found  in  the
              tagbk-draft.pdf  draft  paper  available in this package; if you want to understand
              what are the goals of the algorithm and how it works, please give it a read.

       cleanhierarchy [files...]
              Like hiearchy, but in every node it merges tags which are attached to the same  set
              of items.

       dischierarchy [files...]
              The  tree  starts  with  an  empty tag set, and branches with the most discriminant
              tags.

       findspecials [files...]
              generate a smart hierarchy and print, for each toplevel tag,  what  are  the  items
              that make it toplevel instead of going below another tag

       grep <expression> [files...]
              output the collection of tags that match the given tag expression

       test [files...]
              perform internal tests and timings

OPTIONS

       This  program  follows  the usual GNU command line syntax, with long options starting with
       two dashes (`-').

       Every one of the commands listed above has its own set of options.  To keep  this  manpage
       readable,  all the options are presented together.  Please refer to "tagcoll help command"
       to see which options are accepted by a given command.

       Help options:

       -h, -?, --help
              print commandline help and exit.

       --version
              print the program version and exit.

       --manpage=[hooks]
              output the tagcoll manpage and exit.

       Options for command help
       Options for command copy

       Options controlling transformations of input data:

       --derived=expand derived tags using the given list

       --implications-from=use an external list of implications

       --rename-from=rename tags using the given mapping list

       -p apply patches from the given tag patch file, --patch-with=apply patches from the  given
       tag patch file, --patch=apply patches from the given tag patch file

       --remove-unfaceted=while parsing, remove all tags with no facet part

       --remove-tags=<expression>
              while parsing, remove all tags matching the given tag expression.

       Options controlling transformations of output data:

       -g, --group, --group-items
              group items with the same tagset in the output collection.

       --redundant
              when implications are provided, expand them explicitly in the output.

       -i, --items
              output only the names of the items, without the tags.

       -c, --count
              output the count of tags instead of the tags.

       Options for command reverse

       Options controlling transformations of input data:

       --derived=expand derived tags using the given list

       --implications-from=use an external list of implications

       --rename-from=rename tags using the given mapping list

       -p  apply patches from the given tag patch file, --patch-with=apply patches from the given
       tag patch file, --patch=apply patches from the given tag patch file

       --remove-unfaceted=while parsing, remove all tags with no facet part

       --remove-tags=<expression>
              while parsing, remove all tags matching the given tag expression.

       Options controlling transformations of output data:

       -g, --group, --group-items
              group items with the same tagset in the output collection.

       --redundant
              when implications are provided, expand them explicitly in the output.

       -i, --items
              output only the names of the items, without the tags.

       -c, --count
              output the count of tags instead of the tags.

       Other options:

       --untagged-tag=<tag>
              set item name to use for  associating  untagged  items  when  using  the  "reverse"
              command.  If not specified, untagged items are not included in the output.  Options
              for command diff
              Options for command related

              Options controlling transformations of input data:

       --derived=expand derived tags using the given list

       --implications-from=use an external list of implications

       --rename-from=rename tags using the given mapping list

       -p apply patches from the given tag patch file, --patch-with=apply patches from the  given
       tag patch file, --patch=apply patches from the given tag patch file

       --remove-unfaceted=while parsing, remove all tags with no facet part

       --remove-tags=<expression>
              while parsing, remove all tags matching the given tag expression.

       Other options:

       -d <val>, --distance=<val>
              set the maximum distance to use for the "related" command (defaults to 0).  Options
              for command implications

              Options controlling transformations of input data:

       --derived=expand derived tags using the given list

       --implications-from=use an external list of implications

       --rename-from=rename tags using the given mapping list

       -p apply patches from the given tag patch file, --patch-with=apply patches from the  given
       tag patch file, --patch=apply patches from the given tag patch file

       --remove-unfaceted=while parsing, remove all tags with no facet part

       --remove-tags=<expression>
              while parsing, remove all tags matching the given tag expression.

       Options for command hierarchy

       Options controlling transformations of input data:

       --derived=expand derived tags using the given list

       --implications-from=use an external list of implications

       --rename-from=rename tags using the given mapping list

       -p  apply patches from the given tag patch file, --patch-with=apply patches from the given
       tag patch file, --patch=apply patches from the given tag patch file

       --remove-unfaceted=while parsing, remove all tags with no facet part

       --remove-tags=<expression>
              while parsing, remove all tags matching the given tag expression.

       Options controlling generation of tag hierarchies:

       --flatten-threshold=<val>
              set the number of total items below which a branch  is  flattened  when  using  the
              "hierarchy" command (defaults to 0, meaning "don't flatten").

       -f <val>, --filter=<val>
              filter  out  the  tags  with cardinality less than the given value (defaults to not
              filter; currently only works when building hierarchies).

       Options for command cleanhierarchy

       Options controlling transformations of input data:

       --derived=expand derived tags using the given list

       --implications-from=use an external list of implications

       --rename-from=rename tags using the given mapping list

       -p apply patches from the given tag patch file, --patch-with=apply patches from the  given
       tag patch file, --patch=apply patches from the given tag patch file

       --remove-unfaceted=while parsing, remove all tags with no facet part

       --remove-tags=<expression>
              while parsing, remove all tags matching the given tag expression.

       Options controlling generation of tag hierarchies:

       --flatten-threshold=<val>
              set  the  number  of  total  items below which a branch is flattened when using the
              "hierarchy" command (defaults to 0, meaning "don't flatten").

       -f <val>, --filter=<val>
              filter out the tags with cardinality less than the given  value  (defaults  to  not
              filter; currently only works when building hierarchies).

       Options for command dischierarchy

       Options controlling transformations of input data:

       --derived=expand derived tags using the given list

       --implications-from=use an external list of implications

       --rename-from=rename tags using the given mapping list

       -p  apply patches from the given tag patch file, --patch-with=apply patches from the given
       tag patch file, --patch=apply patches from the given tag patch file

       --remove-unfaceted=while parsing, remove all tags with no facet part

       --remove-tags=<expression>
              while parsing, remove all tags matching the given tag expression.

       Options controlling generation of tag hierarchies:

       --flatten-threshold=<val>
              set the number of total items below which a branch  is  flattened  when  using  the
              "hierarchy" command (defaults to 0, meaning "don't flatten").

       -f <val>, --filter=<val>
              filter  out  the  tags  with cardinality less than the given value (defaults to not
              filter; currently only works when building hierarchies).

       Options for command findspecials

       Options controlling transformations of input data:

       --derived=expand derived tags using the given list

       --implications-from=use an external list of implications

       --rename-from=rename tags using the given mapping list

       -p apply patches from the given tag patch file, --patch-with=apply patches from the  given
       tag patch file, --patch=apply patches from the given tag patch file

       --remove-unfaceted=while parsing, remove all tags with no facet part

       --remove-tags=<expression>
              while parsing, remove all tags matching the given tag expression.

       Options controlling generation of tag hierarchies:

       --flatten-threshold=<val>
              set  the  number  of  total  items below which a branch is flattened when using the
              "hierarchy" command (defaults to 0, meaning "don't flatten").

       -f <val>, --filter=<val>
              filter out the tags with cardinality less than the given  value  (defaults  to  not
              filter; currently only works when building hierarchies).

       Options for command grep

       Options controlling transformations of input data:

       --derived=expand derived tags using the given list

       --implications-from=use an external list of implications

       --rename-from=rename tags using the given mapping list

       -p  apply patches from the given tag patch file, --patch-with=apply patches from the given
       tag patch file, --patch=apply patches from the given tag patch file

       --remove-unfaceted=while parsing, remove all tags with no facet part

       --remove-tags=<expression>
              while parsing, remove all tags matching the given tag expression.

       Options controlling transformations of output data:

       -g, --group, --group-items
              group items with the same tagset in the output collection.

       --redundant
              when implications are provided, expand them explicitly in the output.

       -i, --items
              output only the names of the items, without the tags.

       -c, --count
              output the count of tags instead of the tags.

       Other options:

       -v, --invert-match
              invert the sense of matching, to select non-matching lines.

       -q, --quiet
              do not write anything to standard output, but exit with 0 if any  match  is  found.
              Options for command test

              Options controlling transformations of input data:

       --derived=expand derived tags using the given list

       --implications-from=use an external list of implications

       --rename-from=rename tags using the given mapping list

       -p  apply patches from the given tag patch file, --patch-with=apply patches from the given
       tag patch file, --patch=apply patches from the given tag patch file

       --remove-unfaceted=while parsing, remove all tags with no facet part

       --remove-tags=<expression>
              while parsing, remove all tags matching the given tag expression.

Format of the tagged collection input

       A sequence of lines describing the tagged items.  Order of tags  does  not  matter.   Each
       line starts with the item name, optionally followed by tag names.

       Tag names are separated by the item name by a colon and one or more spaces or tabs.

       Tag names are separated by each others using a comma followed by one or more spaces.

       Item  names  can  contain  colons, but not followed by a space or tab, and cannot end in a
       colon.  "ui:gnome" is ok, "ui:" is not.

       Tag names can contain commas, but not followed by a space, and  cannot  end  in  a  comma.
       "cult,religion" is ok, "cult," is not.

       An item with tags tag1, tag2, ..., tagN is represented as:

            item: tag1, tag2, ..., tagN

       An item with just tag1 is represented as:

            item: tag1

       An item without tags is represented as:

            item:

       or just as:

            item

       An example input:

            mutt: clients/mail/net
            sylpheed: clients/mail/net
            procmail: filters/mail/net
            spamassassin: filters/mail/net
            spamfilter: filters/mail/net
            bulkmail: lists/mail/net
            mailman: lists/mail/net
            smartlist: lists/mail/net
            xeukleides: educational
            new-package-not-yet-categorized:
            another-uncategorized

Format for the explicit implications input

       The format for the explicit implications is the same as the one for the tagged collection:
       put the name of a tag at the left of the colon and the names of the tags it implies to the
       right.

       Example:

            C: language, devel
            gnome: gui, ui, x11

Format for the rename mapping input

       The  format  for the rename mappings is the same as the one for the tagged collection: put
       the new name of the tags at the left of the colon and the names of  the  old  tags  to  be
       renamed on the right.

       Example:

            mp3: MP3
            language: languages, devel::language, devel::languages

Format for the tag patch file

       The  format  for the rename mappings is the same as the one for the tagged collection, but
       the tags are listed prepended with a `+' or `-' sign.  A tag prepended with a `+' sign  is
       added to the item, while a tag with a `-' sign is removed from it.

       Example:

            cappuccino: +essential
            emacs: +otheros, -editor

Format for the derived tag list

       The format for the derived tag list is a line-oriented format with a derived tag per line.
       The derived tag name starts as the begining of the  line  and  is  separated  by  his  tag
       expression by colon and space, just like the tagged collection items.

       The  tag  expression  is an expression composed of tags and the operators `&&' (and), `||'
       (or), '!' (not) and the parenthesis '(' and ')'.

       Example:

            userlevel::novice: !specialized && (interface::gui || interface::curses)

       The tag at the left of the colon is added when the set of tags  of  an  item  matches  the
       expression at the right of the colon.

EXAMPLES

       # Output the collection in normal form
       tagcoll copy collection-file

       # Output the items associated to a given tag
       tagcoll reverse collection-file | grep ^tag:

       # Produce tag patch data describing the tag difference between two collections
       tagcoll diff coll1 coll2

       # Apply a tag patch file to coll1
       tagcoll --patch-with=tagpatch copy coll1 > collection-file

       # Show the minimal set of implicit implications contained in the collection
       tagcoll implications collection-file

       # Show the implicit implications contained in the collection, fully expanded
       tagcoll --expanded-output implications collection-file

       # Build a smart hierarchy with the collection
       tagcoll hierarchy collection-file

       # Build a cleaner smart hierarchy with the collection (yoy might like to tweak
       # the parameters)
       tagcoll -f 5 --flatten-threshold=5 cleanhierarchy collection-file

       # Apply some transformations to the collection and build a smart hierarchy with
       # them
       tagcoll --implications-from=explicit-implications-file \
            --rename-from=rename-map \
            --patch-with=patch-file \
            hierarchy collection-file

       # Merge the contents two collections
       cat coll1 coll2 | tagcoll copy > merged

       # Merge the contents two collections and apply an external patch
       cat coll1 coll2 | tagcoll --patch-with=patch-file copy > merged

       # Build a smart hierarchy out of the implicit implications contained in the
       # collection
       tagcoll implications collection-file | tagcoll hierarchy

       # Build a smart hierarchy out of the combination of explicit implications and
       # the implicit implications contained in the collection
       tagcoll --implications-from=explicit-implications-file \
            implications collection-file | tagcoll hierarchy

       # Show all the items similar to "mutt"
       tagcoll related mutt collection-file

       # Show all the items similar to "mutt" and "mozilla-browser"
       tagcoll related mutt,mozilla-browser collection-file

       # Show all the items similar to "mutt", with at most two differences
       # in the tag set
       tagcoll --distance=2 related mutt collection-file

SEE ALSO

       The tagbk draft paper in /usr/share/doc/tagcoll.

AUTHOR

       tagcoll is maintained by enrico@enricozini.org.

       This manpage has been automatically generated by the tagcoll program.