tagger is designed as an auditor/reviewers tool. It allows you to add notes to
source code without touching the source itself.

This is very useful for sharing notes between groups of people, and not
interfering with the the ability to maintain patches against the source code.

Tagger currently only supports C code, but will be extended to support other
languages.

####
# Usage

Add a note:

tagger -a [-e|-n 'string'|<file>] <target> [<ref>]
        -a              add a note
        -e              invoke $EDITOR to write the note body
        -n              take the note body from the string
        <file>          take the note body from the named file
        <target>        the file against which the note is to be added
        <ref>           the point in the file at which to add the note

        If <ref> is omited the note will be added to the file without a
        specific location.

Modify a note:

tagger -m -i <note-id> [-e|-n 'string'|<file>] <target>
        -m              modify a note
        -e              invoke $EDITOR to modify the note body
        -n              take the new body from the string
        <file>          take the new body from the named file
        <target>        the file against which the note is filed

Delete a note:

tagger -d -i <note-id> <target>
        -d              delete a note
        -i              delete the note with the given note-id
        <target>        the file to remove a note from

List notes:

tagger -l [-i <note-id>] <target> [<ref>]
        -l              list notes
        -i              list the note with the given note-id
        <refpattern>    list notes with a ref matching the given pattern

Tidy notes:

tagger -t <target>
        <target>        the target whose notes we should tidy

This simply reindexes the notes in the file and corrects the file-header.
Useful if there is a high turnover of notes in the file.

References:

A reference is a comma seperated list of criteria used to pinpoint the target
of the note. The following criteria are available:

line=<integer>
        The note targets line number <integer>

col=<integer>
        The note targets column <integer>

symdef=<string>
        The note targets the definition of the symbol <string>

symref=<string>
        The note targets a reference to the symbol <string>

The follwing criteria combinations are possible:

line=<integer>
line=<integer>,col=<integer>
line=<integer>,symdef=<string>
line=<integer>,symref=<string>
symdef=<string>
symref=<string>

#####
# File Format

The tagger file format is designed to be simple and easy to manipulate by hand
if needed.

A tagger file shares the name of the target file. The file contains 1 or more
notes. When the last note in a file is removed, the file should be deleted,
empty files are not allowed.

The first line of the file is a file-header which describes the mime-type of
the file and the next available note id, which is a 64bit unsigned int.

The syntax is:

#tagger: type=<mime-type>,id=<id>

For example, in a C file it would be:

#tagger: type=text/x-csrc,id=45

where 45 is the next available note-id.

Following the file-header are the notes.

Each note consists of a header and body. The header describes the target of the
note and records its id. The body follows the header on the next line.

#<id>@[<ref-type1>=<ref-option1[,<ref-type2>=<ref-option>[, .. ]]

As an example, to add a note to the definition a C symbol called "do_stuff()",
the header would be:

address@hidden

A reference to a call of a C symbol on a certain line would be:

address@hidden,symref=do_stuff

A reference to a particular column of a line would be:

address@hidden,col=30

Everything following the header until either EOF or another line beginning with
# is treated as the body of the note.

It is forbidden to start a body line with a # (for obvious reasons).  If you
need to use a # at the start of a line, you should proceed it with a space.
This is not seen as something which will be a burden but let us know if it is.

To add a new note, append a new header and body to the end of the file and
increment the note-id field in the header by one.

To remove a note, simply remove the relevent lines from the file. You do not
need to adjust the file-header when doing this (even if it was the last entry
in the file).