.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH TAGCOLL 1 "April 23, 2003" "0.13"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
tagcoll \- perform various operations on tagged collections.

.SH SYNOPSIS
.B tagcoll
.RI [ options ]
.RI [ command ]
.RI [ arguments... ]
.br

.SH DESCRIPTION
\fBtagcoll\fP is a commandline utility to manage tagged collections.
.P
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.
.P
\fBtagcoll\fP 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.

.SH COMMANDS
\fBtagcoll\fP always requires a non-switch argument, that indicates what is the
operation that should be performed:
.TP
\fBcopy\fP [\fIfile\fP]
.br
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.
.TP
\fBreverse\fP [\fIfile\fP]
.br
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.
.TP
\fBdiff\fP <\fIfile1\fP> [\fIfile2\fP]
.br 
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.
.TP
\fBrelated\fP <\fItag(s)\fP> [\fIfile\fP]
.br
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.  For example:
.nf
	tagcoll related mutt,mozilla-browser -
.fi
The \-\-distance option can be used to control how closely related the output
items shold be from the item(s) specified.
.TP
\fBimplications\fP [\fIfile\fP]
.br
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.

For example:

.nf
	C:devel,languages
	ada:devel,languages
	apachemodules:net,servers,web
	browsers:net,web
.fi
.TP
\fBhierarchy\fP [\fIfile\fP]
.br
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.
For example:

.nf
	/net/clients/mail: mutt
	/net/filters/mail: procmail
.fi

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.
.TP
\fBcleanhiearchy\fP [\fIfile\fP]
.br
Like \fIhiearchy\fP, but in every node it merges tags which are attached to the
same set of items.

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

.TP
.B \-\-help
Print an help message and exit.
.TP
.B \-\-version
Print the program version and exit.
.TP
.B \-p, \-\-patch-with=\fIfile\fP
Apply patches from the given tag patch file when reading the collection.
.TP
.B \-i, \-\-implications-from=\fIfile\fP
Use an external list of explicit implications when reading the collection.
.TP
.B \-e, \-\-derived\-tags\-from=\fIfile\fP
Use an external list of derived tags when reading the collection.
.TP
.B \-r, \-\-rename-from=\fIfile\fP
When reading the collection, rename the tags using the given mapping list.
.TP
.B \-x, \-\-expanded-output
Produce output data in full (and redundant) form.  If not specified,
\fBtagcoll\fP produces the minimal amount of data that full represents the
output.
.TP
.B \-d, \-\-distance=\fInum\fP
Set the maximum distance to use for the "related" command (defaults to 0).
.TP
.B \-f, \-\-filter=\fInum\fP
Filter out tags whose cardinality is less than the given value.
.TP
.B \-\-flatten\-threshold=\fInum\fP
When using the "hierarchy" command, set the a threshold of total child items
below which all items in all children of a node appear only attached to the
node itself.  Defaults to 0, meaning "don't flatten small subnodes".
.TP
.B \-\-untagged\-tag=\fIname\fP
Set the item name to use for associating untagged items when using the
"reverse" command.  If not specified, untagged items are not included in the
"reverse" output.


.SH 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:

.nf
	item: tag1, tag2, ..., tagN
.fi

An item with just tag1 is represented as:

.nf
	item: tag1
.fi

An item without tags is represented as:

.nf
	item:
.fi

or just as:

.nf
	item
.fi


An example input:

.nf
	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
.fi

.SH 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.
.P
Example:

.nf
	C: language, devel
	gnome: gui, ui, x11
.fi
 
.SH 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.
.P
Example:

.nf
	mp3: MP3
	language: languages, devel::language, devel::languages
.fi

.SH 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 `\fB+\fP' or `\fB-\fP'
sign.  A tag prepended with a `\fB+\fP' sign is added to the item, while a tag
with a `\fB-\fP' sign is removed from it.
.P
Example:

.nf
	cappuccino: +essential
	emacs: +otheros, -editor
.fi

.SH 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.
.P
The tag expression is an expression composed of tags and the operators `&&'
(and), `||' (or), '!' (not) and the parenthesis '(' and ')'.
.P
Example:

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

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.

.SH EXAMPLES
.P
.nf
# 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

.fi

.SH SEE ALSO
The \fBtagbk\fP draft paper in /usr/share/doc/tagcoll.

.SH AUTHOR
\fBtagcoll\fP has been written by Enrico Zini <enrico@debian.org> for the
purpose of experimenting with tagged collections and related algorithms: all
possible feedback and ideas are thus more than welcome.
.P
Erich Schubert, Herv Eychenne, and many others have contributed a great deal
of feedback and ideas.