RoboJournal Documentation

for version 0.5

Exporting Journal Entries

Sections

Overview

RoboJournal stores all journals as databases. Databases like MySQL are not discrete files on your hard drive; instead, they are abstract entities you work with through an intermediary program like RoboJournal. The intermediary program relays data between the client (your computer) and the actual journal database residing on the host. While the journal appears to be on your computer, this is not truly the case unless you are running the database server on localhost. Since the journal databases are abstract entities, it is normally difficult to extract data from them unless you dump the entire database to disk as a file (the most common backup method). Fortunately, RoboJournal provides a way to directly extract journal content in a form that can be easily backed up or copied.

To begin, select the entry you wish to export (or any entry, if you wish to export the entire journal) and click the Export Entry toolbar button.Figure 1Figure 1: Select an entry (indicated by the large oval) and click the Export Content toolbar button to display the Export Content dialog.

This action displays the Export Content window:

Figure 1Figure 2: The Export Content window is displayed with the selected entry already pre-loaded.

RoboJournal's export functionality has been dramatically improved in version 0.5. The new design features a page-based interface, much like the new Journal Creator and the new Preferences window introduced in version 0.4. The Export Content window offers a menu with three items on the left side of its interface with its remaining space devoted to options related to the currently-selected item. Unlike the old entry exporter (which separated functionality by use of a tabbed widget in a way that could potentially be confusing) the new design separates functionality by page; each page is dedicated to a a specific type of export function.

The Export Content window always displays the Export single entry page by default. You can switch to a different page at any time by clicking a different item on the list. When you click the Export button, RoboJournal applies actions that are relevant to the current page only (all settings on inactive pages are ignored).  The following sections describe the various pages (and their functions) in greater detail.

Exporting a Single Entry

When initially opened, the Export Content window is automatically configured to export the entry you previously selected from the Timeline on the RoboJournal main window: Figure 3Figure 3: The "Export Single Entry" page allows you to export the current (selected) entry from the main window.

If you need to change any of the settings (including file type or export destination), you must do so before beginning the export operation. Exporting a single entry is designed to be extremely simple since most configuration requirements are pre-set in advance. The available options control the output file properties.

Generally, you only need to click the Export button (shown in Figure 3) after selecting the entry you wish to export from the Timeline on the RoboJournal main window. The Export Content window provides output and automatically closes once its task is finished.

Single Export Options

The following table explains each option on the Export Single Entry page in greater detail:

Filename The Filename field determines what name the entry content is saved under on your hard drive. This field is read-only by default and cannot be edited directly unless the Allow custom filename option is enabled.
Export Location The Export Location field lists the path to the folder where the output file will be saved. Click the Browse button to the right of this field to select a different folder.
Export Format The Export Format options determine which type of file is created during the export operation. The HTML option produces a HTML4-compliant document that is viewable in any web browser. The Plain text option produces a text file that is compatible with any text editor (e.g. Vim, Notepad, Emacs, etc.).

For best results, you should use HTML output because it preserves all document formatting (bold, italic, etc. text) while plain text output does not. As such, the option you should choose depends on your requirements.

Include entry date in filename This option appends the current date, in day of week_mm-dd-yyyy format, to the filename. For best results, you should leave this option enabled each time you export an entry.
Include journal in filename If checked, this option inserts the journal name at the beginning of the Filename field (i.e. journal name_entry title_entry date). You should leave this option enabled for best results because the resulting filename makes it easy to group exported entries from the same journal together and it provides a way for you to easily recognize which journal an entry came from.
Allow custom filename When checked, this option allows you to directly edit the Filename field's contents. You should enable this feature if it is necessary to assign a custom filename to an output file.

Exporting the Entire Journal

In addition to exporting entries one at a time, RoboJournal also allows you to export an entire journal at once. This task can be done in two different ways. RoboJournal can merge each entry into a single large file (the "original" method featured since version 0.3). In version 0.5, RoboJournal introduces a new bulk export method where a journal can be exported as a set of discrete files. This new feature produces the same results as manually exporting the entire journal one entry at a time but is much more efficient and convenient. Under this new method, each entry is saved individually and is placed with the others in a predetermined destination folder bearing the name of the journal and the export date.

You can access the bulk-export function through the following procedure:

  1. On the RoboJournal main window, select an entry from the Timeline and click the Export Content toolbar button (as shown in Figure 1) to display the Export Content window. It does not matter which entry you choose to begin this process.
  2. The Export Content window is displayed. Select the Export Entire Journal list item on the left side of the Export Content window to display the appropriate options:Figure 4Figure 4: The "Export Entire Journal" page allows you to output the contents of an entire journal in one simple process.
  3. Adjust the options in the Export Location, Export Format, and Export Options groups if necessary. Each of these settings and their effects are addressed in-depth in the Bulk Export Options section. The default configuration produces a single HTML-based file (with the journal name and the export date in the filename) with all journal entries arranged in descending order.
  4. Click the Export button to continue. The Export Content window provides output and automatically closes once its task is finished.

Bulk Export Options

The following table contains a full explanation of all options that can be applied to bulk export operations and the effects each option has on the output file(s):

Filename* The Filename field determines what name the entry content is saved under on your hard drive.
Export location This field determines where the output file is stored. If the Keep individual entries separate option is enabled, the output files are stored in a custom folder (bearing the journal name and the export date) within the directory specified in the Export location field. Click the Browse button to the right of this field to select a different folder.
Export Format The Export Format options determine which type of file(s) are created during the export operation. The HTML option produces HTML4-compliant documents that are viewable in any web browser. The Plain text option produces text files that are compatible with any text editor (e.g. Vim, Notepad, Emacs, etc.).

For best results, you should use HTML output because it preserves all document formatting (bold, italic, etc. text) while plain text output does not. As such, the option you should choose depends on your requirements.

Include export date* If enabled, this option causes the current export date to be included in the filename (i.e. sample_journal_09-03-2013.html). This feature is useful for archival purposes since it indicates what a journal contained on a specific date.
Keep individual entries separate If checked, this option causes RoboJournal to export the current journal as a set of discrete files, with one entry per file. Enabling this option disables many other settings on the Export entire journal page that are only relevant to the task of creating a single large export file.

The output files from the export operation are saved in a custom folder contained within the current Export location directory. RoboJournal automatically creates the export folder during the procedure so there is no need to manually create it in advance. Each file in the folder is marked with the journal name, its position in the series, and the entry title (i.e. sample_journal_1_of_15_sample_entry.html).

Exporting the journal as a series of individual entries always arranges the content in ascending chronological order, with the oldest entry being the first item in the set.

Allow custom filename* When selected, this option allows you to directly edit the Filename field's contents. You should enable this feature if the situation requires you to assign a custom filename to the output file.
Sort in ascending/descending order* These two options determine the chronological order in which entries are merged into the output file. Arranging entries in ascending order causes the oldest entry to be listed first while descending order places the latest entry first in the sequence. RoboJournal chooses the descending arrangement by default because it assumes the most recent entries are the most important to the reader (and should therefore be listed first).

* RoboJournal locks these options (and ignores their current settings) while the Keep individual entries separate option is enabled because the affected options are non-applicable to multiple files.

Creating a Backup of Your Journal with MySQLDump

RoboJournal 0.5 introduces a new feature that allows you to easily create a backup of the current active journal. Backing up a journal is useful because it allows you to "freeze" the current condition of your journal at a specific moment in time. You can then use this backup at a later time to restore or revert your journal to the state it was in when the backup was created. For best results, you should create backups on a regular basis and store them in a safe place in case the working copy of the database becomes corrupt or is lost due to equipment failure.

RoboJournal uses a utility called MySQLDump to create the backups (MySQLDump is usually distributed along with MySQL). In the past, this task required you to invoke MySQLDump manually via the command line but RoboJournal is now capable of directly interfacing with MySQLDump through an easy-to-use graphical user interface. At the moment, RoboJournal offers no direct way to restore databases from backups but that feature is planned for future versions.

FYI: If the current journal is located on a remote host (i.e. not "localhost" or "127.0.0.1"), RoboJournal locks the export options because there is no way to dump a remote database with the locally-installed copy of MySQLDump. If you need to back up such a journal, you must access the remote computer either physically or through remote access protocols (SSH or RDP) and run MySQLDump that way.

You can export your journals by completing the following procedure:

  1. On the RoboJournal main window, select an entry from the Chronological Entry List and click the Export Content toolbar button (as shown in Figure 1) to display the Export Content window. For this procedure, it does not matter which entry you choose from the list.
  2. Click the Backup MySQL/MariaDB Journal list item on the left side of the Export Content window to display the backup-related options (Figure 5): Figure xFigure 5: The "Backup MySQL/MariaDB Journal" page provides an easy-to-use interface for MySQLDump.
  3. Make all necessary changes. The default settings produce a .sql file bearing the journal name and the export date (i.e. sample_journal_09-04-2013.sql)  that is saved in your home folder/profile's "Documents" sub-directory ("My Documents" on Windows XP and older).
  4. Click the Export button to begin the operation: Figure 6Figure 6: Click the Export button when ready.
  5. Enter the root password for MySQL when prompted and click the OK button to continue:Figure 7Figure 7: Enter the current MySQL server's root password to continue. RoboJournal requires root-level access for MySQLDump operations because it must lock the current journal's tables (a function that is normally restricted to the root account) before it can complete the dump operation. This prevents the possibility of edit collisions, which are attempts by two or more users to modify the same database simultaneously.
  6. The Export Content window closes itself once its task is complete.

Backup Options

The following table contains a full explanation of all options that can be applied to backup operations and the effects each option has on the output file:

Output filename
The Output filename field determines the name the entry content is saved under on your hard drive. This file always has a .sql extension.
Allow custom filename
If checked, RoboJournal allows you to choose your own filename by directly editing the contents of the Output filename field (which are otherwise read-only). Despite the freedom this feature offers, RoboJournal strictly enforces certain guidelines:

When you click the Export button, RoboJournal corrects any errors it detects in the filename, including replacing spaces with underscore ("_") characters and removing forbidden characters like [semi]colons, slashes, etc. As you edit the text in the field, RoboJournal constantly ensures the filename you have chosen ends with an appropriate .sql extension at all times.

When the Allow custom filename field is unchecked, RoboJournal utilizes a [journal name]_[export date].sql naming convention (i.e. sample_journal_09-23-2013) for all output files.
Output file location
This field determines where the output file is saved (the Documents folder in your home directory is the default location). Click the Browse button to the right of this field to select a different folder.
Path to MySQLDump utility
This field lists the absolute path to the MySQLDump executable on your computer. Click the Browse button to the right of this field to manually locate MySQLDump.

While running on Windows, RoboJournal restricts the file browser to mysqldump.exe but there are no such restrictions on Linux/Unix because executables have no extension on those operating systems. Once you have located the MySQLDump executable with the file browser, RoboJournal saves the selected pathname so you will not need to browse for it again.
<<<<<<< HEAD
RoboJournal Documentation

for version 0.4.2

Exporting Journal Entries

Sections

  1. Overview
    1. Export Formats
    2. Export Options and Settings
  2. Exporting a Single Entry
  3. Exporting the Entire Journal

Overview

RoboJournal stores all journals as databases. Databases like MySQL are not discrete files on your hard drive; instead, they are abstract entities you work with through an intermediary program like RoboJournal. The intermediary program relays data between the client (your computer) and the actual journal database residing on the host. While the journal appears to be on your computer, this is not truly the case unless you are running the database server on localhost.

Since the journal databases are abstract entities, it is normally difficult to extract data from them unless you dump the entire database to disk as a file (the most common backup method). Fortunately, RoboJournal provides a way to directly extract journal content (in part or in whole) from its database in a form that can be easily backed up or copied.

Export Formats

RoboJournal currently supports two export formats for your entry data. Both formats are universally-compatible with every operating system and many handheld devices as well.

HTML Export

HTML formatting causes the exported section(s) to be saved as HTML files that can be displayed in any web browser. Since RoboJournal already stores entries in HTML format, this option preserves all existing formatting. Therefore, it is the recommended format for both individual entries and full journal exports. The appearance and function of HTML output documents are controlled through current settings found in the RoboJournal Preferences.

Plain Text Export

Plain text export causes the exported section(s) to be formatted as plain text files meant to be read with a text editor like Vim or Notepad. RoboJournal automatically formats the text file for the operating system it is currently running on (such as using the proper linebreak character).

Export Options and Settings

The Export Content window interface consists of two tabs that are very similar to each other yet work very differently. The Export Single Entry tab contains options applicable to individual entries while the options on the Export Entire Journal tab affect the entire journal. The following tables list and describe the options found on the Export Content window based on the tab on which they are found.

The Export Location field displays the folder where all exported entries are to be placed. This field is always visible no matter which tab is selected.

Export Single Entry Tab

Filename The Filename field contains the name to be applied to the entry you have selected for export. The length and complexity of the filename are determined by the options you currently have selected. The base filename is determined by the title of the entry to be exported. RoboJournal automatically strips out all characters (like colons or forward/backward slashes) that would produce an illegal filename on Windows or Unix if such characters are found in the entry title.
Export Format The options in this group determine what type of file is produced by the export process. Clicking the HTML (recommended) button causes RoboJournal to export the entry as a web document while the Plain Text option produces a plain text file.
Include Date If checked, this option appends the entry date (plus the day of the week on which it was written) to the filename (i.e. sample_journal_new_entry_friday_1-4-2013.html).
Include Journal Name If checked, this option includes the journal name in the filename (i.e. sample_journal_new_entry_friday_1-4-2013.html). This option is recommended because it makes it easier to remember which journal an entry came from.

Export Entire Journal Tab

Filename The Filename field contains the name to be applied to the entry you have selected for export. The length and complexity of the filename are determined by the options you currently have selected. RoboJournal uses the name of the journal as the base filename. RoboJournal automatically strips out all characters (like colons or forward/backward slashes) that would produce an illegal filename on Windows or Unix if such characters are found in the entry title.
Export Format The options in this group determine what type of file is produced by the export process. Clicking the HTML (recommended) button causes RoboJournal to export the journal as a web document while the Plain Text option produces a plain text file.
Include Export Date If checked, this option causes RoboJournal to append the current date to the filename (i.e. sample_journal_01-20-2013.html). This option is ideal for archival purposes because it allows you to see the journal as it was at a specific point in time. This option also allows you to export the journal multiple times without having to replace older versions.
Sort Ascending/Sort Descending This option controls the order in which entries are placed in the exported document. Selecting the Sort Ascending option causes the newest entry to be placed first while Sort Descending does the opposite.

Exporting a Single Entry

Like the Manage Tags window, RoboJournal's export system is designed to target a specific entry (even when you use it to export an entire journal at once). The following procedure instructs you how to target a specific entry and bring up the Export Content window:

  1. Click to select the desired entry in the Chronological Entry List (the selected entry is shown within the large oval in Figure 1).Figure 1Figure 1: Select an entry and click the Export Content toolbar button to display the Export Content dialog.
  2. Click the Export Content toolbar button (indicated by the small circle in Figure 1).
  3. The Export Content window is displayed:Figure 2Figure 2: The Export Content window is always superimposed over the main window.
  4. Ensure that all Export Format and Filename Options settings (indicated by the red oval in Figure 3) are configured appropriately and change them if necessary.Figure 3Figure 3: The options indicated by the red circle have a direct impact on the predetermined Filename.
  5. Click the OK button to continue (a confirmation message is displayed if the export operation is successful).

Exporting the Entire Journal

As previously stated, RoboJournal allows you to export an entire journal at once. This is much faster and produces better results than the only other alternative method (manually exporting the journal one entry at a time) because it loops through the entire journal and appends each entry to a single file.

The procedure for exporting the entire journal is very much the same as exporting a single entry:

  1. Click to select an entry (indicated by the oval in Figure 4) from the Chronological Entry List. Unlike in the previous procedure, it does not matter which entry you choose since you intend to export the entire journal.Figure 4Figure 4: You can select any entry if you intend to export the entire journal.
  2. Click the Export Content toolbar button (indicated by the small circle in Figure 4). The Export Content window is displayed.
  3. Click the Export Entire Journal tab (indicated by the oval in Figure 5) to switch to it.Figure 5Figure 5: The procedure for exporting the entire journal is very similar to that of exporting a single entry until you get to this point.
  4. Check the circled options in Figure 6 to ensure they are set properly. Change them if necessary.Figure 7Figure 7: At first glance, these options look similar to those in Figure 3 but these affect the entire journal rather than a single entry.
  5. Click the OK button to continue. A confirmation message is displayed if the export operation is successful.
=======
>>>>>>> experimental