1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
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 beginning 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.
|
