Keeping Notes

Comments are one of the most idiosyncratic elements of computer programming. Two people can do the same thing exactly the same way but consider completely different aspects deserving of comment. Presuming the comments have something to do with the program itself, they will be comprehensible to anyone with enough knowledge, although often by the time you figure out the comment, you've already figured out the code anyway.

TkCodex won't make you write more useful comments for others, but it may help you keep more useful notes for yourself (since not everyone uses TkCodex yet, doing anything else would be pointless). It also allows you to save your existing index of searches, which might compliment your notes or help serve as a starting-point for later if you're tired of staring at the screen for a while.

If you want to keep a single highlight of a searchable term, you can eliminate the rest of them by selecting a range and clicking both buttons simultaneously in the index list.

To avoid getting WINDOW, I set the case button on the command window, so the results of these searches are preceded by an asterisk. Now I eliminate all the instances I don't want. You can also index a specific place by highlighting it red (ctrl-r). By default, red highlights are not shown in the user index, but you can toggle their appearance with ctrl-x.

One purpose to saving a small set of indexes is that you can use them as additional reference points to the subroutine index. This is particularly handy if you index a brief comment (eg, "main loop", "enumerations", "fork-socket" etc.).

The other unique aspect of red highlights is that they remain visible in the text area when you switch to the subroutine view. Normal searches and notes disappear with the user index.

To add a note, you just select the text you want marked-up and use ctrl-N. Hypertext highlights are yellow on gray and their index in the list is magenta. When you mouse over them, the familiar hypertext hand will appear. A double left click calls up the note window again. Never dismiss the note window (or any of the view windows) by "closing" it with your window manager -- always use the done button or the F keys, or you will never see that window again. This is because of some peculiarities of perl/tk which are explained in more detail elsewhere in the TkCodex documentation. Changes made to the note will remain, but if the note was part of stuff you saved and loaded, you will have to press "save" again to make it permanent.

Saving notes is simple. You just press "save" and TkCodex will keep a file in your codex notes directory (see configuration) with the extension .store (this is a binary produced by perl's "Storable" module). To load a set of notes, just press "load", and if there is a .store file in the notes directory matching the current file name, they will be loaded. Ostensibly, this means you can't have more than one set of notes for one filename, but it also means you can do it with one click and don't have to search around or remember where and under what name you saved the notes. Of course, you can switch files in and out of the notes directory to your heart's content (or you can modify your configuration file to switch to a different note directory). Something else to keep in mind: when there are multiple files with the same name in a tree, TkCodex adds a partial path to some names in the command window file list box. This partial path+name is what is used to save and check for notes, so if you have saved notes for file.x at some point and then start TkCodex higher in the tree containing file.x, such that it now appears as subdir/file.x, TkCodex will look for notes for "subdir_file.x" when you press load.

There is a problem with all this. The notes, highlights, etc, are indexed by character position in the file, so if you save notes and the file changes, when you load the altered file and its notes, the notes will be in the wrong place! Fortunately, these changes almost always affect the vertical position -- line number -- and not the horizontal, unless the alteration was a complete change in indent style, et. al.

For example, let's pretend you added a new function somewhere in the middle of your program and that function is 27 lines of additional code. All the notes after that point will be 27 lines off of their intended position:

Here you can see the yellow-on-gray tag for "sub formlist" is on line 588, while sub formlist is actually on line 615. To correct this, enter 27 in the text entry at the top, position the cursor above where you want the changes to take effect, and press ctrl-a.

Notice that all the indexes below line 587 (where the cursor is) are affected, including "sub pushtag" which is moved to line 929. If there were no other changes, this should be the correct place. Lines can be quickly subtracted (like when some function becomes defunct) using ctrl-s.

My intention with the note taking capacity of TkCodex was to favour fast, intuitive functionality and not for the purpose of creating permanent archives of your thoughts, but you can do that too if you want.