DESCRIPTION end
|\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.

OPTIONS end
|.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

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