Quick Start Guide for ThoutReader™ v 1.7 & 1.8

INTRODUCTION

The ThoutReader^TM is an open source (GPL 2.0) cross-platform multi-document help system (written in Java) that organizes new and existing content. Developers can browse, search, bookmark, and append a library of their favorite reference documentation and personal code as well as reference books - from one program, in one format, at the same time - even off-line.

Tip: To get the most out of the ThoutReader^TM please read this Quick Start Guide.

Vision

OSoft's vision is to train, educate, and help the open source community by providing a standardized platform through which open source documentation and training content will be delivered. This will speed development time by having all of your important references at your fingertips. Once you learn how to take full advantage of the ThoutReader^TM, you'll find it hard to go without it.

OSoft.com is a "community" where developers congregate to contribute information as well as sell training content. We provide the conduit for publishers, authors, and developers, through the ThoutReader^TM, to post their content on OSoft.com and generate royalties from units sold.

Here's what you can expect from the ThoutReader^TM:

• Reference all your documentation and access material from one place.
• Save time and learn new programming languages faster with the convenience of a single, easy to use format.
• Search all of your documentation at once.
• You buy it you own it, no subscription fees.
• Organize, bookmark and append content.
• Download and/or submit public notes.
• View your content off-line on practically any platform.

• Create your own documentation.
• Cross-link with other documentation to speed your own content creation.
• ThoutReader^TM documentation can be generated from docbook and other popular formats.
• ThoutReader^TM documentation is xhtml and is rendered in HTML.
• Powerful creation tools available at www.osoft.com/tcreator.php make it easy to create good documentation.
• Publish your content NOW at www.osoft.com.
• Set your own selling price or give it away free.
• Keep and maintain your own intellectual property and copyrights.

About Thout

Open Source

ThoutReader™ is OSI Certified Open Source Software, licensed under the GNU General Public License (GPL) Version 2, June 1991, ensuring broad adoption and future development of the project. We welcome your suggestions on how to improve the product. Please post your comments/suggestions to our user forum at www.osoft.com/forum.

Credits

The ThoutReader^TM and ThoutCreator^TM are open source projects. As such, we welcome volunteer assistance. The following people contributed to the development of the ThoutReader^TM:

Gary Varnell - Project Leader
Maxim Berdyugin
Rick Blair
Mark Carey
Peter Cooner
David Hadley
Alexander Semejonov
Andrew Singleton

If you would like to contribute your talent and skills to the further development of the ThoutReader^TM open source project, please contact Gary Varnell gvarnell@osoft.com.

Key benefits of submitting work to OSoft.com:

• Publish your content now! With our conversion scripts, we can have your content up in a matter of days.
• You set the selling price for your work and earn significantly higher royalties than through a traditional publisher. For example, if you wrote a small "How To" pamphlet that you believe would help others; you might sell it for as little as $5.00. We will also post it for free. We recommend, however, that you charge a small fee so that you may donate some or all of your proceeds to the open source foundation of your choice.
• Keep your copyrights with our "author friendly" agreement.
• Paid content is protected with DRM encryption.
• Use OSoft's high site traffic to distribute your content.

Contact us at author@osoft.com

INTERFACE

Changing the Look and Feel

The ThoutReader™ comes with several skins. To change the skin, select View...Change Look and Feel... from the Menu bar and make your selection. In the future additional skins will be downloadable from www.osoft.com.

Anti-Aliasing

By default, anti-aliasing is turned "on". This reduces the unwanted jaggies between the font and the background color .

Turning anti-aliasing "off" may speed up the rendering of content on older/slower machines. To adjust anti-aliasing, select View...AntiAliasing from the Menu bar. Click once to turn off (no visible check mark). Click again to turn on (check mark).

PACKAGE MANAGEMENT

A package is defined as a collection of content that has been prepared for viewing with the ThoutReader^TM. For example, this Quick Start Guide is a package, as is any referenceware, book, or other content that can be viewed by the ThoutReader^TM.

Download New Packages

Additional packages that can be read by the ThoutReader^TM can be downloaded several ways:

• Go to www.osoft.com or other content provider and download directly from that site.
• Click the Download Icon from the Quick Navigation Buttons in the upper right menu as shown below. This will take you directly to OSoft's content repository.
• Create and install your own packages created from ThoutCreator™ tools.

Many packages at www.osoft.com are free. These include all of the available open source application documentation. Top selling reference books and author contributed content are available for a reasonable price.

Re-downloading Packages

All packages, both commercial and free, may be re-downloaded from your OSoft user account at www.osoft.com. This is particularly useful if the original download was interrupted or if you choose to install your content on more than one computer owned and used by you. To do this:

• Log-in to your OSoft.com user account.
• Select Download Products...Previous Downloads...Select file(s) to re-download.

Installing Packages

IMPORTANT: In order to be visible by the ThoutReader^TM, packages must be installed through the ThoutReader™ File Menu. To accomplish this:

• From the Menu bar, Select File...Add Package
• Navigate to your downloaded or created package.
• Select file(s) and click "open".
• Packages will appear in the Library Window

TIP: You may install multiple files at the same time by holding CTRL and selecting the file names.

Removing Packages

Removing a package from the ThoutReader™ does not delete the package from your computer, it only removes it from the ThoutReader™ library. To remove a package from the ThoutReader™ library:

• Select the Library Tab
• Right-click the package you wish to remove...select Remove Package

Reader Registration Key

The ThoutReader™ has the ability to read encrypted commercial packages. The encryption is based on the user, not the hardware the package is installed on. This means that you can install your content on any number of platforms/computers you own and use without restriction. Simply re-download the content and install your Reader Registration Key into your other machines. Encryption is entirely contained within the package itself and is designed to be minimally invasive. You only need to install the registration key once per machine. After that, you can download additional commercial content from that provider without any further action. There are no ongoing log-ins, passwords, or other requirements.

Note: The ThoutReader™ Key is only required if you purchase commercial, encrypted content. No action is required for the download and use of free content.

Note: If you receive the following error message, it means that the Reader Registration Key is not installed for that package.

To add your ThoutReader™ key, do the following:

• Log in to your OSoft User Account
• Select Download Reader Registration Key and download your key to your computer desktop
• Open the ThoutReader
• Select File...Add Key...Navigate to your OSOFT.KEY file...Install the key
• You will receive a confirmation that the key was successfully installed.
• You can delete the key file on your desktop.

Note: You can store multiple Reader Registration Keys into the ThoutReader™. For example, each publisher that distributes content directly will generate their own User Registration Key. You need only install that key one time.

View a Package

The ThoutReader^TM comes with one pre-installed package, this Quick Start Guide. By default, the Quick Start Guide will automatically be displayed in the Content Window the first time you open the ThoutReader^TM. The ThoutReader^TM browse view will display your last viewed package the next time you load the ThoutReader^TM.

To View an index of all installed packages, click the Library Tab. Double Click any installed package to load into the Browse window.

Organizing Your Packages

The Library Tab displays all of the installed packages in the OSoft Thout Reader/Content directory. You can organize your library by creating folders; then drag and drop packages into desired folders.

All of your content is depicted in the Library Root Folder.
To create a folder/sub-folder, select the root you want the folder to be displayed in and right click anywhere in the Library pane...select Add Folder

Drag and drop selected contents into the desired folder.

LIBRARY

The Library Tab displays all of the installed packages in the OSoft Thout Reader/Content directory. Double-click on any package name and the index for that package will automatically display in the Browse Tab Navigation window.

Adding Folders

All of your content is depicted in the Library Root Folder. You can organize your library by creating additional sub-folders; then drag and drop packages into desired folders.

To create a new sub-folder, Right Click on the desired Parent folder and click Add Folder. Name the folder and press Enter.

Drag and Drop

You can move packages around in your library. Simply drag and drop package names from one location to another. We recommend you put "vertical content" in a common folder. For example: Create a folder called MySQL. Place all your MySQL documentation packages and your favorite MySQL book packages in the MySQL folder. This will make finding and searching your content easier.

Removing Folders

Folders must be empty to be deleted. Right click the empty folder and select Remove Folder.

Renaming Folders

To rename a folder, select the desired folder, right click and click Rename Folder. Type in new name and hit enter.

BROWSE

The Browse tab displays the index of the selected package from the Library. When you select a topic from the index, the content will be displayed in the Content Window.

Navigating

Click on the desired topic you wish to see and it will be displayed in the Content Window. Click the left or right arrows on your keyboard to expand or collapse categories.

Copy and Paste

Copy and paste functionality is dependent on the package and the restrictions the authors/publishers place on it. All free/open source content has no restrictions and can be copied and pasted. ALL code, regardless of the type of package, can be copied and pasted. This is invaluable for long or complicated sample code.

To copy non-encrypted content, select desired content with your mouse (it will turn light blue):

• Right-click and choose Copy or
• press CTRL+C
• Paste into desired application.

OSoft has made it easy to copy "clean" versions of code. To the upper left of each code block you will notice a small "copy icon". When you click on the icon, an OSoft ThoutReader Code Window opens up with the content identified by the copy icon. This content may be copied/pasted/printed as needed using any text editor or word processing program.

Printing

Printing of the current node is supported in ThoutReader™ v.1.8 and higher.

Code - all code can be copied, pasted, and printed.
Non encrypted packages - the entire package can be copied and pasted or printed from the File menu.
Encrypted packages - The ability to copy/paste/print is determined by the author/publisher. All code may be copied/pasted. The current node may be printed from the File menu.

Keyboard Commands

To navigate within the Browse Tab, click on the desired topic or use the keyboard commands:
To see a list of keyboard commands, Right-Click anywhere in the Browse Navigation Window.

SEARCHING

The power of the ThoutReader^TM is evident in its awesome search capability. Using all of the cawill speed up and enhance productivity.

Normal Search

The normal search only searches the current (open) package. To conduct a normal search:

• Click the Search tab or
• From the Menu bar select Navigation / Search or
• CTRL+ S anywhere in the program
• Enter search term
• Choose Index (default) or All Text
• Click Search
• View results in the Navigation Window

NOTE:

• While searching, the OSoft logo will spin, letting you know that it is actively searching.
• A status bar in the lower right corner of the Content Window keeps you informed of the search progress.

Advanced Search

The Advance Search offers more options and can broaden your search to specific packages or all packages. To conduct an advanced search:

1. Open the advanced search by doing one of the following
   1. Double click on the search tab or
   2. Click the Search tab and select Advanced OR
   3. From the Menu bar select Navigation / Search and select the Advanced tab OR
   4. Select CTRL + S from anywhere in the program and select the Advanced tab
2. Select one or more of the following advanced options you wish to use in your search
   1. Exact Phrase - Matches exact phrase word for word
   2. Match Case - Allows for case sensitive matching
   3. Regular Expression - Allows complex matching
   4. Outline - Allows searching all text, or only text in outline items (nodes)
3. Enter search term
4. From the drop down box, select which packages you want the ThoutReader™ to search. Note: If you select Library, all of the packages in the content folder will be searched
5. Click Find
6. View results in the Navigation Window.

Viewing Search Results

Search results will be rendered in the Navigation Window. When you click on a topic in Navigation Window, your search terms will be displayed in the Content Window, highlighted in yellow.

Managing Search Results

Manage your search results by RIGHT-CLICKING on any search result in the Navigation Window and follow the menu instructions to move from one term to the next. Or, just use your mouse.

BOOKMARKS

Bookmarks are global and are recorded in the Bookmark tab for all installed packages. This easy reference allows you to quickly move to important reference locations in any installed package.

Create a Bookmark

Once you have content in the Content Window that you wish to bookmark for later retrieval, you may either:

1. Right click the content and select Add Bookmark or
2. On the Menu Bar, choose Navigation - Add Bookmark.

Choose a name for the Bookmark and select enter. Your bookmarked section can be retrieved from any open package.

Managing Bookmarks

The ThoutReader^TM allows you to create file folders to organize your bookmarks (similar to creating folders in the library tab).

Adding Folders

You can organize your bookmarks by creating additional sub-folders; then drag and drop bookmarks into the desired folders.

To create a new sub-folder, right click on the desired parent folder and select Add Folder or [Alt + a], name the folder and press Enter.

Drag and Drop

You can move bookmarks around by dragging and dropping bookmarks from one location to another. We recommend you put "vertical content" in a common folder. For example: Create a folder called Linux. Place your Linux documentation packages, "How To" packages, and your favorite Linux book packages in the Linux folder. This will make finding and searching your content easier.

Deleting Folders

Folders must be empty to be deleted. There are two ways to delete a folder:

• Right click the empty folder and click delete.
• Click folder to select and press the delete key on keyboard.

Renaming Folders

To rename a folder, select the desired folder, right click and click Rename or [Alt + r].
Right click on any Bookmark in the Navigation Window and follow menu instructions to move, delete, or rename bookmarks.

Deleting Bookmarks

To delete a bookmark:

• Select the bookmark from the bookmark tab and press Delete key
• Right click on bookmark and select Delete Bookmark

Renaming Bookmarks

• Select the bookmark from the bookmark tab and press (Alt + r)
• Right click on bookmark and select Rename Bookmark

Keyboard Commands

Right-click in the Bookmark tab and follow the keyboard commands.

NOTES

Viewing of notes only applies only to the currently opened package. There are two types of notes - Private and Public. The Notes function is turned on/off through Notes on the Menu bar.

Private Notes

Private notes allow you to add personal notes, tips, and ideas to the existing content. It's your space. You can edit existing notes or add multiple notes to each section. Private notes and related icons are are yellow in color.

Displaying/Hiding Private Notes

To view Private notes select Notes...Private Notes from the Menu bar
To hide Private notes select Notes...Private Notes from the Menu bar to remove the check mark.

Add a Private Note

To add a note, you have to turn the feature "on". To do this, select Notes ...Private Notes from the Menu bar

Once the Notes feature has been turned on, a yellow + icon will appear in each section of the package. When you select the icon, a pop-up box appears for your note information as seen below:

Complete note and press OK.

Edit a Private Note

To edit a note, select the yellow edit icon from within the note. You can also right click on the note in the Notes tab...Select Edit Note.

Deleting Private Notes

• Click on the Note Tab...Select the note you wish to delete...Right click on the note...Select Delete Note
• Alternatively, when viewing the note, select the delete icon from inside the note.

Viewing Private Note List

The entire private note list for an open package may be viewed from the Notes tab. Select Private Notes from the drop-down box as shown below:

Keyboard Commands

Right-click in the Notes tab and follow the keyboard commands.

Public Notes

 Public notes promote active community participants to become formal contributors to the package. Often, public contributions are more "valuable" than the original content as they provide insight from real-world users. Public notes and related icons are blue in color.

How Public Notes Work

Displaying/Hiding Public Notes

To view public notes select Notes...Public Notes from the Menu bar
To hide public notes select Notes...Public Notes from the Menu bar to remove the check mark.

Downloading Public Notes

Public notes may be downloaded for the current package or for all packages. Make your selection from Notes menu as shown below:

Add a Public Note

To add a public note, you have to turn the feature "on". To do this, Select Notes ...Public Notes from the Menu bar.
NOTE: You must be connected to the internet to add a public note to OSoft's web server.

When you turn public notes on, a blue + icon will appear in each section of the package. Selecting the icon will open your default browser and take you to OSoft's website.

• In order to add a public note, you must log in to your OSoft user account. If you are not logged in at the time you desire to create a public note, clicking on the blue + will take you to OSoft's log in page.
• Once you log in, the Add a Public Note page will be displayed for the particular node you selected.
• Add your note and click Submit.

 Making a Public Note Private

This unique feature of the ThoutReader™ allows you to convert any public note into a personal note. Perhaps you only wish to view only the best public notes or responses from the author(s) as part of your notes. To accomplish this, click the public-->private note icon as shown below:

Notice that the public (blue) note is duplicated as a private (yellow) note. By turning public notes off and private notes on, you have access to a repository of great private notes from leading experts.

Deleting/Editing Public Notes

Only the author of a public note can edit or delete it. This must be done from their OSoft user account at www.osoft.com. Users can edit a public note created by others by turning the public note private.
Note: OSoft reserves the right to edit or remove any public note deemed objectionable as defined by our posting guidelines.

UPDATES AND UPGRADES

Whenever OSoft updates a package that you have previously downloaded, you will be notified by e-mail and the new version will automatically be placed in the download section of your individual user log-in at www.osoft.com. This will allow you to download the updated package at your convenience. It is important that you keep your user information current.