--- name: "thoughttracker" section: "1" platform: "linux" package: "thoughttracker" version: "0.5.6-16.2" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/thoughttracker" --- # thoughttracker(1) **ThoughtTracker** - knowledge base application storing arbitrarily linked notes ``` thoughttracker [options] [DATADIR] ``` **ThoughtTracker** is a knowledge base application of sorts. Its purpose is to provide you with an efficiently interfaced database where to store those infrequent ideas that are worth keeping or facts learnt by experience you don't want to forget but don't know anywhere else to put. Unlike other programs of its kind, **ThoughtTracker** doesn't force you to put your facts'n'thoughts in some hierarchy or even store them without any mutual connections whatsoever. Much rather, it allows you to make entries and connect them to any number of others via bidirectional links. A simple but efficient search function allows you to find records, and once you've found the one you were looking for, its links will refer you to related notes. **ThoughtTracker** knows database records which will henceforth be referred to as *entries*. These consist each of a *summary* and a *details* part, and a list of *links*. The summary part stores a summary of the entry's contents in a title-like fashion. This information will later be listed when searching for entries. The details part contains the actual contents of an entry and may store any kind of textual information. A link is a bidirectional connection between two entries; each entry may have an arbitrary number of links. Additionally, there's the concept of so-called *hub entries*. These are just like regular entries, except that by designating them as hubs, the program will display them with a different icon in search and link lists, and some advanced search options can be used to match entries based on whether or not they're flagged as hubs. This is so to provide you with a means of having records that primarily gather links to others with mutually related subjects treated differently from regular entries. This feature may come in handy if you want to have a larger number of related entries linked to one outstanding entry rather than each other. Finally, there are the notions of *the active entry* and *a selected entry*. The former is the entry stored in the database that was last displayed on the *entry form*, a selected entry is an entry chosen by selecting a link in either the search result list of the *search form* or in an entry's link list. To make this clear again, the active entry can be changed by *show*ing an entry selected in the search list or *follow*ing a link selected in an entry's list of links. Additionally, the active entry can explicitly be set via the search form using the button right of its summary display. Besides that, the active entry is reset to none by various actions, such as clearing the form or deleting the currently active entry. As a GTK--/GTK+ application, **ThoughtTracker** accepts those command line parameters commonly paid attention to by GTK+ programs, most importantly,\ **\`DISPLAY'** specifies an alternative X display to be used. Other than that, the program understands the usual ``` --help, -h --version ``` flags, and that's about it. Furthermore, the name of an alternative data directory can be given as a parameter. If this directory doesn't exist, it will be created (but not its hierarchy of base directories). This way, you can use the program to maintain multiple databases, if desired.\ **ENTRY FORM** This form is used to enter, display, and edit entries. It consists of a tool bar, summary and details fields, and the entry's link list. The latter three widgets correspond in functionality to the conceptual description above and work as anyone who's every used a GUI application would expect them to. Entries listed in the link list can be selected, and icons on a per-item basis hint at the type of the referenced link (see the description of the *search form*'s result list below). The only difference is that a wireless light bulb denotes an entry that's connected *only* to the one currently being viewed. This way, icons with a low (i.e., unary) reference count and (presumably) lower importance can be identified easily when occurring within a more comprehensive list of links. The check button labeled "hub" toggles whether the entry being edited is to be considered a hub entry, as explained in the section on "CONCEPTS". Right below it, the button labeled "fixed" chooses whether to use a fixed- width font for displaying the current entry's details field. Depending on the specific contents of the details field, using a font with equally wide characters may be preferable. The chosen state is saved along with the entry's data, and toggling it counts as modification of the current entry. The tool bar's buttons are usually not all sensitive, depending on whether you're entering a new or just viewing or editing an existing entry, and whether, in the case of an existing entry, it is linked to others. The tool bar's buttons' functions are as follows:\ If the shown entry is linked to others, and one of those links is selected, this button will follow the link and display that entry. Double-clicking on a link works as a shortcut for this option.\ Switches to the search form.\ Causes changes made to an existing entry to be explicitly written to the database right away rather than implicitly later on.\ Adds the form's contents to the database, creating a new entry. The entry's summary field is required to be non-blank, the details field may be left empty.\ If an existing entry is being displayed, pressing this button will cause it to be deleted from the database.\ If an existing, linked entry is being displayed and a link is selected, that link will be removed.\ Clears the form's fields' contents and generally resets the form, i.e., the active entry is set to none. Generally, you will be prompted to confirm actions that might cause loss of data. Furthermore, the status bar at the bottom of the window will provide you with additional status information. Additionally, you may import and export the details field's contents to and from files, respectively, and copy/paste text among input fields via the corresponding menu options (see the section on "MENUS").\ **SEARCH FORM** Just like the *entry form* described above, the search form consists of a tool bar, input fields, and a list. In order to search for entries, words, separated by white space, can be entered in the field labeled "Search string:". Making choices in one of the three radio button groups below it allows you to define where and how to search. It is possible to limit the search to summaries, or to search both summaries and details. Via the button group labeled "Logic", you can define whether, if you've specified several search words, these all have to occur in an entry in order to match (AND), or whether the occurrence of just one of the words suffices (OR). Finally, the group labeled "Attributes" allows you to limit the search to hubs or regular entries and connected or isolated records. The list displayed in the lower half of the form will contain the search's results, if any. It will list the matching entries, showing both the summary and an icon hinting at the type for each. The icons' meanings are as follows:\ This icon denotes an entry not connected to any other.\ This indicates that the entry in question is connected to at least one other entry.\ This means the respective entry is a hub, a conceptual peculiarity explained in the section on "CONCEPTS". As the light bulbs' state indicates, however, the hub in question hasn't been connected to other entries yet.\ This symbol denotes a hub entry with at least one link. Below the list, there's an insensitive text field showing the active entry's summary--if there is an active entry. In that case, you can open the entry form for that entry by clicking on the label (which in fact is a button). The (small) arrow button on the right allows you to to make the selected link the active one right away. As is the case about the entry form, not all of the tool bar's buttons are sensitive all of the time, depending on whether you've selected a link in the search result list, and whether there's an active entry, and if so, whether it is connected to the selected one. The tool bar's buttons' functions are as follows:\ Pressing this button will cause a search with the specified parameters to be performed. The number of matching entries found will be displayed on the status bar. By default, if it exceeds a hard-wired limit of 50, the list will be truncated, and you should try and refine your search criteria. This feature can be disabled via the *options dialog*. Alternatively, hitting \[Return\] on the search string field will cause a search to be performed, too.\ If an entry is selected in the search result list, this button will show it (for display and editing) in the entry form (and make it the active entry in the process). Double-clicking on a list entry is a shortcut for pressing this button.\ If there is an active entry, and another entry which it isn't already linked to is selected in the list of search results, pressing this button will create a link between the two.\ This will show a clear entry form, allowing you to conveniently add a new entry.\ If an entry has been selected in the search result list, this button will delete it. If the selected entry was also the active one, the active entry will be reset to none.\ Clears the entire form and resets the active entry to none. Again, the status bar at the bottom of the window will provide you with additional status information. Additionally, you can copy/paste text among input fields of both forms via the corresponding menu options (see the section on "MENUS").\ **MENUS** Some of the menu options have shortcuts which are specified next to their label.\ The option labeled "Options" herein will open a dialog for setting preferences and adjust other run-time parameters. See the section on "OPTIONS DIALOG". While the entry form is active, you may import or export the contents of the details field from or to a file, respectively, via the corresponding options of this menu. The export feature will export the details field's current selection if there is one, otherwise, its entire contents; the import option will insert the chosen file's contents at the cursor's current position within the details field, possibly deleting what's currently selected first. The "Quit" option, naturally, terminates the program, asking whether to save changes if appropriate.\ This menu's first two options allow you to copy and paste text to and from input fields of both the entry and search forms, respectively. Rather than in the X clipboard, copied text will be stored internally, so as to allow for copying among e.g. separate entries. "Copy" will copy the selected text, if any, otherwise the current field's entire contents. Likewise, "Paste" will replace any currently selected text or insert the clipboard's contents at the cursor's current position within the currently active input field. "Revert" will undo all changes made to the entry being edited after a confirmation has been given by the user.\ Via this menu, you may create and keep a list of bookmarks to your most frequently accessed entries. Its usage ought to be intuitive: if there is an *active* entry, a bookmark for it can be created or, if it already exists, deleted. Selecting a bookmark will open the entry form for that entry. Deleting an entry will cause an existing bookmark for it to be deleted as well, and changes of an entry's summary text will be reflected by the bookmark's text as well.\ This menu just offers an option to display copyright information about the program.\ **OPTIONS DIALOG** This dialog offers access to some options influencing **ThoughtTracker**'s behavior and some less frequently needed functions. All of its elements have tool tips set containing slightly more verbose descriptions than their mere labels. Options:\ With this option set, a fixed-width font will be used by default when creating new entries. The button beside this option opens a new dialog where you may chose the fixed-width font to use when the "fixed" button of the entry form is toggled.\ Enabling this option results in that when you add a new entry, and you've previously viewed an existing one (and not switched to the search form since then), you will be asked whether you want these two entries to be linked right away.\ With this option enabled, searches resulting in just a single entry being listed will immediately show that entry. However, this happens only if there is no active entry, as it might prove awkward otherwise when you're searching for records to link the active entry to.\ If this feature is disabled, the list of search results will be truncated if the number of results exceeds a hard-wired limit of 50. In the author's opinion, a search yielding this many or even more entries usually isn't of much use to the user, anyway, and the search criteria should be refined in this case.\ Defines whether the program should remember the main window's size and restore it when started the next time. Actions:\ This option will run a consistency check of the database, automatically repairing any inconsistencies found (note that data may be lost in the course of this). It's mainly there to prevent treacherous bugs in the program from silently messing up the database, and should in theory never report any errors. If there are any, however, a summary detailing those will be displayed. After the check, the database will be optimized, which may free some disk space if there have been a lot of deletions without subsequent additions. See also the section on "BUGS".\ This option will, after asking for confirmation, delete all bookmarks from your list of such. Note that when the options dialog is opened after you've made changes to an existing or entered data for a new entry, you will be asked whether you want to save those changes. This is because in the event that errors are found and repaired during a consistency check, the forms will have to be cleared to avoid possible differences in what they display and the database's contents.\ By default, **ThoughtTracker** will create this directory in your home directory and store its database and configuration files therein. Note that an alternative data directories may be specified on the command line.\ If it exists, this file will be parsed as an application-specific GTK RC file. (If you've specified an alternative data directory to be used, the file will be looked for there.)\ Used to determine where to look for the data directory. I've tried to make both **ThoughtTracker** and its databases as portable as possible. Additionally to the inter-system portability of GDBM databases, the application stores its information with a defined integer key size and endianness. Restrictions are implied by the fact that text is stored as single-byte characters. This means that you may enter 8bit characters, but these will only retain their meaning when viewed with the same character set as when created. Also, due to the restriction to 8 bits, languages with multi-byte letter representations are not supported. This issue may change in a later revision, if I figure out how to implement wide char handling throughout the application. There are no known bugs, of course; however, there are a few issues that may or may not prove problematic:\ The way errors reported by the underlying database facility are handled isn't perfect yet, so **ThoughtTracker** may behave unpredictably in some situations. Most of the time, these should be harmless, however, and database errors are rather improbable, after all, once the database has successfully been opened.\ There is a feature to check the database's consistency and repair it if necessary. It's mainly there to make sure that no bug in the program is gradually messing up the database--in theory, the checks should never fail. However, lacking authentic test cases, this check and repair functionality has not been thoroughly tested. Altogether, you are advised to back up your *~/.thoughttracker* directory every once in a while, just to make sure you won't lose valuable information due to bugs in either the program or one of the libraries it uses, or adverse outside influences. **ThoughtTracker** is copyrighted (c) 2000 by Marco Goetze, \. It is distributed under the terms of the GNU General Public License, revision 2 or any later revision thereof. Use at your own risk. New releases of **ThoughtTracker** can be found at \, or that was true at least by the time this document was last updated.