.TH TAGCOLL 1 "December 02, 2016" "2.0.14" .SH NAME tagcoll \- Perform various operations on a tagged collection .SH SYNOPSIS \fBtagcoll\fP [options] [options and arguments] .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 accepts a non-switch argument, that indicates what is the operation that should be performed: .TP \fBhelp\fP [command] .br With no arguments, print a summary of available commands. If given a command name as argument, print detailed informations about that command. .TP \fBcopy\fP or \fBcat\fP [files...] .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 [files...] .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. .br The \-\-untagged\-tag switch can be used to provide a name to which untagged items will be associated in the output. .TP \fBdiff\fP .br Output a tag patch file with the differences between two files (requires two file arguments). .br The output tag patch file can then be applied when reading a collection with the \-\-patch\-with option. .TP \fBrelated\fP [files...] .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. .br The \-\-distance option can be used to control how closely related the output items shold be from the item(s) specified. .TP \fBimplications\fP [files...] .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. .br Implications can be used to discover implicit hierarchical relationships between tags. .br 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. .TP \fBhierarchy\fP [files...] .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. .br 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 \fBcleanhierarchy\fP [files...] .br Like hiearchy, but in every node it merges tags which are attached to the same set of items. .TP \fBdischierarchy\fP [files...] .br The tree starts with an empty tag set, and branches with the most discriminant tags. .TP \fBfindspecials\fP [files...] .br generate a smart hierarchy and print, for each toplevel tag, what are the items that make it toplevel instead of going below another tag .TP \fBgrep\fP [files...] .br output the collection of tags that match the given tag expression .TP \fBtest\fP [files...] .br perform internal tests and timings .SH 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 "\fBtagcoll\fP help \fIcommand\fP" to see which options are accepted by a given command. Help options: .TP .B \-h, \-?, \-\-help print commandline help and exit. .TP .B \-\-version print the program version and exit. .TP .B \-\-manpage=\fI[hooks]\fP output the tagcoll manpage and exit. .PP \fBOptions for command help\fP .br \fBOptions for command copy\fP .br Options controlling transformations of input data: .TP .B \-\-derived=\fIexpand derived tags using the given list\fP . .TP .B \-\-implications-from=\fIuse an external list of implications\fP . .TP .B \-\-rename-from=\fIrename tags using the given mapping list\fP . .TP .B \-p \fIapply patches from the given tag patch file\fP, \-\-patch-with=\fIapply patches from the given tag patch file\fP, \-\-patch=\fIapply patches from the given tag patch file\fP . .TP .B \-\-remove-unfaceted=\fIwhile parsing, remove all tags with no facet part\fP . .TP .B \-\-remove-tags=\fI\fP while parsing, remove all tags matching the given tag expression. .PP Options controlling transformations of output data: .TP .B \-g, \-\-group, \-\-group-items group items with the same tagset in the output collection. .TP .B \-\-redundant when implications are provided, expand them explicitly in the output. .TP .B \-i, \-\-items output only the names of the items, without the tags. .TP .B \-c, \-\-count output the count of tags instead of the tags. .PP \fBOptions for command reverse\fP .br Options controlling transformations of input data: .TP .B \-\-derived=\fIexpand derived tags using the given list\fP . .TP .B \-\-implications-from=\fIuse an external list of implications\fP . .TP .B \-\-rename-from=\fIrename tags using the given mapping list\fP . .TP .B \-p \fIapply patches from the given tag patch file\fP, \-\-patch-with=\fIapply patches from the given tag patch file\fP, \-\-patch=\fIapply patches from the given tag patch file\fP . .TP .B \-\-remove-unfaceted=\fIwhile parsing, remove all tags with no facet part\fP . .TP .B \-\-remove-tags=\fI\fP while parsing, remove all tags matching the given tag expression. .PP Options controlling transformations of output data: .TP .B \-g, \-\-group, \-\-group-items group items with the same tagset in the output collection. .TP .B \-\-redundant when implications are provided, expand them explicitly in the output. .TP .B \-i, \-\-items output only the names of the items, without the tags. .TP .B \-c, \-\-count output the count of tags instead of the tags. .PP Other options: .TP .B \-\-untagged-tag=\fI\fP 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. \fBOptions for command diff\fP .br \fBOptions for command related\fP .br Options controlling transformations of input data: .TP .B \-\-derived=\fIexpand derived tags using the given list\fP . .TP .B \-\-implications-from=\fIuse an external list of implications\fP . .TP .B \-\-rename-from=\fIrename tags using the given mapping list\fP . .TP .B \-p \fIapply patches from the given tag patch file\fP, \-\-patch-with=\fIapply patches from the given tag patch file\fP, \-\-patch=\fIapply patches from the given tag patch file\fP . .TP .B \-\-remove-unfaceted=\fIwhile parsing, remove all tags with no facet part\fP . .TP .B \-\-remove-tags=\fI\fP while parsing, remove all tags matching the given tag expression. .PP Other options: .TP .B \-d \fI\fP, \-\-distance=\fI\fP set the maximum distance to use for the "related" command (defaults to 0). \fBOptions for command implications\fP .br Options controlling transformations of input data: .TP .B \-\-derived=\fIexpand derived tags using the given list\fP . .TP .B \-\-implications-from=\fIuse an external list of implications\fP . .TP .B \-\-rename-from=\fIrename tags using the given mapping list\fP . .TP .B \-p \fIapply patches from the given tag patch file\fP, \-\-patch-with=\fIapply patches from the given tag patch file\fP, \-\-patch=\fIapply patches from the given tag patch file\fP . .TP .B \-\-remove-unfaceted=\fIwhile parsing, remove all tags with no facet part\fP . .TP .B \-\-remove-tags=\fI\fP while parsing, remove all tags matching the given tag expression. .PP \fBOptions for command hierarchy\fP .br Options controlling transformations of input data: .TP .B \-\-derived=\fIexpand derived tags using the given list\fP . .TP .B \-\-implications-from=\fIuse an external list of implications\fP . .TP .B \-\-rename-from=\fIrename tags using the given mapping list\fP . .TP .B \-p \fIapply patches from the given tag patch file\fP, \-\-patch-with=\fIapply patches from the given tag patch file\fP, \-\-patch=\fIapply patches from the given tag patch file\fP . .TP .B \-\-remove-unfaceted=\fIwhile parsing, remove all tags with no facet part\fP . .TP .B \-\-remove-tags=\fI\fP while parsing, remove all tags matching the given tag expression. .PP Options controlling generation of tag hierarchies: .TP .B \-\-flatten-threshold=\fI\fP set the number of total items below which a branch is flattened when using the "hierarchy" command (defaults to 0, meaning "don't flatten"). .TP .B \-f \fI\fP, \-\-filter=\fI\fP filter out the tags with cardinality less than the given value (defaults to not filter; currently only works when building hierarchies). .PP \fBOptions for command cleanhierarchy\fP .br Options controlling transformations of input data: .TP .B \-\-derived=\fIexpand derived tags using the given list\fP . .TP .B \-\-implications-from=\fIuse an external list of implications\fP . .TP .B \-\-rename-from=\fIrename tags using the given mapping list\fP . .TP .B \-p \fIapply patches from the given tag patch file\fP, \-\-patch-with=\fIapply patches from the given tag patch file\fP, \-\-patch=\fIapply patches from the given tag patch file\fP . .TP .B \-\-remove-unfaceted=\fIwhile parsing, remove all tags with no facet part\fP . .TP .B \-\-remove-tags=\fI\fP while parsing, remove all tags matching the given tag expression. .PP Options controlling generation of tag hierarchies: .TP .B \-\-flatten-threshold=\fI\fP set the number of total items below which a branch is flattened when using the "hierarchy" command (defaults to 0, meaning "don't flatten"). .TP .B \-f \fI\fP, \-\-filter=\fI\fP filter out the tags with cardinality less than the given value (defaults to not filter; currently only works when building hierarchies). .PP \fBOptions for command dischierarchy\fP .br Options controlling transformations of input data: .TP .B \-\-derived=\fIexpand derived tags using the given list\fP . .TP .B \-\-implications-from=\fIuse an external list of implications\fP . .TP .B \-\-rename-from=\fIrename tags using the given mapping list\fP . .TP .B \-p \fIapply patches from the given tag patch file\fP, \-\-patch-with=\fIapply patches from the given tag patch file\fP, \-\-patch=\fIapply patches from the given tag patch file\fP . .TP .B \-\-remove-unfaceted=\fIwhile parsing, remove all tags with no facet part\fP . .TP .B \-\-remove-tags=\fI\fP while parsing, remove all tags matching the given tag expression. .PP Options controlling generation of tag hierarchies: .TP .B \-\-flatten-threshold=\fI\fP set the number of total items below which a branch is flattened when using the "hierarchy" command (defaults to 0, meaning "don't flatten"). .TP .B \-f \fI\fP, \-\-filter=\fI\fP filter out the tags with cardinality less than the given value (defaults to not filter; currently only works when building hierarchies). .PP \fBOptions for command findspecials\fP .br Options controlling transformations of input data: .TP .B \-\-derived=\fIexpand derived tags using the given list\fP . .TP .B \-\-implications-from=\fIuse an external list of implications\fP . .TP .B \-\-rename-from=\fIrename tags using the given mapping list\fP . .TP .B \-p \fIapply patches from the given tag patch file\fP, \-\-patch-with=\fIapply patches from the given tag patch file\fP, \-\-patch=\fIapply patches from the given tag patch file\fP . .TP .B \-\-remove-unfaceted=\fIwhile parsing, remove all tags with no facet part\fP . .TP .B \-\-remove-tags=\fI\fP while parsing, remove all tags matching the given tag expression. .PP Options controlling generation of tag hierarchies: .TP .B \-\-flatten-threshold=\fI\fP set the number of total items below which a branch is flattened when using the "hierarchy" command (defaults to 0, meaning "don't flatten"). .TP .B \-f \fI\fP, \-\-filter=\fI\fP filter out the tags with cardinality less than the given value (defaults to not filter; currently only works when building hierarchies). .PP \fBOptions for command grep\fP .br Options controlling transformations of input data: .TP .B \-\-derived=\fIexpand derived tags using the given list\fP . .TP .B \-\-implications-from=\fIuse an external list of implications\fP . .TP .B \-\-rename-from=\fIrename tags using the given mapping list\fP . .TP .B \-p \fIapply patches from the given tag patch file\fP, \-\-patch-with=\fIapply patches from the given tag patch file\fP, \-\-patch=\fIapply patches from the given tag patch file\fP . .TP .B \-\-remove-unfaceted=\fIwhile parsing, remove all tags with no facet part\fP . .TP .B \-\-remove-tags=\fI\fP while parsing, remove all tags matching the given tag expression. .PP Options controlling transformations of output data: .TP .B \-g, \-\-group, \-\-group-items group items with the same tagset in the output collection. .TP .B \-\-redundant when implications are provided, expand them explicitly in the output. .TP .B \-i, \-\-items output only the names of the items, without the tags. .TP .B \-c, \-\-count output the count of tags instead of the tags. .PP Other options: .TP .B \-v, \-\-invert-match invert the sense of matching, to select non-matching lines. .TP .B \-q, \-\-quiet do not write anything to standard output, but exit with 0 if any match is found. \fBOptions for command test\fP .br Options controlling transformations of input data: .TP .B \-\-derived=\fIexpand derived tags using the given list\fP . .TP .B \-\-implications-from=\fIuse an external list of implications\fP . .TP .B \-\-rename-from=\fIrename tags using the given mapping list\fP . .TP .B \-p \fIapply patches from the given tag patch file\fP, \-\-patch-with=\fIapply patches from the given tag patch file\fP, \-\-patch=\fIapply patches from the given tag patch file\fP . .TP .B \-\-remove-unfaceted=\fIwhile parsing, remove all tags with no facet part\fP . .TP .B \-\-remove-tags=\fI\fP while parsing, remove all tags matching the given tag expression. .PP .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 is maintained by enrico@enricozini.org. This manpage has been automatically generated by the tagcoll program.