ReadMe File for TreeLine

TreeLine's window is divided into two panes. The view on the left shows the entire tree structure, while the view on the right shows various information about the tree node that is selected in the left pane.

The right pane is tabbed to show one of three different views of the data. The "Data Output" view shows the formatted text for each node and is read-only. The "Data Editor" view shows a text edit box for each data field within a node. The "Title List" view shows a list of node titles that can be modified using typical text editor methods.

By default, the right view will show information about the selected node in an upper pane and information about the selected node's children in the lower pane. Selecting "View->Show Selected Node" will show a single pane with information about the selected node only. When there are many children, the combined view may slow down, especially in the "Data Editor" view. In this case, it is quicker to view just the selected node. The initial state of the view can be controlled in "Tools->General Options".

Most of the menu and tool-bar commands apply to the items selected in the left view. In general, they perform an operation on the nodes themselves or on the descendants of the nodes. Multiple nodes can be selected by holding down the "Ctrl" and "Shift" buttons when clicking with the mouse. But some commands, such as "File->Export" and "File->Print", use data from only the current node, which is shown with a surrounding rectangle. The right hand view also references only the current node.

To add information to a new TreeLine document, use the "Edit->Add Child" command to create a new node. Then combinations of the add and insert commands may be used for additional nodes. Alternatively, new node titles may be typed into the "Title List" view in the right pane.

There are several keyboard commands that can be used for tree navigation. The up and down arrow keys move the selection. The left and right arrows open and close the current node. Holding the CTRL key and the up and down arrows moves between siblings, skipping children. The CTRL key and "U" moves to an item's parent. The "Home", "End", "Page Up" and "Page Down" keys can be used to move quickly through the tree. Holding the SHIFT key with the "Page Up" and "Page Down" keys will scroll the right-hand child view.

All of these keys and the keyboard shortcuts for pull-down menu commands can be customized by editing the TreeLine configuration file ("~/.treeline" on Linux, "treeline.ini" on windows).

Another way to move through the tree is to type the first letter of a visible node title. A lowercase letter moves downward, an uppercase letter moves upward. Hitting the letter again moves to the next possibility.

There are two ways to search for nodes. These methods can find nodes that are deeply buried in the tree structure. The first is the "Tools->Find" command. Keywords can be entered in a modeless dialog box. A node is found if the keywords are matched in any of the node's fields. The next method is an incremental search. Type a "/" followed by a search string. The search will progress as the string is being typed. The incremental search only finds text in the node's titles. The previous search can be repeated with the "F3" key and backward with "Shift-F3".

By default, parent nodes will automatically open and close when found with the search methods, by typing the first letter, and with the "next sibling" keyboard command. This behavior can be disabled in "Tools->General Options".

The commands in the "Edit" menu (except for undo and redo) operate on the selected nodes in the left tree view. The cut, copy and paste commands can also be an exception to this, since they operate on the right view when something is selected there. And keep in mind that, in general, the descendants of the selected nodes are also affected.

Paste will add a copied node as the last child of the current node. Alternatively, the "Edit->Paste Node Text" command actually renames the selection based on the top node in the clipboard.

There are several shortcuts for use in tree editing. Drag and drop will move or copy nodes to become a children of the destination node. Clicking on a selected node will rename it. Pressing the enter key will insert a new node, and pressing the delete key will remove the selected nodes. If desired, these shortcuts can be disabled in "Tools->General Options".

In the right pane, the "Data Editor" view provides the most direct way to edit the data within a node. If the edited field is used in the title formatting, the node title in the tree will show the changes. The field editor will scroll, allowing multiple lines of text to be entered.

There are items in the "Data Editor" box context menus to add HTML font tags around selected text. These tags include bold, italics, underline, size and color. Note that the fields must be set to display HTML content (see the Field Types section, below) for this to be effective.

An external editor can also be invoked from a "Data Editor" box context menu. After the text editor saves changes and is closed, the changed text will be in the text box. The EDITOR environment variable can be used to specify the editor to start, or, if the variable doesn't exist, TreeLine will prompt for an executable to set as the default.

Also in the right pane, the "Title List" view is useful to quickly rename child titles or to add new child nodes. A text list of new nodes can even be pasted directly into this view.

There is a spell check command in the "Tools" menu. Use of this command requires an external program to be installed (see the System Requirements section). If there are any misspelled words in the selected branch, a dialog will allow the word to be ignored, added to the dictionary, replaced with a suggestion or edited. This will spell check the text in all data fields of each node.

By default, a new TreeLine document contains two node types: "ROOT" and "DEFAULT". The type is shown at the top of each node box in the "Data Editor" right-hand view. The creation of new types and the customization of types is described below. To set the selected nodes to a specific type, use the "Data->Set Item Type" menu. Alternately, to set a series of child and descendant nodes to a specific type, use the "Data->Set Descendant Types" command. The resulting dialog box allows the selected nodes, their children, all descendants, or descendants matching logical conditions to be set to the highlighted type. The dialog box can be left open while the tree selection is changed to set more nodes.

The data types are configured with the "Data->Configure Data Types" dialog. The type is selected at the top of the dialog box, and the "Modify List" button is used to add, delete and rename the available types. The left half of the configure dialog shows the fields. These are the data fields that will be in each node of this data type. There are buttons to add, delete and reorder the fields. A button to change the field type is covered later.

The right half of the Configure Data Types dialog box shows the formatting for the title (used for the node text in the tree view) and the node output. The formatting consists of text lines with embedded fields. The fields are shown as "{*field_name*}". They can be added or removed with the ">>" and "<<" keys.

References to fields from parent and grandparent nodes are shown as "{**field_name*}" and "{***field_name*}", respectively. There are also general ancestor references, shown as "{*?field_name*}", that take data from the closest ancestor with a matching field.

These references can be added with the "Other Fields" button in the field portion of the dialog. This will prompt for the parent level (any ancestor, parent, grandfather, etc.) and the ancestor's data type. Then, the ">>" keys will add the selected fields to the formatting.

References to child nodes can also be added from the "Other Fields" dialog. The child data becomes embedded in the parent output. The child data is delimited with a separator string defined as a file option. The separator defaults to a comma and a space, but can be set to <br> or anything else.

The "Other Fields" dialog also contains file info references. These fields contain file meta-data, including the file name, path, size, and modified time. These are shown as "{*!field_name*}" in the title and output format editors.

When a node in the tree is renamed, the program attempts to match the title formatting pattern to set the appropriate fields. If the title formatting is too complex, it may not correctly guess your intent. Things like adjacent fields with no characters separating them should be avoided unless you do not wish to rename nodes from the tree.

If the text data used for a tree view title has multiple lines, only the first line will be used as the title.

If a line in the output formatting contains one or more fields and all of those fields for a given node are empty, the line is skipped. No blank line or embedded text will be output for that line. Note that this does not apply to a line without any fields (only embedded text). Also, when a line ending with a <br/> or an <hr/> tag is skipped, the ending tag is retained.

Simple HTML formatting tags can be used in node output formats. Commonly used tags include "<b>bold</b>", "<u>underline</u>", "line break<br/>", "<hr/>horizontal line", and various font tags. Complex block tags should generally be avoided. When the "Allow HTML rich text in formats" file option is disabled, formatting tags are treated as plain text.

A line break is automatically output after each formatting line, unless the "Add line breaks after each line" file option is unset. In addition, the "Add blank lines between nodes" file option determines whether there is also an automatic blank line between node outputs. A line break tag ("<br>") can be used at the end of the formatting to get the same effect, or a horizontal line tag ("<hr>") may be used instead to separate the nodes.

Here is an example of output formatting for a book list:

<hr/>"{*Title*}"
(c) {*Copyright*}, Rating: {*Rating*}
{*PlotDescription*}

Sample files with various kinds of formatting are included in the program distribution (see the "sample_*.trl" files in the "doc" directory).

The icons shown for each node in the tree view can be assigned based on data type. The "Change Icon" button in the "Configure Data Types" dialog brings up the set icon dialog. If the selection in the dialog is cleared, no icon will be shown for that type. To avoid showing any tree icons, the "Show icons in the tree view" general option can be unset.

The "Configure Data Types" dialog also contains a setting for the default child type. If set, this is the initial data type that is used for new children of this type parent. If it is not set, the type of the parent or of siblings is used.

The "Advanced" button in the "Configure Data Types" dialog brings up additional settings. The first allows one of the fields to be set as the reference field, used for the arrange and flatten by reference commands and for internal link references. The reference field is the first field by default.

The advanced dialog also has settings for sibling prefix and suffix tags. These tags can often be left blank, but are useful for creating tables or bulleted lists. These tags will be placed before and after sibling groups of the proper type. For example, to create an output table, the sibling prefix tag could be set to "<table border="1">" and the suffix tag could be set to "</table>". Then, the output format could be set to:

<tr><td>"{*Title*}"</td><td>(c) {*Copyright*}</td></tr>

Siblings should generally be of the same type, or at least have the same prefix and suffix tags.

Another method for changing data type formatting is to copy the formats from another TreeLine file. This is done with the "Data->Copy Types from File" command. All types from the chosen file are copied. Any types in the current file with a matching name are overwritten, but types with unique names are retained.

In the "Configure Data Types" dialog, the "Field Type" button brings up a dialog for formatting the selected field. The field type may be set to text, long text, number, choice, combination, auto choice, date, time, boolean, URL, path, internal link, executable link, email, or picture. Prefix and suffix text can be entered and will show up whenever the data is not blank.

There are also settings for text content handling that can be set to allow HTML rich text in the field data or to preserve line breaks (ignoring HTML code). If HTML rich text is used, carriage returns are ignored and non-escaped "<", ">" and "&" symbols do not display. There is also a general option available that makes new fields default to HTML content.

Several of the field types use a formatting string to define their output. For a list of available formatting characters, use the "Format Help" button. Entries in the data editor which do not match the format will cause the field name label to show in bold, and the output for that field will be replaced by "#####".

The default field type is a text field. These fields are edited using edit boxes in the data editor view. The edit box height expands when redisplayed after adding several lines of text. The edit box height can also be set explicitly in the field format dialog box.

The choice and combination field types allow for the selection of text items from a pull-down edit list. The formatting strings for these types list the items separated with the "/" character (use "//" to get a literal "/" in an item). Choice is used to select a single item and combination to select multiple items. The pull-down edit list for combination allows items to be added or removed. Also, the initial text of an item can be typed and auto-completed.

The boolean field type is similar to choice, but defaults to options such as "True/False", "yes/no" and "1/0".

There is also an AutoChoice field type. Like Choice, it provides pull-down selection items, but it does not have a formatting string. The pull-down is automatically populated with all previously used entries.

In the number type, special characters in the format define the display of the numbers. The format uses a string of "#" (optional digit) and "0" (required digit) characters to define the output formatting. For example, pi formatted with "#.#" is "3.1" and formatted with "00.00" is "03.14". Regardless of the formatting, digits to the left of the decimal point are not truncated, since that would display an incorrect result. But use care to show enough decimal places (either optional or required) to avoid problems with round-off error.

The radix character can be specified as either "." or "," to handle internationalization. For use as a thousands separator, use "\," or "\.". For example, a large number may be formatted as "#\,###\,###.##" or as "#\.###\.###,##". Press the "Format Help" button from the field format dialog for more formatting details.

Unlike most other formats, the number type also uses the output format for display in the Data Editor. Of course, any new entry with a reasonable format is correctly interpreted (but the correct radix character must be used).

In the date, and time field types, special characters in the formats are replaced by elements of the data, similar to number fields. Press the "Format Help" button from the field format dialog for formatting details.

There are also formats for these types under "Tools->General Options->Data Editor Formats". These control how these fields are displayed in the Data Editor view. Generally, entries in the data editor with various formats will be correctly interpreted regardless of this setting, but dates must use the correct day-month-year sequence. Also note that the date editor format does not support days of the week. Entries which cannot be interpreted will cause the field name to show in bold.

A default initial field value of "Now" can be used to get a time-stamp of node creation.

The URL, path, and email field types are used to create links in the output. URL is for a standard web link (defaults to http:// unless otherwise specified), path is for a local file link (defaults to file:///), and email is for a mail link (defaults to mailto:). When clicked in the output window. these links open an external browser or email program. In exported HTML, they act as regular links. Simply enter the desired full path (such as "www.bellz.org/treeline/index.html") in the data editor. In Linux, setting the "BROWSER" environment variable to a string like "mozilla %s" will result in the desired browser being used.

There is also an internal link field type. It creates a clickable link in the Data Output window that selects the next node with matching text in its reference field. If link or reference fields contain multiple lines, each line is treated as a separate link or reference, respectively. If desired, the same field can be used as both the link and reference fields, so that clicking on a keyword in one node's field selects the next node that also has that keyword. If exported to HTML, the internal links function as links to page anchors, but, in cases with duplicate references, they only find the uppermost reference on the page instead of the next one.

The ExecuteLink field type runs an external program when its link is clicked. The command to run is given by the text of the field. Or the field's prefix may contain the program name, so that the field's text is used for arguments or file names. A general option can disable these links when security is a concern.

The picture field type will show a referenced picture in the output. Enter the full path to a local image file in the data editor. For Qt2 (used on windows builds) the output window only supports GIF and PNG image formats. For Qt3, JPEG and other image types are supported. Of course, when exporting HTML, the picture will show as long as the browser supports the format.

The "Advanced" button in the "Field Format" dialog brings up additional settings. A default initial field value can be specified for a field type. Any new nodes get this value for the given data field when they are created.

Link fields can display alternate text in place of the target URL. This is done by specifying an alternate text field.

There is also a setting to flag fields as required to be filled in. Those fields will be marked with an asterisk in the data edit view.

Fields can also be set as hidden, to prevent them from showing in the data edit view.

The "Data" menu contains commands for arranging and flattening the data by category and by reference. These methods are used to automatically add and remove levels of nodes below the current node in the tree.

The "Add Category Level" command allows you to select one or more of the fields that the child nodes have in common. These fields are used to create new parent nodes for the children, grouping them by common categories. For example, in a list of books, picking the "author_first_name" and "author_last_name" fields will result in a tree with the books under new nodes for each unique author.

The "Flatten by Category" command is almost the opposite of "Add Category Level". It eliminates any descendant nodes with children, transferring their data fields to their children. It will rename fields instead of overwriting data with the same field names, but this command is most useful when the children and parents are different types with unique field names.

The "Arrange by Reference" and "Flatten by Reference" commands arrange data nodes by using pointers to the value of their parent's reference data field. These commands rely on nodes having unique values in the reference field, such as an ID number. The "Flatten by Reference" command adds a field containing the parent's ID to each descendant node. It then places all of the nodes under the selected root node. The "Arrange by Reference" command does the opposite, placing each node under the parent with the referenced ID. If there are multiple nodes with the same ID, the nearest node above the child is chosen. Any nodes with lost parents are placed directly under the selected root node.

The "Update by Reference" command uses a separate file to update the values of missing fields. Unique values are matched in the reference data field. Any fields in the other file's node but not in the original node are added. Fields may be deleted in the original file to force the update, since the field must be missing (not just blank).

The "Data" menu also contains the "Sort Node Children", "Sort Type in Branch" and "Sort Branch by Title" commands. The first two allow the selection of several fields to be used as the first key, second key, etc. The keys are selected in order with the left mouse button and the direction is changed with the center mouse button. The "Sort Node Children" command sorts the children of the selection only, while the "Sort Type in Branch" command sorts all descendants of a given type. The "Sort Full Branch" command will sort all descendants, but sorts only by the node title text, not by particular keys.

The "Filter Data" command allows the removal of nodes based on user-defined rules. If there is more than one data type in the selection's descendants, the type to be filtered is selected. Next, logical rules may be entered based on any of the type's fields. Multiple rules can be linked by the "and" and "or" operators (press the "Add Rule" button). Rules with their operator set to "None" are ignored. Any descendant nodes of the given type that don't match the rules will be deleted (including their children). The current filename will have "_filter" added to avoid overwriting the full document. If the document was already modified, there will be a prompt allowing the unfiltered file to be saved. Once done, there is no way to undo the filtering.

The "Numbering" command is used to add number fields to descendant nodes. The number fields do not automatically update when the tree is modified - the "Numbering" command must be repeated. In the dialog, a new or existing field name is entered, and the root (selected) node may be included in the numbering if desired. One of three styles may be chosen: outline style restarts numbering for each group of children, section style appends the child's number onto the parent's number, and single level style numbers only the first level of children. The default formats can be used ("I, II..., A, B..., 1, 2..." for outlines; "1, 2..., 1.1, 1.2..." for sections), or custom formats may be specified for each level. The custom formats should contain one of the following characters: "1", "A", "a", "I", or "i". The series will continue from there (using numbers, letters or Roman numerals, respectively). The last occurrence of one of these characters in the format string is used - previous ones are assumed to be part of the format.

Finally, the "Change Selected Data" command allows the values of a data field to be changed simultaneously for all selected nodes. Simply select the desired field and enter the new value.

The "Data Output" right hand view shows the formatted output text for the current node and its children. The formatted output can be printed. For printing, starting from the current node, the node's descendants are shown with the children indented. The root node can be included or excluded, and items with closed parents in the tree can be skipped.

There are additional options in the "Print Options" dialog box for setting printer fonts, margin sizes, the number of columns, and for adding tree structure lines. The tree structure lines are drawn to connect parent and child nodes. They can make parent/child relationships easier to visualize, especially across multiple pages. The lines may not display as desired when using some HTML formatting tags.

By default, TreeLine will avoid breaking pages between a parent and its first child. This behavior can be disabled by changing the "Keep first child with parent" print option.

Also on the print options dialog is a button to set the print header and footer. This brings up a dialog with file info fields on the left and six header/footer edit boxes (left, center and right justified) on the right. These fields can be added and combined with other text in the edit boxes, just like in the "Data->Configure Data Types" dialog. The header and footer settings are saved with the TreeLine file.

A preview will be shown before printing (but after hitting 'OK' on the normal print dialog box) by default. The print preview will show more detail if its window is made larger.

Some printing problems, especially problems with margins and word-wrapping, can be eliminated by changing the print font to a font that is better supported by the printer.

A TreeLine file is in an XML text format. There are also options to work with compressed files (gzip format) to save space. Individual files can be set to compressed mode from either "Tools->File Options" or from the save-as dialog. There is also a general option to set the default mode for new files.

There is a file encryption option to password protect TreeLine files. Individual files can be set to encrypted mode from either "Tools->File Options" or from the save-as dialog. There is also a general option to set the default for new files. The encryption uses the SHA hash function as a stream cipher - it should be fairly secure.

An auto-save feature can store unsaved files with a "~" appended to the file name. The backup files are automatically removed when the file is saved or TreeLine exits cleanly. The auto-save time interval is set in the general options. Setting the interval to zero disables this feature.

When opening a recently used file, TreeLine will restore the states of open and selected nodes. This information is stored in the user's TreeLine configuration file. If desired, this feature can be disabled with a general option.

Command line options allow non-interactive file importing and exporting. This allows automated runs to be scheduled. For more details, run "treeline -h" from the command line. If using a windows binary, output is suppressed, so it must be directed to a log file ("treeline -h > log.txt").

A TreeLine file is in an XML text format. Other types of text files can be imported simply by opening them. Opening a file that is not valid TreeLine XML will result in a prompt for the type of import desired.

TreeLine will open a text file with a tree structure represented by tabs before each line. In this case, only the node title is imported, without any extra fields. This method is used to open files from old versions of TreeLine.

A tab-delimited table can also be imported. It becomes a single level of children under the root node, with each node containing fields from each table column. The first row of the table is used as field names and each row thereafter becomes a node.

There are two types of plain text import. One creates a separate node for each line in the file. The other creates a node for each paragraph, assuming the paragraphs are separated by blank lines. In both cases, the resulting TreeLine file will have all of the text under a single parent, but it is a good starting point. Additional structure can be added later.

There is also a filter to import files from the Treepad shareware program. Only Treepad text nodes are supported.

TreeLine will import bookmark files in both the Mozilla HTML format (Mozilla, Firefox and Netscape browsers) and the XBEL format (Konqueror, Galeon and Elinks browsers). Each bookmark becomes a node with a name and a link field. Some information in the files, such as visited dates and icon references, is not imported.

TreeLine will import and export generic XML files. These routines do not have much intelligence - each XML element becomes a node and each XML attribute becomes a field. XML text content become fields named "Element_Data". This lets TreeLine function as a crude XML editor.

Files are exported using the "File->Export" command. This will show a dialog box of available export types and options.

Single-file HTML output is similar to printing, with similar options. It can include the print header and footer in the HTML, and the number of columns can be set.

There is also a multiple-file HTML export that creates a directory structure. Directories are named for the content of the first data field, which must contain legal file names and not have duplicates under the same parent. Each HTML file is a table of data for a set of siblings, with links to the parent and child pages.

Data can be exported to tabbed title text (the old TreeLine text format) and tab-delimited tables. These formats are the same as the corresponding import formats. When exporting to a table, only the first level of children is used, so you may wish to flatten the data before exporting.

TreeLine will export bookmark files in both the Mozilla HTML format (Mozilla, Firefox and Netscape browsers) and the XBEL format (Konqueror, Galeon and Elinks browsers).

TreeLine will import and export generic XML files. These routines do not have much intelligence - each node becomes an XML element and each field becomes an XML attribute, except for fields named "Element_Data" that become the element's text. This lets TreeLine function as a crude XML editor.

In addition to exporting data, the format for a file can be exported to an XSLT file. This can be used to display the XML data from a native TreeLine file in a compliant browser without exporting the data to HTML. Recent versions of most browsers are XSLT compliant. Note that complex field type formatting will be ignored by the XSLT.

When exporting to XSLT, a link to the XSL file is added to the TreeLine file. Note that the TreeLine file must then be saved. In general, the TreeLine file should have a .xml extension so that the TreeLine file can be opened directly in a compliant browser. After that, the XSL file does not need to be re-exported for data changes (only for formatting changes).

If HTML tags are used in data formats that will be exported to XSLT, they should use xHTML style (<br /> instead of <br>). When exporting, there is a prompt for the name of an optional style sheet (css). This name is stored in the TreeLine file as the default for future exports. Also, the reference to the XSLT file in the TreeLine file may be removed with the "Tools->Remove XSLT Reference" command.

TreeLine has an interface to plugin extension modules. This allows extensions to be written by various coders that provide functionality needed by a few users without adding bloat to the main application. The plugins can add new menu items, access the TreeLine data and read and write TreeLine Files.

Currently available plugins are listed on the "Downloads" page of the TreeLine web site.

The plugins are installed by copying their Python file (*.py) to the plugins directory ("<prefix>/lib/treeline/plugins/" on Linux or "TreeLine\lib\plugins\" on Windows). A list of loaded plugins can be found using the "Help->About Plugins" command.

There is also a configuration file setting, "UserPluginDir", that can specify an alternate plugin directory. This allows plugins to be installed without root/administrator access. This setting can only be changed by editing the configuration file (~/.treeline on Linux, treeline.ini on Windows).

Information about writing new plugins can be found in the "plugininterface.py" file in the TreeLine source code.

An error message, "Error loading XML Parser", typically means that TreeLine could not find a necessary XML library. Under Linux, Python uses external libraries for parsing. Installing either the expat library or the PyXML package should fix the problem. Under Windows, Python includes a parser, so this error should not be seen unless files are missing or corrupt.

There is a problem in which the tree and output text appears with squares between each character and truncated before the end. This is generally due to a unicode problem with a certain PyQt RPMs on Red Hat systems. The solution is to upgrade to an RPM for PyQt 3.7 or higher. A sip RPM of the same version must also be installed.

Some printing problems, especially problems with margins and word-wrapping, can be eliminated by changing the print font to a font that is better supported by the printer.