[Debtags-commits] [svn] r1030 - in debtags/trunk: . debian src
Enrico Zini
enrico at costa.debian.org
Sun Jul 31 16:07:15 UTC 2005
Author: enrico
Date: Sun Jul 31 16:07:14 2005
New Revision: 1030
Modified:
debtags/trunk/debian/README.Debian
debtags/trunk/debian/changelog
debtags/trunk/debtags.1
debtags/trunk/src/debtags.cc
debtags/trunk/src/instantiations.cc
Log:
Added 'search' command
Updated the manpage
Modified: debtags/trunk/debian/README.Debian
==============================================================================
--- debtags/trunk/debian/README.Debian (original)
+++ debtags/trunk/debian/README.Debian Sun Jul 31 16:07:14 2005
@@ -1,183 +1,22 @@
debtags for Debian
------------------
-Note: this is an old README: it may still be interesting, but many things have
-changed. You can refer to the Debtags website for less outdated resources:
-http://debtags.alioth.debian.org
+Some links if you want to know more about Debtags:
+ The Debtags website
+ http://debtags.alioth.debian.org
- * Important notes for this release
+ An introductory paper about Debtags, written for Debconf5
+ http://debtags.alioth.debian.org/paper-debtags.html
-At the moment of this release, a bug in libapt-pkg-perl (bug #186104) causes an
-harmless segfault on exit when some libapt-pkg-perl functions are used by a perl
-script. If you use the "related" command of debtags, or run the mkbrowser
-example script, you are likely to see this segfault happening.
+ (also available in text format in
+ /usr/share/doc/debtags/paper-debtags.rst.gz)
-The segfault happens after the script has finished, when the destructors are
-called. Maybe I should have the scripts terminate with `exec "/bin/true"' or
-`exec "/bin/false"' so that the destructors are not called. However I hope that
-the problem in libapt-pkg-perl will get fixed soon.
+ My Debtags talk at Debconf 5 (includes slides and video of the presentation)
+ http://people.debian.org/~enrico/talks/20050710-Debconf/
-What is important is that the segfault does not affect the program output. The
-output of "debtags related" is not truncated by the segfault, and you get it all
-regardless of the error.
+You can have a look at the manpage for some example queries.
- * Quick start
- 1. As root, issue the command "debtags update".
-
- 2. The package tag database will be in /var/lib/debtags/package-tags.
-
- 3. Quickly skim `man debtags' for some example queries.
-
-
- * About package tags
-
-Tags, otherwise known as keywords or categories, are short names symbolizing
-qualities, features or other characteristics of an item.
-
-Package tags are tags that get attached to Debian packages to represent a given
-quality, like having a specific feature, offering a specific service, working
-with a specific set of data or in a specific environment, and so on.
-
-Tags can be thought of as the evolution of the package sections historically
-used in Debian systems. Unlike what happens with package sections, the package
-tags system is designed so that more than one tag can be attached to a package,
-and so that all attached tags have the same importance.
-
-
- * Shortcomings of the package sections system
-
-When the sections system was introduced, Debian was a small distribution.
-Package sections were a good idea for separating existing packages by area of
-interest, and worked well for some time.
-
-Now, however, the situation has changed. We have more than 11,000 binary
-packages (as of January 2003). This wide variety does not fit well with the
-one-section-per-package approach. For example, which section should a
-full-featured web browser such as Mozilla be put in? `net'? `web'? `mail'?
-Where should users look for Mozilla?
-
-The section system just does not scale to this extent. Package tags are the
-intended replacement.
-
-
- * Advantages of package tags
-
-Package tags can be used to note the relevant aspects and qualities of a
-package. Unlike package sections, they do not impose a choice of "the most
-important aspect". Unlike package hierarchies, they do not impose an ordering
-on the importance of the tags.
-
-All the structure necessary to present the package archive in an organized way
-can be generated automatically from the package tag database. This means that
-such auto-generated structures will always reflect the up-to-date and real
-situation of the package archive. Handmade hierarchies cost a great effort to
-build and quickly become outdated as the contents of the archive change.
-
-Package tags also enable new kind of queries to the package archive:
-
- - You can query packages with a given quality, or packages without it.
-
- - You can query for qualities, as is now possible with full-text search in
- apt-cache, but without incurring in false positive because of ambiguous
- words, or because words match in a wrong context.
-
- - Simple set operations on the sets of tags assigned to packages can define a
- "distance" function, that can be use to compute a list of packages similar
- to a given one.
-
-These, and the smart hierarchy-generation algorithm implemented in the `tagcoll'
-utility, are only the first applications that have been conceived so far. The
-possibilities are far from having been fully explored.
-
-
- * The package tags system
-
-The package tags system consists on two pieces of information: the normative tag
-vocabulary and the package tags database itself.
-
- The normative tag vocabulary
-
-The normative tag vocabulary is a list of all available tags that can be
-attached to a package. choose from. Every tag is accompanied by a brief
-description of its meaning and intended usage, to avoid possible
-misinterpretations.
-
-A tag may also have a list of explicit implications, that is, a list of tags
-that are automatically implied by the tag. For example, the `C++' tag currently
-implies `languages' and `devel'. These implied tags can be added automatically
-when `C++' is attached to a package.
-
-The vocabulary is maintained by a (yet-to-be-formed) task force that will edit
-it cooperatively via CVS. An up-to-date version of the vocabulary is then
-shipped with the debtags package itself.
-
-Changes that happen in the vocabulary between its various revisions will be
-summarized by the task force in an `upgrade-checklist' document, analogous to
-the one that ships with the Debian policy. This checklist will be used by the
-package tag database editors to keep it up to date with the evolution of the tag
-domain.
-
- The package tags database
-
-The package tags database is the list of tags attached to each package.
-
-It is maintained cooperatively using Erich Schubert's Debian Package Browser,
-found at http://debian.vitavonni.de/packagebrowser/
-
-The package browser provides periodic snapshots of the tags database, that are
-downloaded by debtags and installed in the system.
-
-
- * Internationalization and customization
-
-The package tags system has been designed from the start to fully support
-internationalization and customization.
-
- Internationalization
-
-Internationalizing the package tags is so easy that it's hard to explain in a
-section long enough to appear serious. So, I'm filling it with this nonsense.
-
-Basically, the tags themselves are not designed to be displayed to the user, but
-to work as a sort of pointers to an internationalized name and description
-database. This is not in conflict with the descriptions found in the vocabulary
-database, since they are not intended to be the user-serviceable tag
-descriptions, but help for translators to provide a correct and unambiguous
-description of the tags in their target language.
-
-The format and location of the internationalized tag descriptions have not yet
-been decided, since this prototype implementation has just been released. The
-Debian translation teams will be contacted shortly for help, since design
-choices in this field must take their experience in account.
-
- Customization
-
-As Debian grows bigger and bigger, its nature changes. One idea of the future
-of the Debian system is that of a Debian "Universe of Packages," of which
-sub-projects or meta-distributions offer a custom view targeted at a special
-audience. Sub-projects already exist to target Children, Medical, Music and Law
-environments, and other such customization efforts are being done by developers
-in Extremadura (Spain), or by projects such as Morphix.
-
-The package tags system offers the possibility to customize the package tags
-database so that it better reflects the needs of the intended audience.
-
-The nature of package tags allow the possibility of writing flexible tag patch
-files that represent changes to a tags database. These tag patch files can be
-applied to any version of the database, even future ones, without generating
-conflicts.
-
-What this means is that a customization team can edit the tag database, produce
-a patch file with the `tagcoll' utility and ship it so that it's installed in
-the /etc/debtags/tagpatch.d/ directory. debtags will then pick it up during the
-`update' cycle and apply it to the downloaded tag data.
-
-In this way, the package tags will be kept up-to-date and the changes will be
-preserved.
-
-
- -- Enrico Zini <enrico at debian.org>, Fri, 25 Apr 2003 00:16:36 +0200
- With corrections from Evan Prodromou <evan at debian.org>
+ -- Enrico Zini <enrico at debian.org>, Sun Jul 31 16:06:49 CEST 2005
Modified: debtags/trunk/debian/changelog
==============================================================================
--- debtags/trunk/debian/changelog (original)
+++ debtags/trunk/debian/changelog Sun Jul 31 16:07:14 2005
@@ -8,8 +8,13 @@
* Notify invalid tags passed to 'tag add' as errors, not as verbose output.
Closes: #319656.
* Correctly return exit code when grepping. Closes: #319756.
+ * New libdebtags1 doesn't complain anymore about tags not in the vocabulary.
+ Closes: #292208.
+ * Manpage updates, thanks A Costa for the patch. Closes: #305803.
+ * Removed lots of old content from README.Debian. Most is now in the
+ Debconf5 paper also available in /usr/share/doc. Closes: #308931.
- -- Enrico Zini <enrico at debian.org> Sun, 31 Jul 2005 15:53:16 +0200
+ -- Enrico Zini <enrico at debian.org> Sun, 31 Jul 2005 16:07:09 +0200
debtags (1.1) unstable; urgency=low
Modified: debtags/trunk/debtags.1
==============================================================================
--- debtags/trunk/debtags.1 (original)
+++ debtags/trunk/debtags.1 Sun Jul 31 16:07:14 2005
@@ -28,41 +28,23 @@
\fBdebtags\fP manages package tag data in a debian system and performs basic
queries on it.
.P
-System package data consists on two database file: a normative tag vocabulary,
-shipped with \fBdebtags\fP, found in /var/lib/debtags/vocabulary, and a package
-tag database, updated regularly, found in /var/lib/debtags/package\-tags. The
-vocabulary provides a list of the available tags and what they mean, and the
-package tag database lists which tags are attached to each package.
-.P
Package data are activated or updated in the system using the \fBdebtags
-update\fP command, that must be run by root. It proceeds as follows:
-.IP "1." 4
-The vocabulary file is merged with the local additions from /etc/debtags/tagvoc.d
-.IP "2." 4
-Derived tag definitions are extracted from the vocabulary and placed in
-/var/lib/debtags/derived\-tags; explicit implications are extracted from the
-vocabulary and placed in /var/lib/debtags/implications.
-.IP "3." 4
-Source package tag data files are downloaded from the source locations
-specified in /etc/debtags/sources.list;
-.IP "4." 4
-Downloaded data is merged;
-.IP "5." 4
-If tag patch files are found in the directory /etc/debtags/tagpatch.d, they are
-applied in alphabetical order;
-.IP "6." 4
-The resulting package tag data is then purged of all redundancy and stored in
-/var/lib/debtags/package\-tags, ready to be accessed by applications supporting
-package tags.
+update\fP command; that must be run by root. Tag data are pulled from a
+variety of sources listed in /etc/debtags/sources.list and merged together.
+.P
+Recently, a basic version of the tag data is also present in the APT database.
+It is a very useful resource for applications that are not using
+debtags-specific functions (such as apt-cache or grep-dctrl), but it does not
+support local changes or merging from different sources.
.P
-Once package data has been activated in the system, \fBdebtags\fP itself can be
-used to perform basic queries on it: the vocabulary can be queried with the
-\fBtagshow\fP and \fBtagsearch\fP commands; a package tag database can be
-checked against the vocabulary with the \fBcheck\fP command; packages related
-to a given one (or group) can be shown with the \fBrelated\fP command; the
-whole collection can be copied to standard output to be processed with
-\fBtagcoll\fP or other tools by the \fBcat\fP command; \fBtaggrep\fP can be
-invoked directly using the \fBgrep\fP command.
+\fBdebtags\fP itself can also be used to perform basic queries on the Debtags
+system: the vocabulary can be queried with the \fBtagshow\fP and
+\fBtagsearch\fP commands; a package tag database can be checked against the
+vocabulary with the \fBcheck\fP command; packages related to a given one (or
+group) can be shown with the \fBrelated\fP command; the whole collection can be
+copied to standard output to be processed with \fBtagcoll\fP or other tools by
+the \fBcat\fP command; packages can be searched by tags using the \fBgrep\fP
+command.
.SH COMMANDS
@@ -76,11 +58,6 @@
data and update the system package tag database.
It needs to be run as root.
.TP
-\fBimplications\fP
-.br
-Print the list of explicit implications found in
-the tag vocabulary.
-.TP
\fBcheck\fP [\fIfilename\fP]
.br
Check that all the tags in the given tagged
@@ -108,24 +85,69 @@
.br
Output a fully expanded version of the package tag database.
.TP
+\fBsearch\fP [\-v] [\-q] \fItag expression\fP
+.br
+Output the names and descriptions of the packages that match the given tag
+expression.
+.TP
\fBgrep\fP [\-v] [\-q] \fItag expression\fP
.br
Output the lines of the full package tag database
that match the given tag expression.
.TP
+\fBinstall\fP [\-v] [\-q] \fItag expression\fP
+.br
+Invokes apt-get install with the names of the packages matched by the given tag
+expression.
+.TP
\fBmkpatch\fP [\fIfilename\fP]
.br
Output to standard output a tag patch with the differences between the current
tag database and the tag collection [\fIfilename\fP].
.TP
-\fBinstall\fP [\-v] [\-q] \fItag expression\fP
-.br
-\fIapt-get install\fP the packages that match the given tag expression
-.TP
\fBmaintainers\fP
.br
Create a tagged collection of maintainers and the tags of the packages they
-maintain
+maintain.
+.TP
+\fBtag add\fP \fIpackage\fP \fItags...\fI
+.br
+Add one or more tags to the given package.
+.TP
+\fBtag rm\fP \fIpackage\fP \fItags...\fI
+.br
+Remove one or more tags to the given package.
+.TP
+\fBtag ls\fP \fIpackage\fP
+.br
+Shows the tags of the given package.
+.TP
+\fBsubmit\fP [\fIpatch\fP]
+.br
+Mail the given patch file to the central tag repository. If [\fIpatch\fP] is
+omitted, mail the local tag modifications.
+.TP
+\fBtodo\fP
+.br
+Print a list of the installed packages that are not yet tagged.
+.TP
+\fBscore\fP
+.br
+Score uninstalled packages according to how often their tags appear in the
+packages that are installed already.
+.TP
+\fBfacetcoll\fP
+.br
+Print the tagged collection where each package is tagged with its facets only.
+This is useful for further processing via \fBtagcoll\fP.
+.TP
+\fBstats\fP
+.br
+Print statistics about Debtags.
+.TP
+\fBtodoreport\fP
+.br
+Print a report of packages needing work.
.SH OPTIONS
\fBdebtags\fP follow the usual GNU command line syntax, with long options
@@ -173,16 +195,22 @@
debtags show mutt
# Show packages related to mutt
- debtags related mutt
+ # (adjust the distance as needed)
+ debtags -d 7 related mutt
# Show packages related to galeon and mozilla-browser
- debtags related galeon,mozilla-browser
+ # (adjust the distance as needed)
+ debtags -d 5 related galeon,mozilla-browser
# Search the tag vocabulary for mail-related tags
debtags tagsearch mail
- # Output the collection of all mail clients
- debtags grep 'mail && client'
+ # Show all mail clients
+ debtags search 'works-with::mail && role::sw:client'
+
+ # Output the collection of all mail clients, ready to be reprocessed via
+ # tagcoll
+ debtags grep 'works-with::mail && role::sw:client'
# Produce an easily navigable hierarchy with the collection data
debtags cat | tagcoll hierarchy
@@ -193,20 +221,20 @@
debtags mkpatch work-tags > my-tagpatch
# Produce a local tag patch with tagcolledit
- ...start tagcolledit, load Debian Package Tags, edit, save as "my-tags"...
- debtags mkpatch my-tags > my-tagpatch
+ debtags cat > orig-tags
+ debtags cat > work-tags
+ tagcolledit work-tags
+ tagcoll diff orig-tags work-tags > my-tagpatch
- # Install my-tagpatch in the system
- # (Debian subprojects oughta love this!)
- cp my-tagpatch /etc/debtags/tagpatch.d/
- debtags update
+ # Submit the patch
+ debtags submit my-tagpatch
# Install all IRC clients
- debtags install 'tech::irc && role::client'
+ debtags install 'protocol::irc && role::sw:client'
# Look for friends ;)
- # (don't forget to increase distance as needed)
- debtags maintainers | tagcoll -d 12 related enrico at debian.org
+ # (adjust the distance as needed)
+ debtags maintainers | tagcoll -d 12 related 'Enrico Zini <enrico at debian.org>'
.fi
.SH FILES
@@ -221,29 +249,19 @@
.TP
.B /var/lib/debtags/package\-tags
.br
-The system package tags database
-.TP
-.B /var/lib/debtags/implications
-.br
-The list of implication extracted from the vocabulary and ready for use
-.TP
-.B /var/lib/debtags/derived\-tags
-.br
-The list of derived tags extracted from the vocabulary and ready for use
-.TP
-.B /etc/debtags/tagpatch.d
-.br
-The directory where local tag patches are installed
+The system package tags database, only kept as an easily parsable reference.
+In the same directory there is a the binary index with the same content, used
+by applications for fast access.
.SH SEE ALSO
+.BR debtags-edit (1),
.BR tagcoll (1),
-.BR taggrep (1),
.BR tagcolledit (1),
.BR apt-cache (1),
.br
-.BR http://debian.vitavonni.de/packagebrowser/
+.BR http://debtags.alioth.debian.org/
.br
-.BR http://deb-usability.alioth.debian.org/debtags/
+.BR http://debian.vitavonni.de/packagebrowser/
.SH AUTHOR
\fBdebtags\fP has been written by Enrico Zini <enrico at debian.org>, with a great
Modified: debtags/trunk/src/debtags.cc
==============================================================================
--- debtags/trunk/src/debtags.cc (original)
+++ debtags/trunk/src/debtags.cc Sun Jul 31 16:07:14 2005
@@ -870,18 +870,26 @@
}
#endif
-template<class ITEM>
-int outputGrepped(DebtagsSimple<ITEM>& debtags, const string& expression, bool invertMatch, TagcollConsumer<string, string>& cons)
+
+template<>
+void ExpressionFilter<Package, Tag>::consume(const Package& item, const OpSet<Tag>& tags);
+
+template<>
+void ExpressionFilter<Package, Tag>::consume(const OpSet<Package>& items, const OpSet<Tag>& tags);
+
+
+template<class ITEM, class TAG>
+int outputGrepped(DebtagsSimple<ITEM>& debtags, const string& expression, bool invertMatch, TagcollConsumer<ITEM, TAG>& cons)
{
// Build the grep filter chain
- FilterChain<string, string> filters;
- ExpressionFilter<string> filter;
+ FilterChain<ITEM, TAG> filters;
+ ExpressionFilter<ITEM, TAG> filter;
if (!filter.setExpression(expression))
fatal_error("Error in tag expression `%.*s'.\n", PFSTR(expression));
- filters.appendFilter(&filter);
-
if (invertMatch)
- filter.setMatchType(ExpressionFilter<string>::INVERTED);
+ filter.setMatchType(ExpressionFilter<ITEM, TAG>::INVERTED);
+
+ filters.appendFilter(&filter);
filters.setConsumer(&cons);
@@ -1012,7 +1020,7 @@
}
};
-enum valid_command { UPDATE, CHECK, TAGSHOW, TAGSEARCH, SHOW, RELATED, CAT, GREP, INSTALL, MKPATCH, MAINTAINERS, TAG, SUBMIT, TODO, SCORE, FACETCOLL, STATS, TODOREPORT };
+enum valid_command { UPDATE, CHECK, TAGSHOW, TAGSEARCH, SHOW, RELATED, CAT, SEARCH, GREP, INSTALL, MKPATCH, MAINTAINERS, TAG, SUBMIT, TODO, SCORE, FACETCOLL, STATS, TODOREPORT };
int main(int argc, const char* argv[])
{
@@ -1034,6 +1042,9 @@
" related <pkg1[,pkg2[,pkg2,[...]]]>\n"
" Show packages related to the specified ones.\n"
" cat Output the full package tag database\n"
+ " search [-v] <tag expression>\n"
+ " Output the names and description of the packages that match\n"
+ " the given tag expression\n"
" grep [-v] [-q] <tag expression>\n"
" Output the lines of the full package tag database that match\n"
" the given tag expression\n"
@@ -1084,6 +1095,7 @@
opts.addCommand("show", (int)SHOW);
opts.addCommand("related", (int)RELATED);
opts.addCommand("cat", (int)CAT);
+ opts.addCommand("search", (int)SEARCH);
opts.addCommand("grep", (int)GREP);
opts.addCommand("install", (int)INSTALL);
opts.addCommand("mkpatch", (int)MKPATCH);
@@ -1143,6 +1155,26 @@
break;
}
+ // search [-v] <tag expression>\n"
+ // Output the names and description of the packages that match\n"
+ // the given tag expression\n"
+ case SEARCH:
+ {
+ DebtagsSimple<Package> debtags(false);
+ wantTagDatabase(debtags);
+
+ string expression = args.next();
+
+ PackagePrinter printer;
+
+
+ int matched =
+ outputGrepped(debtags, expression, opts.get("invert-match").defined(), printer);
+
+ return matched > 0 ? 0 : 1;
+ }
+
+
// grep [-v] [-q] <tag expression>
// Output the lines of the full package tag database that match the
// given tag expression
Modified: debtags/trunk/src/instantiations.cc
==============================================================================
--- debtags/trunk/src/instantiations.cc (original)
+++ debtags/trunk/src/instantiations.cc Sun Jul 31 16:07:14 2005
@@ -1,15 +1,47 @@
#define INSTANTIATING_TEMPLATES
+#include <debtags/Package.h>
#include <debtags/Tag.h>
#include <tagcoll/InputMerger.cc>
#include <tagcoll/ItemGrouper.cc>
#include <tagcoll/OpSet.cc>
#include <tagcoll/TagcollConsumer.cc>
+#include <tagcoll/ExpressionFilter.cc>
+
+// Provide needed template specialisations
+
+template<>
+void ExpressionFilter<Debtags::Package, Debtags::Tag>::consume(const Debtags::Package& item, const Tagcoll::OpSet<Debtags::Tag>& tags)
+{
+ Tagcoll::OpSet<std::string> stringTags;
+ for (Tagcoll::OpSet<Debtags::Tag>::const_iterator i = tags.begin(); i != tags.end(); i++)
+ stringTags += i->fullname();
+ if (match(stringTags))
+ {
+ matched++;
+ this->consumer->consume(item, tags);
+ }
+}
+
+template<>
+void ExpressionFilter<Debtags::Package, Debtags::Tag>::consume(const Tagcoll::OpSet<Debtags::Package>& items, const Tagcoll::OpSet<Debtags::Tag>& tags)
+{
+ Tagcoll::OpSet<std::string> stringTags;
+ for (Tagcoll::OpSet<Debtags::Tag>::const_iterator i = tags.begin(); i != tags.end(); i++)
+ stringTags += i->fullname();
+ if (match(stringTags))
+ {
+ matched += items.size();
+ this->consumer->consume(items, tags);
+ }
+}
+
// Instantiate needed templates
template class InputMerger<std::string, Debtags::Tag>;
template class ItemGrouper<std::string, Debtags::Tag>;
+template class ExpressionFilter<Debtags::Package, Debtags::Tag>;
// vim:set ts=4 sw=4:
More information about the Debtags-commits
mailing list