Changes between Initial Version and Version 1 of TagsPlugin/0.5


Ignore:
Timestamp:
Jan 20, 2008, 2:26:04 AM (7 years ago)
Author:
athomas
Comment:

Copying old docs.

Legend:

Unmodified
Added
Removed
Modified
  • TagsPlugin/0.5

    v1 v1  
     1[[PageOutline]]
     2
     3= A Tagging System for Trac =
     4
     5The TagsPlugin implements both a generic tagging engine, and frontends for the Wiki and ticket systems. An extra text entry box is added to the Wiki edit page for tagging Wiki pages, and ticket fields (you can configure which ones) are treated as tags for the ticket system.
     6
     7The TagsPlugin was created by [wiki:muness Muness Alrubaie], with contributions from [wiki:athomas Alec Thomas].
     8
     9== Bugs/Feature Requests ==
     10Existing bugs and feature requests for TagsPlugin are
     11[report:9?COMPONENT=TagsPlugin here].
     12
     13If you have any issues, create a
     14[http://trac-hacks.org/newticket?component=TagsPlugin&owner=athomas new ticket].
     15
     16== Obtaining and Installing ==
     17Follow the [wiki:TagsPlugin/0.5/Installation installation instructions].
     18
     19== What are tags? ==
     20Tags are like hierarchically organized wiki entries, however with them you can categorize a wiki entry under multiple tags and not just under one hierarchy.  You can then search for wiki entries categorized under a tag or a collection of tags.  In other words, tags provide a [http://en.wikipedia.org/wiki/Faceted_classification faceted classification system] for the Trac wiki.
     21
     22As an added bonus, tags are linked to the wiki entry of the same name, allowing you to describe them explicitly under the wiki entry of the same name.  This allows for a flexible means for establishing the context of wiki entries.  Besides this, tags also make it incredibly easy to create [wiki:todo todo] lists or [wiki:Index indexes].
     23
     24Tags don't have to be predefined.  As long as there are wiki entries categorized under a tag, it'll be automatically created.
     25
     26Tags are similar to labels in gmail, tags in the social bookmark manager del.icio.us and Flickr.  They are substantially different from Wikipedia categories, because tags are associated with wiki entries of the same name, whereas [http://meta.wikimedia.org/wiki/Categories WikiMedia Categories] are just indexes.
     27
     28This implementation of wiki tagging is specific to [wiki:TracGuide Trac]. To stay consistent with the way Trac names wiki entries, tags are case sensitive. Trac Hacks itself makes extensive use of tagging and is a good example of their use.  Also, see http://lists.edgewall.com/archive/trac/2006-April/007646.html for an example of how Alec uses !ListTagged to query tickets.
     29
     30=== How do I apply tags? ===
     31To create a tag, follow these steps:
     32
     33 1. Go to the wiki entry you want to tag.
     34 2. Click on ''Edit This Page''
     35 3. Under ''Change information'', ''Tag under:'', enter the tags you want to categorize the entry under.  Separate the tags by commas.  Note that white spaces are currently not supported and will be replaced by commas.
     36 4. Click ''Save changes''.
     37
     38The wiki entry you edit is now categorized under the tags you specified.
     39
     40=== How do I remove a tag from a wiki entry? ===
     41
     42To remove a tag from a wiki entry
     43 1. Go to the wiki entry you want to ''untag''.
     44 2. Click on ''Edit This Page''
     45 3. Under ''Change information'', ''Tag under:'', remove the tag from the list.
     46 4. Click ''Save changes''.
     47
     48== Using the tags ==
     49Querying is implemented through the /tags uri handler, `the tag:<tag>` syntax or [http://projects.edgewall.com/trac/wiki/WikiMacros Trac Macros] as follows
     50
     51=== /tags handler ===
     52Going to /tags under your project will show a list of all tags in the wiki.  /tags/<tag> will show all the objects tagged ''<tag>''.  e.g. [http://muness.textdriven.com/trac/tags/Java,Examples].  This accepts all the parameters that the !ListTagged macro does.  e.g. [http://muness.textdriven.com/trac/tags/Java,Examples?operation=union&amp;amp;showheadings=true].
     53
     54== `tagged:<tag>` Usage ==
     55Using `tagged:<tag>` will link to the wiki <tag>.  If that doesn't exist, it will instead link to a listing of all the objects tagged <tag>.
     56
     57e.g. tagged:todo or tagged:Java,Examples .  This syntax accepts all the options that the !ListTagged macro does.  e.g. tagged:Java,Examples?operation=union .
     58
     59== Tag expressions ==
     60
     61Both the `ListTagged` macro and the `/tags` handler use a basic expression language for filtering tagged objects.
     62
     63Operators supported by the language are:
     64||'''Operator'''||'''Function'''||
     65||`+` or `,`||Logical `and`||
     66||`-`||Logical `and not`
     67||unary `-`||Not||
     68||`|`||Logical `or`||
     69
     70Sub-expressions can be grouped inside parentheses `(`, `)`.
     71
     72Tags can be quoted with single `'` or double `''` quotes, in case they contain characters that are operators.
     73
     74=== Examples ===
     75
     76Intersection of `Java` and `Examples` tags:
     77        tagged:Java+Examples
     78
     79Union of `Java` and `Examples` tags:
     80        tagged:Java|Examples
     81
     82Objects tagged `Java` or `Python`, ''and'' `Examples`
     83        tagged:(Java|Python)+Examples
     84
     85== Macro Usage ==
     86=== !ListTagged ===
     87[[MacroList(ListTagged)]]
     88
     89=== !ListTags ===
     90[[MacroList(ListTags)]]
     91
     92=== !TagCloud ===
     93[[MacroList(TagCloud)]]
     94
     95Note that the macro argument defaults can be customized site-wide.  See the [wiki:TagsPlugin/0.5/Installation installation instructions] and [wiki:TagsPlugin/0.5/TagCloud examples] for details.