for version 0.5

# Working With Tags

## Sections

## Tagging Overview

As a journal gradually increases in size over the term of months and years, you will probably write about similar topics multiple times. If you are not using a range limit on such a journal, related entries can be harder to find and/or track once the sheer volume of entries is taken into account. While RoboJournal allows you to search for an entry using a keyword system, it is far easier to use the built-in tagging system to keep related entries together.

RoboJournal's tagging system is designed to work with the currently-selected entry in the Timeline or the entry that is currently open in the Editor. As such, using the tagging system requires an active database connection. All tag-related functionality is locked while RoboJournal is in Default State due to there being no point of reference.

In addition to the standalone Manage Tags window, the tagging system has also been integrated into the Editor as the Tag Management Pane. The Tag Management Pane conveniently allows you to tag new entries as you write them. The Manage Tags window and the Tag Management Pane can only work with one entry at a time. Since RoboJournal equally distributes tagging functionality through the classic Manage Tags window and the Editor itself (to the point of literally using the same interface for both), it does not matter which method you use to tag your entries since both ways produce identical results.

### Best Practices

RoboJournal's tagging system allows you to assign one or more descriptive labels to an entry. Once declared, a new tag becomes available to the entire journal; you can apply all existing tags to all entries as you see fit. However, each tag can only be used once in any given entry. RoboJournal does not currently make tagging suggestions based on entry content but that may change in future releases.

In all cases, you should assign tags based on entry content and/or subject matter because RoboJournal's tagging system is designed to categorize by topic. For instance, all car-related entries could be tagged with "car" or "vehicle" but not "pet". Ultimately, tag assignment is a matter of common sense. Since any given entry can address multiple subjects, it is typical for most entries to have several different tags.

RoboJournal supports the use of multi-word tags and there is no real set limit on how many tags can be assigned to each entry or how many tags the journal can hold. However, the tagging system is most effective when tags are short in length, broad (but not overly broad) in scope, and appropriate in number to the size and diversity of the journal. In other words, you should only declare a new tag if your journal's subject matter requires it since tags are meant to be shared between entries. When you search for all instances of a specific tag, RoboJournal displays all entries that currently have that tag assigned to them.

New tags should only be created if all of the existing tags are inapplicable to an entry's content or subject. When you define a new tag, you should expect to eventually use it more than once. Tags that are only used once in an entire journal are practically useless because they provide only one result during searches (and the affected entry probably would have had other tags assigned to it anyway).

### Accessing the Tagging Interface (Standalone)

Although RoboJournal now allows you to tag entries directly from the Editor, the "classic" standalone Manage Tags window continues to be an important feature. The main advantage offered by the standalone feature is speed; rather than requiring you to open an entry in the editor to alter its tag data, the Manage Tags window presents a stripped-down user interface to allow you to see which tags are active, apply new tags, or clear active ones as quickly as possible. The Manage Tags window is therefore best suited to situations where you must tag many entries at once during one session (as is the case whenever the Tag Reminder window is triggered).

The following procedure allows you to access the Manage Tags window from the RoboJournal main window (assuming a connection is active at the time). The standalone Manage Tags window can also be invoked from the Tag Reminder window (consult the "Tag Reminder Window" section for details).

1. Click to select the entry you wish to tag (indicated by the large oval in Figure 1) from the Timeline on the RoboJournal main window. Figure 1: Select the entry you wish to tag and click the Manage Tags toolbar button. Figure 2: The standalone tag window is also accessed through the Tag Reminder window that is displayed whenever RoboJournal detects untagged entries.
2. Click the Manage Tags toolbar button (as shown in the small circle in Figure 1). Alternatively, click the Manage Tags button (Figure 2) after selecting an entry from the Tag Reminder window. In either instance, the Manage Tags window is displayed:Figure 3: The Manage Tags window is always superimposed over the main window.
3. Make all necessary changes (consult "Applying and Removing Tags" for details). The Apply button near the bottom of the window is unlocked after you have made at least one change.
4. Click the Apply button to commit the changes (or click Cancel to abort the changes you have made).
5. The OK button unlocks once you have saved your changes. Click OK to close the Manage Tags window.

FYI: The Manage Tags window is always superimposed over the main window under normal circumstances. However, screenshots of the Manage Tags window in the following sections of this documentation omit the main window for the sake of simplicity.

### Accessing the Tagging Interface (From the Editor)

As previously stated, the tagging system has been fully integrated into the Editor for the sake of convenience. This new design allows you to apply tags to an entry as you write. This easy access to the tagging system is meant to get you into the habit of tagging entries in advance instead of allowing untagged entries to accumulate in your journal.

The following procedure assumes you have already opened the Editor to write a new entry or modify an existing one:

1. Click the Manage Tags toolbar button (indicated by the red circle in Figure 4) in the Editor window. Alternatively, you can click and drag the Tag Management Pane splitter to the left (RoboJournal exerts a small degree of resistance to prevent accidental expansion or collapse) to expand it. RoboJournal allows the pane to expand once you have dragged the splitter far enough to the left to overcome resistance: Figure 4: You can expand the Tag Management Pane by clicking the circled Manage Tags toolbar button or by dragging the Tag Management Pane splitter (shown in red) to the left.
2. Once triggered, the Tag Management Pane expands itself and allows you to access the tag data (if any) for the current entry:Figure 5: RoboJournal allows you to apply tags to an entry before you save changes to it.
3. Make all necessary changes (consult "Applying and Removing Tags" for details).
4. (Optional) Collapse the Tag Management Pane by toggling the Manage Tags toolbar button or by dragging the splitter back to the far right of the Editor window. Under the second method, the pane collapses itself once you have dragged the splitter far enough to overcome its resistance.

The Tag Management Pane always limits itself to a maximum width no matter how large the Editor window is. However, the width increases to compensate for larger buttons if toolbar button text labels are enabled in RoboJournal Preferences.

Unlike the standalone tag management window, the Editor's Tag Management Pane does not require you to manually commit changes to an entry's tag data. RoboJournal automatically saves/updates the current entry's tags when you post a new entry or save changes to an existing one.

## The Tag Menu and Toggle Filtering Menu

In version 0.5 and later, RoboJournal's tagging system has been completely redesigned to be much more straightforward and intuitive. The new interface is intended to streamline the task of applying or removing tags from entries; instead of adding tags one at a time from a drop-down list (as was the case in older versions) the new system makes adding tags to entries as simple as checking items from a list of all available tags.

The original tag interface design with its individual buttons was impractical for integration into the Editor window. Instead, RoboJournal 0.5 (and later) utilizes a menu-based system to prevent user interface overcrowding, especially when toolbar button labels are enabled. Under this new design, most tag-related functionality is contained within the tag menu. You can access the tag menu at any time by clicking the Tag Menu toolbar button:Figure 6: The Tag Menu toolbar button displays a drop-down list containing most of RoboJournal's tag-related functionality.

The following table addresses each item on the tag menu:

Declare new tag | This option allows you to add a new tag to the Available Tags list.
Strip all tags | This feature purges all tag data from the current entry.
Auto-tag entry (experimental) | Auto-tagging is an experimental feature that causes RoboJournal to assign tags based on the contents of the current entry's body text.
Revert Tags | This feature reverts all tag changes you have made.

The Toggle Filtering menu is displayed by clicking the down arrow immediately to the right of the Toggle Filtering button (Figure 7). The menu only contains the Clear Tags list item, which erases the current search pattern in the Filter Tags field.Figure 7: The Toggle Filtering menu contains items specifically related to tag filtering.

## Declaring a New Tag

Journals are deliberately created with no pre-existing tag data. RoboJournal leaves tag designation up to you because each journal is unique (therefore making it impossible to successfully anticipate your needs with a set of pre-defined tags) and you would know best about what is required. Once defined, each new tag becomes available to the entire journal.

As stated in the previous section, nearly any word can be used as a tag but it is always best to use short one-word tags that are applicable to several entries. The only reserved word you may not use for a tag under any circumstances is any variant of "Null" (i.e. null, Null, NULL, etc.) because that word has special properties in the RoboJournal tagging system. "Null" is a type of invisible tag that is used for entries that were previously tagged but currently have no tag data assigned to them (brand-new entries that have never been tagged are treated differently). Entries tagged with "Null" produce a response of, "No tags for this post" in the main window's Entry Output Pane. RoboJournal produces an error message if you attempt to declare "Null" as a tag.

The following procedure demonstrates how to declare a new tag in RoboJournal. The process is exactly the same for the standalone Manage Tags window and the Editor's Tag Management Pane (the screenshots show the Manage Tags window for the sake of simplicity)

1. Click the Define Tag button on the Manage Tags window.Figure 8: The Define Tag toolbar button launches a text prompt that allows you to define a new tag.
2. RoboJournal displays the Enter the new tag: dialog. Enter the new tag into the text box:Figure 9: Enter the new tag into the provided text box.
3. Click the OK button in the Enter the new tag: dialog to continue (or click the Cancel button to abort).
4. RoboJournal adds the new tag to the very top of the Available Tags list and automatically selects it:Figure 10: Newly-defined tags are inserted at the top of the list and are marked with a green plus-sign indicator.

FYI: Newly-defined tags are not permanent until they have been assigned to at least one entry. Therefore, you should not define a new tag until you actually need it (otherwise it will be discarded once you close the Manage Tags window).

## Applying or Removing Tags

RoboJournal's tagging interface has been revamped in version 0.5 to make applying or removing tags as simple as possible. The old menu-based interface from 0.4.1 and earlier has been deprecated in favor of a checkbox-based system. Every available tag in the journal is represented as a list item with a checkbox next to it. For ease of identification, active (checked) tags are shown in bold, colored font. The specific color used for active tags depends on your operating system; RoboJournal uses your system-level selected text background color as a base and then darkens it slightly to improve contrast and readability.

To apply a tag to an entry, click once on the corresponding list item (the box to the left of the tag name checks itself automatically):Figure 11: Clicking an inactive tag in the list applies that tag to the current entry.

Each time the Manage Tags window or the Editor is displayed, RoboJournal automatically marks all active tags so you will know which ones are already in use. To remove a tag from an entry, simply click the appropriate list item once (the checkbox clears itself automatically):Figure 12: Clicking an active tag (shown by the red circle) removes that tag from the current entry.

FYI: To apply or remove a tag, you must click the text in the appropriate row instead of clicking the checkbox itself.

## Other Tag-Related Features

RoboJournal 0.5 offers new features that are designed as safety features or allow you to do bulk operations much more quickly.

### Revert Tags

The Revert Tags feature provides a way to immediately undo all the changes you have made to an entry's tags up until the time you commit the changes (i.e. before you click the Apply button in the standalone Manage Tags window or you save the entry that is currently open in the Editor). The Revert Tags feature works by resetting the tag list with the data that is currently saved in the database. RoboJournal refers to all unsaved tag changes as the "history".

Since reverting changes requires the history to contain at least one change to undo, the Revert Tags toolbar button is always kept locked—as shown in Figure 1—until some other action (like applying or removing a tag) triggers a history change. Clicking the Apply button in the standalone Manage Tags window applies all changes. Once the new data has been saved, RoboJournal clears the history and locks the Revert Tags toolbar button once more because the previous tag data no longer exists.

The following procedure assumes the Manage Tags window is already displayed or the Tag Management Pane is visible in the Editor:

1. The Revert Tags menu item is locked by default. Making one or more changes to the current entry's tag data establishes a history, which causes the Revert Tags menu item to unlock.
2. After you have established a history, click the Tag Menu to display the tag operations menu: Figure 13: The Revert Tags button unlocks itself after you have made at least one change to an entry's tag data.
3. Click the Revert Tags menu item (shown in Figure 13).
4. RoboJournal asks you to confirm your decision to discard all changes you made to the tag data. Click the Yes button to continue or click No to abort.
5. If you chose to continue, RoboJournal restores the saved tags for the selected entry:Figure 14: In this example, "tips" is no longer selected after you have reverted the entry's tags (compare with Figure 13).

RoboJournal only allows you to click the Cancel button (exiting the Manage Tags window without saving) because there are no changes in the history to apply after reverting the tags back to their original state.

### Strip Tags

RoboJournal's new Strip Tags feature allows you to quickly remove all tags from an entry if it ever becomes necessary to do so. The Revert Tags feature can undo this operation. The following procedure assumes the Manage Tags window is displayed or the Tag Management Pane is visible in the Editor:

1. Click the Tag Menu toolbar button to display the list of tag operations. Once the list is visible, click the Strip all tags list item (circled in Figure 15):Figure 15: Accessing the Strip Tags menu item on the Tag Menu.
2. RoboJournal asks you to confirm your decision to strip all tags from the entry. Click the Yes button to proceed or click No to abort.
3. If you chose to continue the operation, all tags are now unchecked:Figure 16: The strip tags operation removes all tags from the current entry. Clicking the Apply button saves the changes.
   If you are accessing the tags from the Editor, saving the current entry is equivalent to clicking the Apply button.

   Steps 4—5 are only applicable when you are using the standalone Manage Tags window. If you are completing this procedure through the Editor's Tag Management Pane, any changes to the tag data are not finalized until you save the current entry (closing the Editor without saving rejects all tag changes as well).

4. The Apply button unlocks itself once you have made changes to the tag data. To finalize the decision, click Apply. If you wish to undo the changes, click Cancel or use the Revert Tags feature.
5. Clicking Apply unlocks the OK button. Click OK to close the Manage Tags window.

### Filtering Tags

Your journal is likely to accumulate a large number of tags over time. Since RoboJournal normally displays all available tags in the Available Tags list, finding a particular tag can prove difficult even though RoboJournal always sorts your journal's tags in alphabetical order. RoboJournal 0.5 (and later) addresses this problem by allowing you to filter the tags list to display only the tags that match certain criteria.

The filtering system works by scanning the Available Tags list for tags that contain a user-defined string. This scan is care-insensitive and matches all tags that contain the specified pattern. Each time a matching tag is found, RoboJournal appends it to a list. Once all the tags have been scanned, RoboJournal displays the list of matching tags instead of the full Available Tags list. This feature allows you to find the desired tag(s) much more quickly because the list of matches is usually much shorter than the full list of tags.

The following procedure assumes the Manage Tags window is displayed or the Tag Management Pane is visible in the Editor:

1. Click the Filter Tags field (indicated in Figure 14) to transfer focus to it:Figure 17: When empty and unfocused, the Filter Tags field displays "Filter Tags" as placeholder text.
2. Once a cursor appears in the field, enter the text you wish to use as a filter. As you enter text, RoboJournal automatically updates the contents of the Available Tags field:Figure 18: Once you have set a filter, RoboJournal only displays the tags that match.
   For instance, the Available Tags list in Figure 15 displays tags that contain at least one occurrence of "ta".
3. (Optional) Click to select the tags you wish to use from the filtered list.
4. (Optional) Un-toggle the Toggle Filtering button (by clicking on it) to display the full Available Tags list again:Figure 19: Un-selecting the Toggle Filtering button clears the Filter Tags field and causes RoboJournal to display the full tag list again.

## Tag Reminder Window

RoboJournal takes additional measures (starting in version 0.4.1) to ensure that all entries in your journal are properly tagged because untagged entries are invisible to tag searches and therefore can only be found through pattern matching. The Tag Reminder window is essentially a "nag screen" that asks you to tag existing entries at the start of each session. The purpose of this feature is to encourage you to use the tagging system; the notification is deliberately designed to be annoying in the hopes that you will soon get in the habit of tagging new entries immediately after you write them in order to prevent the Tag Reminder window from being displayed at all.

If RoboJournal finds any untagged entries, it adds them to a list and displays them on the Tag Reminder window immediately after login (the Tag Reminder window is not displayed if RoboJournal fails to find any untagged entries):Figure 20: The Tag Reminder window is shown only if RoboJournal detects untagged entries.

The Tag Reminder window list shows all entries that currently have no tag data. This is limited to entries that have never been tagged before. Entries that were tagged at some point and have subsequently had their tag data cleared (i.e. entries tagged with "Null") are not included in the search because RoboJournal assumes you had a reason for clearing the previous tag data. This search covers all entries in the journal from newest to oldest and ignores the current entry range limitation. As such, you may be asked to tag very old entries that are outside the visible entry range you specified in RoboJournal Preferences.

You can click the Close button to postpone the tagging procedure. This hides the Tag Reminder window for the remainder of the session but it will be displayed again during the next login. You can permanently suppress the Tag Reminder window by unchecking the Display this notification during the next login (if necessary) checkbox before clicking the Close button. This prevents the Tag Reminder window from being displayed ever again even if the journal still contains untagged entries. (you can also suppress or re-enable the Tag Reminder window through RoboJournal Preferences at any time).

Alternatively, you can select any entry from the list and click the Manage Tags button to apply tags to it (consult Figure 2 in the "Accessing the Tagging Interface (Standalone)" section for details). The Entry Title column in the list gives the title of an untagged entry while the value in the Date column provides a point of reference for the entry in question. After you tag each entry, the list automatically refreshes and the current count (x entries need to be tagged.) indicator is reduced by one. The Tag Reminder window automatically closes after you have tagged every item on the list. Once cleared, the Tag Reminder window will not be displayed at the start of the next session (unless you introduce more untagged entries during the current session).

Copyright © 2014 by Will Kraft. All parts of the RoboJournal Documentation are subject to the terms of the GNU Free Documentation License.