First draft of a spec attached. Glosses over directory structure (we agree here anyway and it isn't complicated).
It lacks: details of locking for working on the notes file (exclusive lock on notefile.lock before writing..?) and details of how regex might work. I assume we want this... "Give me all notes relating to str* on this file". It doesn't discuss how we know where the source and notes directories are (again a small issue). I've avoided the term post-it as I fear trademarks ;) I don't see any obvious pitfalls with the spec yet. Let me know what you think. I'm happy to knock up a proof of concept once we're happy with the spec. Cheers, Rob -- Rob Holland Inverse Path Ltd Chief R & D Engineer -----> <-------- <[EMAIL PROTECTED]> http://www.inversepath.com 0xD91B4729 5251 4FAC D684 8845 5604 E44F D65C 392F D91B 4729
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:
[EMAIL PROTECTED]
A reference to a call of a C symbol on a certain line would be:
[EMAIL PROTECTED],symref=do_stuff
A reference to a particular column of a line would be:
[EMAIL PROTECTED],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).
signature.asc
Description: This is a digitally signed message part
_______________________________________________ Bug-global mailing list [email protected] http://lists.gnu.org/mailman/listinfo/bug-global
