for version 0.5

# RoboJournal Preferences

## Sections

## Preferences Overview

RoboJournal's preferences system has been completely redesigned into a modular interface (starting in version 0.4). This new design offers vastly improved efficiency and increased potential for expansion in the future. The new design groups all available options into several categories depending on their specific purposes. Each category is officially known as a "page". To switch to a different page, click on its name in the list on the left side of the Preferences window. The title of the Preferences window indicates which page you are currently viewing (i.e. Preferences -- General; Preferences -- Appearance, etc.).

Since each page is inherently a different size (due to each page having a different number of options on it), RoboJournal's Preferences window automatically pads out the extra space on a page if necessary to ensure that everything fits properly without distortion. If a page is larger than the available display area, the Preferences window utilizes vertical scrollbars to allow you to access controls that would otherwise be inaccessible due to being placed outside the bounds of the window. These scrollbars are only used if a page does not fit the current window size; to eliminate the scrollbars, you must resize the Preferences window to the point where it is large enough to accommodate the entire page. RoboJournal automatically stretches each page on the horizontal axis to fit the available space (thereby eliminating the need for cumbersome horizontal scrollbars).

The Preferences window is fully resizable; you can resize the window by dragging any side or corner of the window border into a more appropriate position. Whenever you resize the window, RoboJournal automatically records the size changes in your configuration file and automatically loads the new size each time the window is subsequently displayed. If the new size data becomes unavailable for some reason, the Preferences window automatically reverts to its original size (575x525 pixels).

## General Page

The General page contains options that control the behavior of the entire program. The General page is always shown by default whenever the Preferences window is displayed. Otherwise, the General page is displayed when you click the General list item on the left side of the Preferences window:

Figure 1: RoboJournal Preferences Window — General Page

### Global Preferences

All options in the Global Preferences group affect underlying program behavior and appearance.

Always suggest default settings | If checked, this option requires RoboJournal to automatically populate affected form fields with default settings whenever a form capable of using these settings (e.g. New Connection dialog) is displayed. This action is not the same as mandating default settings because it is often possible to override the defaults on a form-by-form basis.

Always show confirmation dialogs

This security measure forces RoboJournal to display all confirmation dialogs in situations where they are supposed to be triggered. This practice helps prevent accidental deletions and other data loss in situations where carelessness can cause problems. You are strongly encouraged to leave this option enabled at all times!

However, be advised that some confirmation dialogs are mandatory and are always shown (if triggered) whether this setting is enabled or not.

Show labels on toolbar buttons | If checked, this setting causes every toolbar to display their buttons with both icons and text labels (default setting). Unchecking this option causes all toolbar buttons to display their icon only. Some users may prefer icon-only mode because it saves space and usually eliminates the need for the toolbar overflow menu.
Display current journal name in title bar | This feature simply shows the name of the current journal in the main window title bar (i.e. sample_journal - RoboJournal). If unchecked, the title bar simply says, "RoboJournal" whether a connection is active or not.
Display alternating row colors in lists | This option causes all lists (specifically the Timeline and the search output list) to use alternating background colors. This looks good on some color schemes but is completely unreadable on others (so you may wish to disable it in some situations).
Display Tag Reminder window during login | If checked, this option causes RoboJournal to display the Tag Reminder window immediately after login under the appropriate conditions (i.e. if the journal contains one or more untagged entries). The Tag Reminder window is completely suppressed while the Display Tag Reminder window during login box is unchecked.
Toolbar docking position | This drop-down list controls the default location of the main window's toolbar. This setting is persistent between sessions. It is possible to change the location of the toolbar during runtime by dragging it to a new position or using the setting in the Window → Toolbar position list, but these changes revert to the default setting the next time RoboJournal is used.

### Backend (Database)

The backend option controls which database engine RoboJournal should use. For instance, choosing "MySQL" from the list causes RoboJournal to switch to MySQL mode. You must switch the backend before you can work with a different type of database (like SQLite). RoboJournal can use only one backend at a time.

### Date and Time

The Date and Time group controls all settings that determine how RoboJournal processes date and time data.

Display day of week when entries were made | If checked, this setting causes RoboJournal to display the day of week along with the regular date and timestamp (i.e. Wednesday, 12/26/2012 at 12:00 am).

Record the time when entries are made

This setting requires RoboJournal to record the time when entries were made. Timestamps are displayed along with other relevant data in the entry header.

RoboJournal does not display timestamps if this setting is disabled. RoboJournal will not store timestamps for entries made while this option is disabled. Entries with no timestamp data are indicated as being made at an "[unknown time]". There is currently no way to update timestamps on existing entries (other than manually editing the database).

Use 24-hour clock in timestamps | If enabled, this setting causes datestamps to be shown in 24-hour format (i.e. 16:00 instead of 4:00 pm).

Preferred date format

This drop-down list determines which date format RoboJournal should use in the entry header and Chronological Entry List. Supported formats include:

USA
  MM-DD-YYYY; January 1, 2013 (used throughout the United States).
European
  DD-MM-YYYY; 1 January, 2013 (used primarily in Europe).
International Standards Organization 8601
  YYYY-MM-DD; 2013, January 1 (used world-wide, especially in scientific context).

Certain date-related functions in RoboJournal (most notably the date column in the search results) override the preferred date format setting. These exceptions use the date format setting of your operating system instead.

## Journal Page

The Journal page contains options that govern journal behavior and general user preferences. The Journal page is displayed when you click the Journal list item on the left side of the Preferences window:

Figure 2: RoboJournal Preferences Window — Journal Page

### Entry Settings and Range

This group contains settings that define the current entry range (the timespan of entries shown in the Timeline). The entry range feature limits how many entries RoboJournal shows at once in order to keep the Timeline at a manageable length. For instance, setting an entry range of two years causes RoboJournal to show all entries made within the last two years (including the current year) in the Timeline. As time progresses, older entries gradually move out of range and are no longer displayed. Disabling the entry range causes RoboJournal to display all entries from the current journal (regardless of age).

Limiting the entry range also offers some performance benefits. Requiring RoboJournal to display the entire journal can be slow if there are several full years to process each time the Timeline needs to be displayed or updated. On the other hand, RoboJournal is able to generate the Timeline much more quickly if the entry range is set to 1-2 years. Entries that are outside the current range can still be found through the search tool, so there is no reason to display old entries unless you need all of them available at any given time.

The Entry Settings and Range group also has options for miscellaneous behavior associated with entries.

Show all entries in journal | This setting determines whether the entry range function is enabled. Checking this box disables the entry range and year range indicator features (as shown in the screenshot above).
Show entries from the last: | This list sets the current entry range from 1-10 years. If the entry range function is disabled, this list locks and becomes unavailable.
Show year range indicator on statusbar | This feature (if enabled) causes the current entry range to be displayed on the main window statusbar along with the current entry count (i.e. "x Entries : y Years"). If the entry range function is disabled, this checkbox locks and is unavailable.
Select entry node icon | This allows you to select the icon used to represent individual entries in the Timeline and search output list. By default, RoboJournal represents individual entries with a pencil icon.

### User Information

The User Information group contains settings that directly relate to your user account:

Your full name (as you would like it to appear)

This text box is meant to display your full name as you would like it to appear in the entry header. For example, you would probably set your full name to "John Doe" (or something similar) if your username were "john_doe". Unlike the username assigned to your journal, this value may contain spaces and uppercase characters.
Your username is displayed in the header instead if this field is left blank. This field is normally populated during first-run but its value can be changed at any time.

Select your gender | This setting determines which avatar icon (male or female) is displayed next to your username in the main window status bar. This setting is initially determined during first-run but its value can be changed at any time.

### Highlighting

The options in the Highlighting group control how RoboJournal highlights occurrences of a search term. This feature is designed to mimic traditional highlighter pens; all instances of a search term in an entry are displayed with a bright colored background to make them easier to locate in the text.

Highlight current search term | If checked, this option instructs RoboJournal to apply highlighting to searches.
Select highlight color | This list allows you to select the highlight color. The square box for each item on the list displays an approximate sample of that particular color.

### Behavior

The Behavior group contains general options that control journal behavior and affect how journal content is rendered. These options work on a global scope; the same settings govern every single journal RoboJournal comes into contact with instead of being limited to the journal that is currently open.

Group journal entries by day

This option gives you the ability to sort entries by day instead of by month (which is the default behavior). Under normal conditions, entries are displayed with the date and title merged together (i.e. "January 1: Sample Entry"). Grouping entries by day adds another sub-category; in the aforementioned example, the entry "Sample Entry" would be a separate node listed under "January 1" instead of the two being merged together into a single node.

This option is useful if you frequently post more than one entry per day and would like greater control of how such entries are displayed.

Show title for current journal entry | If checked, this option causes the title of the current entry to be included when the entry is displayed in the output pane.
Display most recent entry automatically | If checked, RoboJournal displays the most recent entry in the output pane immediately after you log in. If unchecked, Robojournal simply waits for you to select the entry you wish to view from the Timeline.

Display full name (instead of username)

This option determines whether RoboJournal displays the user's full name as it is written in the Your full name (as you would like it to appear) text box. This checkbox automatically disables itself and locks if the full name value is cleared. Inversely, this setting re-enables itself if a new full name value is entered. You can also disable this setting manually and leave the full name value intact.

Double-click an entry to open it in the Editor | When this option is enabled, RoboJournal allows you to edit the current item when you double-click on it. This is meant to be an easy way to make changes to existing entries.

## Editor Page

The Editor page contains settings that affect the behavior and performance of the Editor window, including post-processing features, appearance settings, and spell check integration. The Editor page is displayed when you click the Editor list item on the left side of the Preferences window:

Figure 3: RoboJournal Preferences Window — Editor Page

### Post Processing

The options in the Post-Processing group manipulate the text of new or revised entries after they have been saved. These functions perform necessary corrections and cleanup operations to body text as a means to improve appearance and fix common errors. In all instances, the post-processing functionality looks for specific patterns and then applies changes to all matching instances of those patterns it detects.

Since these changes are only applied after an entry is saved, post-processing does not affect old entries that were made before the post-processing features were introduced or were made while post-processing features were disabled. Post-processing is applied once after an entry has been saved in order to improve efficiency. Therefore, the only way to apply post-processing to old entries is to open them in the editor and then save them again.

Remove unnecessary whitespace from entries

This function removes extra line breaks between paragraphs and trims extra space from the bottom of the entry. Whitespace removal also eliminates extra spaces between words (since all words should only be separated by one space).

This feature is still semi-experimental and may occasionally produce unexpected results (a reliable fix is to edit the entry and save it again).

Use HTML-compliant dashes and hyphens

This feature ensures the correct use of dashes and hyphenation in entries. These are impossible to add with a regular keyboard (without resorting to key combinations) so this function does it for you. It replaces the common workaround for long dashes (i.e. --) with HTML-compliant long dash characters (i.e. — ) and removes any unnecessary spacing. Dashes between numbers are replaced with a proper medium-length dash (i.e. 1–2 instead of 1-2).

Use smart (curly) quotation marks | This feature replaces instances of "straight" quotation marks with “curly” quotation marks. Post-processing also affects grammatical contractions and possessive nouns (i.e. won't becomes won’t; John's becomes John’s).
Apply miscellaneous formatting options | Miscellaneous formatting applies post-processing features that are not easily categorized. These convert three or more consecutive periods into a true ellipsis character (…) and formalizes number notation (i.e. 12th, 101st).

### Appearance

The Use custom theme font in the editor option causes the editor to use the same font/font size as the entry output pane in the main window. This improves consistency and allows you to preview how your entry will look once it has been saved. This option is locked (as shown in the screenshot above) if RoboJournal is not presently configured to use a custom style.

### Spell Check

RoboJournal's spell check feature scans the contents of the editor each time a new word is entered and applies a wavy red underline to all spelling errors it detects. Spell check is not automatically enabled during first-run. To enable spell check, you must first select a dictionary for it to use from the drop-down list.

Enable spell check functionality | This option controls whether spell check should be used in RoboJournal (if checked, this option automatically triggers the dictionary selection function). All spell check functionality remains disabled while this option is unchecked.

Use System-Level Dictionaries

Non-Windows operating systems like Linux usually have built-in dictionaries. These dictionaries are automatically installed along with everything else in the operating system and are meant to be system-level resources that multiple applications can utilize. If the Use system-level dictionaries option is enabled, RoboJournal favors the global OS dictionaries over its own; each time the configuration window is opened, RoboJournal scans your computer and lists all system-level dictionaries it finds (in any language) in the Select spell check dictionary list. You can then select any one of these to use as your spell check dictionary.

Select spell check dictionary

This combo/list box contains the path to the current dictionary file. This field is locked while spellcheck is disabled.
When spell check is enabled, this field automatically populates itself with all known dictionaries.You can then select the dictionary you want to use from the given options or click the Browse button to the immediate right of the field to look for a different one.

It is no longer necessary to manually browse for a dictionary whenever you enable spell check because RoboJournal now does this for you in versions 0.5 and later. On Windows, RoboJournal automatically selects the US English dictionary located in the .robojournal configuration folder in your user profile folder. On Linux, RoboJournal searches for and returns a list of global system-level dictionaries, assuming you have any installed on your system. If you do not have any system-level dictionaries, you can rectify this problem by using your package manager to install some Hunspell-compatible dictionary packages. If you have disabled the Use system-level dictionaries option on Linux, RoboJournal attempts to use the .robojournal folder's US English dictionary in a manner similar to the Windows default behavior.

### User-Defined Words

RoboJournal 0.5 (and later) stores all custom words you have defined in a file called user_defined_words.txt. This file is located in the hidden .robojournal folder in your home folder (Linux) or your user profile (Windows). The spell check system does not mark your custom words as being misspelled, even if they are not in the main dictionary you are currently using. This feature allows you to gradually assemble your own dictionary of non-conventional words that the spell checker should ignore.

Click the Manage user-defined words button in the Spell Check group. This action displays the Manage User Defined Words window: Figure 4: The custom words interface

This interface gives you full control over your custom word list so there is no need to ever edit the user_defined_words.txt file manually.

- The Add Word button displays a dialog that allows you to declare a new word. This has the same effect as adding a new word through the Editor's spell check interface.
- The Delete Word button removes the currently-selected word from the list. At present, there is no undo function, so if you accidentally delete a word you will need to add it again.
- The Modify button allows you to make changes to the currently-selected word through a dialog interface.

## Appearance Page

The Appearance page controls the appearance and font settings of rendered entries in the output pane on the main window. The Appearance page is displayed when you click the Appearance list item on the left side of the Preferences window:

Figure 5: RoboJournal Preferences Window — Appearance Page

### Enabling Custom Styles

All custom styles are disabled by default. Instead, RoboJournal uses a generic sans-serif font for text and system colors to indicate the header/highlighted text. The default settings are generally consistent with the overall system theme currently in use on your computer.

The entire Style Options group is locked while the Use custom font and/or background image box is unchecked. Checking this box unlocks the group and allows you to define custom settings. Certain background-related options (Tile background image and Apply background image to entry list) will remain locked indefinitely unless a background image has been set.

#### Selecting a Font Color

Use the following procedure to select a font color:

1. Click the Choose button on the Appearance page in the RoboJournal Preferences window. The Select Color dialog is displayed:Figure 6: Select Color dialog box. This design is universal across all operating systems.
2. Select a preset color from the Basic colors list or use the targeting crosshair to select a custom color from the full spectrum (use the vertical slider on the far right side of the dialog to set color brightness).
3. Click the OK button to apply the selected color.

FYI: The color selected through the above procedure is also used for the date box header and tag header backgrounds. Because of this, both headers display their text in the inverse color of their backgrounds in order to ensure maximum contrast and readability.

#### Setting a Background Image

1. Click the Browse (folder) button in the Style Options group:Figure 7: Browse button marked for identification.
2. The Choose Background Image file dialog is displayed:Figure 8: Choose Background Image dialog.
   FYI: The Choose Background Image dialog does not resemble Figure 8 on operating systems other than Windows 7.
3. Navigate to a folder that contains image files (*.png, *.jpg, *.bmp, or *.gif) and select the desired image by clicking on its filename.
4. Click the Open button.
5. Your choice is now displayed in the Select background image from disk field. The background is applied after you click the OK button in the RoboJournal Preferences window.
6. (Optional) Click the Tile background image checkbox if you want the background image to be repeated in the entry output pane.
7. (Optional) Click the Apply background image to entry list checkbox if you want to apply the background to the Chronological Entry List.

#### Clearing a Background Image

1. Click the Clear Background button in the Style Options group: Figure 9: Clear Background button marked for identification.
2. The current background image is removed. This change is applied after you click the OK button in the RoboJournal Preferences window.

FYI: This action causes all background-related options in the Style Options group to uncheck themselves and lock. Any background image in the Timeline will persist until the current session has ended.

### Style Options

The following table lists and provides a description of each object in the Style Options group.

Select font and base font size | The font and font size lists control which typeface is to be used in Journal entries and its point size. This font/font size is also used in the Editor if the Use custom theme font in the editor box on the Editor page is checked.
Font color | This value sets the current font color. Colors are specified in the 6-character hexadecimal format (i.e. #000000) commonly used on the web.
Select background image from disk | This text field contains the path to the current background image.
Tile background image | If checked, this option causes the background image to be tiled on the X and Y axis in the entry output pane. If unchecked, the current background image is only displayed once without repeating. This option is locked if no background image has been set.
Apply background image to entry list | If checked, this feature applies the background image to the Timeline. Once enabled, this feature takes effect immediately after clicking the OK button on the RoboJournal Preferences window. However, disabling this feature requires you to restart RoboJournal before the change will take effect.
Use system colors in date/timestamp box | This feature overrides the rule that applies the current font color to the background in the date/time header and tag header. If checked, this option forces the use of system colors even when a custom theme is in use; this is ideal for those who wish to use a custom font but retain default colors/background settings.

## Export Settings Page

The options on the Export Settings page allow you to control how exported entries are processed. Since this function takes database content and uses it to create documents in both HTML and plain-text format, any changes made to the options on this page will not affect entries that have already been exported.

The Export Settings page is displayed when you click the Export Settings list item on the left side of the Preferences window:

Figure 10: RoboJournal Preferences Window — Export Settings Page

### HTML Behavior

The HTML Behavior group contains options that affect the visual appearance of exported HTML documents. As such, these settings are entirely optional. These options are not applied to plain text files.

Use rounded corners on date/timestamp header | If checked, this option causes the entry exporter to apply rounded corners (using Cascading Style Sheets) to the date/timestamp header in both the single entry export and full journal export functions. This function is purely decorative and may not be visible on older browsers.

Use system colors in exported HTML files

If checked, this function applies the system colors for highlighted text (foreground) and selected color (background) to exported documents. The purpose of this setting is to allow the exported text to more closely resemble the entry as it is shown in the entry output pane.

If unchecked, black text is used for the foreground and a neutral gray is used for the background.

### Fonts and Units

RoboJournal supports separate fonts for headers and entries in exported HTML documents. In normal situations, sans-serif font should be used for headers and serif font for text. Fonts are chosen through the Preferred HTML Fonts group while sizes/units are determined by the Font Sizes and Units group.

To select a font, click on the Select header font or Select body text font lists (depending on which one you want to change). The font lists contain all fonts installed on your system; scroll through the current list until you locate the desired font. On Windows, RoboJournal uses Verdana (header) and Times New Roman (body) as the default fonts.

Fonts can be displayed in point size (pt) or em units. Point size is a fixed size traditionally used in word processing and print media; 1pt is generally equivalent to 1/72 inch. Em units are more scalable than pt and refer to current font size; 1em = 12 pt, 2em = 24pt, etc. Even though 1em is always equivalent to 12pt, the apparent size of em increases in proportion to general font size; 1em appears larger under a base font size of 120% than under a size of 100%. In contrast, point size always remains consistent regardless of base font size. Generally, you should use pt if you intend to print your exported journal entries while em units are more appropriate if readability across different devices is your highest priority.

The available font sizes depend on the unit currently in use. Changing the unit assigned to header or body fonts causes the affected available size list to refresh and display new values appropriate for that unit. Select the desired value from the list to set a font size.

### Export Preview

After changing fonts, font sizes, font units, or HTML Behavior settings, you can preview your changes by clicking the Preview Export Settings button. The Export Preview window is displayed:

Figure 11: The Export Preview window provides a faithful representation of the current export settings. The Export Preview window allows you to "test" new settings before saving them. The current settings of the Export Settings page are used to render a sample entry that contains a title, date/timestamp header, and several paragraphs of body text. This feature is designed to be as accurate as possible. The body text is an excerpt from the classic Latin Lorem Ipsum text used throughout the print industry since the 1500s. Click the Close button to exit the Export Preview.

## MySQL Settings Page

The MySQL page contains options that define and control all settings related to MySQL. The MySQL Settings page is displayed when you click the MySQL Settings list item on the left side of the Preferences window:

Figure 12: RoboJournal Preferences Window — MySQL Settings Page

### Default Account

The Default Account group contains options that determine the default account for MySQL connections, including the default Host, Database, Port, and Username to use if RoboJournal is configured to always suggest default settings. The Default button (to the right of the Port field) is an easy way to reset the Port field to its default value of "3306" in case you previously changed it and need to change it back.

RoboJournal 0.5 (and later) offers an easy way to change the default database. Find the database you wish to use as your default in the List of Known Journals (Figure 13) and double-click its entry node. Once you have done so, your chosen database is "promoted" to the new default database (RoboJournal asks you to confirm your decision if confirmation dialogs are enabled). Once you have set a new default, the old default database is still considered to be a favorite unless you decide to clear its checkbox.

### Favorite Journals

RoboJournal 0.5 introduces the "Favorites" system for MySQL journals. Under this new design, RoboJournal automatically scans the current host for databases bound to your user account every time you log in, create a new journal, or use the Journal Selector. This list of databases is stored in the ".robojournal" folder in your home directory along with your RoboJournal configuration file.

The Favorites system records each journal (and the host it is associated with) only once to ensure there are no duplicate entries in the list. Each time a new database is created or detected, RoboJournal automatically appends it to the list of databases associated with your user account. Collectively, this data is formally called the List of Known Journals. The List of Known Journals is unique for each user. Some users may have only one journal while others may have dozens of them for various purposes.

Because displaying the full List of Known Journals in the New Connection dialog becomes impractical as the list increases in size, RoboJournal allows you to select one or more items from the list to be your "favorites". The favorite journals populate the Journal drop-down list on the New Connection dialog (the current default journal is always considered a favorite). For maximum effectiveness, your favorite journals should be the ones you use most frequently. All favorites are represented by a checked item in the List of Known Journals on the MySQL Page in RoboJournal Preferences:Figure 13: The MySQL Settings page conveniently displays all known journals (and their hosts) that are associated with your user account.

To select a journal as a favorite, click the checkbox next to its name in the list. To un-favorite a journal, clear the checkbox next to the appropriate entry. RoboJournal saves your changes once you click the OK button on the Preferences window. If a connection is currently active, RoboJournal takes this opportunity to scan for journals that no longer exist and automatically removes any such journals it finds from the List of Known Journals.

The default journal (for instance, "journal1" in Figure 13) is always selected as a favorite because it is the journal you connect to most frequently. Also, forcing the default item to be a favorite guarantees that there will always be at least one item in the New Connection window's Journal list. For ease of identification, the default journal is represented with a gold-colored database icon and bold text.

### Security

Enabling the Allow root logins on host option overrides the security protocol that prevents users from logging in as the MySQL root user. This option should not be used unless absolutely necessary since the root account has full control over all database functions (including those which have the potential to be harmful). By design, RoboJournal places restrictions on regular user accounts for security purposes.

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