TrivWriter Documentation


<Introduction>


TrivWriter is a free Palm application that can be used to create trivia sets, study guides, and other modules for Triv.Although it was designed to run on an actual Palm device, it can also be used on your PC or Macintosh by running it inside POSE (PalmOS Emulator), a free program from Palm Computing.

<Table of Contents>


Module Header Information
Categories
TrivWriter Questions
Preferences
Menu Options
Importing Data
Import Error Descriptions
Other Documentation
Updates and Contact Information


<Module Header Information>
Module Info

Each TrivWriter module contains a set of header fields that both identify the module (e.g., the name) and provide additional information to Triv users (using the Module Info menu option). Most of these fields are optional but highly recommended.

Module Name - Name of the module. Maximum of 28 characters. Internally, a ".pdb" suffix is appended for the generated Triv module database name, and a "TW" prefix is added for the TrivWriter database name. (Note: if you intend to make your modules publicly available, it is better to avoid special characters such as slashes, backslashes, colons, quotes, and periods and to use underlines instead of spaces).
Module Type - Very brief description of the module (e.g. Genus, Entertainment, Sports, etc.). This field is informational only.
Answer Type - Pop-up menu to set the type of answers expected. This can be set to Alphabetic (all letters), Mult[iple] Choice (up to 4 choices), Numeric (all digits), True/False, or Mixed (any combination of the above). This field is mostly informational but also provides the default answer type for questions that have empty answers (if "Mixed" is selected, the default becomes "Alphabetic").
Questions - Number of questions in the question set. This is always a multiple of 18 since there has to be an equal number of questions in each category (6) and difficulty level (3). The maximum number of questions allowed is 504 per module. Note: unregistered copies of Triv are restricted to seeing the first 36 questions in each module.
Author - Name of the author of this data module.
Created - Date the question set was created. Initially set to today's date (in the date format specified in your Palm Date/Time preference).
Updated - Date the question set was last updated. Initially set to today's date (in the date format specified in your Palm Date/Time preference).
Version - Version of the question set.


Note: on this screen and every other screen with text fields, the Graffiti "Next Field" (draw straight up then down) and "Previous Field" (draw straight down then up) characters can be used to move between fields.

<Categories>


CategoriesEach TrivWriter module has 6 categories of questions. These are used in the Trivia Pizza and Triv Grid game variants in Triv but can be ignored if you prefer (e.g., set them to A, B, C, D, E, and F). The category name is restricted to 20 characters, but more importantly, the name should not overflow the width of the field on the screeen. Each category name should preferably begin with a different letter so that the Trivia Pizza pie piece labels are unique. Do not use any special characters in the category names (in particular, commas will be replaced with spaces). Category descriptions can be seen inside Triv using the Module Info menu option and cannot contain carriage returns (automatically replaced by spaces).

Tap on the number of the category that you want to edit or use the Page Down and Page Up hardware buttons to go to the next or previous category.

<Questions>


QuestionsEach TrivWriter question consists of a question, an answer (and corresponding answer type), and an optional note. The category and difficulty are predetermined by the question number and cannot be changed.

Question - For non-multiple choice questions, the description should fit into the question field using any of the 4 available fonts (hint: Large is usually longer than Large Bold), but overflow is allowed (the question should still make sense when cut off). For multiple choice questions, the standard font is always used, leaving you 7 lines to work with. The first 1 to 3 lines on the screen (no carriage returns allowed) should contain the question itself, while the next 4 lines (each preceded by a carriage return) should contain the 4 answer choices.

For all answer types, additional information may be presented to the user on the Answer screen. This text must be appended to the question description following a " -- " separator (that's a space, 2 dashes, and a space). For multiple choice questions only, the separator is not displayed to the user, so a carriage return after the separator is highly recommended (this means you can only have additional information if the question itself is 1 or 2 lines long). Note: if you are running TrivWriter in the PalmOS Emulator or Simulator, you can use the up and down arrow keys to move around the Question and Answer fields (in addition to the left and right arrow keys).
Answer - Depending on the answer type (see below), the answer field has different restrictions:

Alphabetic - All capital letters, 1 to 10 characters long, and should fit into the answer field. Add a dollar sign ($) to the end of any answer where you want to accept the answer with or without a trailing "S" (e.g. "FONT$" would match either "FONT" or "FONTS").
Mult[iple] Choice - Lower case 'a', 'b', 'c', or 'd'.
Numeric - 1 to 5 digits, with no decimals, commas, or minus signs. Leading zeroes are allowed (e.g., "007"). Add an exclamation point to the end of any answer that is a year (e.g. "1999!") for more accurate Horseshoes scoring.
True/False - Lower case 't' for "true" or 'f' for "false".

Note - This is optional information for your use only (not copied into generated Triv modules) and can be used for source information or any other notes you want. A white note icon in the lower right corner of the screen indicates that the question already has a note attached to it, while a black note icon indicates that there is no note. In either case, tapping on the icon pops up the Notes form for you to edit.


There are 5 buttons at the bottom of the Questions screen:

Previous - Go to the previous question. If currently on the first question, go to the last question.
Next - Go to the last question. If currently on the last question, go to the first question.
Go - Bring up a dialog box where you can go to the First, Previous, Next, or Last question that has the same category and/or difficulty as the current question. You can also go to the Header or Categories screen (14 choices in all).
Again - Repeat the last Go command from above, with the exception of Header and Categories.
Back - Go to the question you were previously on, regardless of how you got to the current question. Repeated taps on the Back button toggle back and forth between a pair questions.
If the Hardware Btns preference is checked, the first 4 of these buttons can also be activated via the corresponding hardware buttons (e.g., the Datebook button is the same as the "Previous" button).

Tap on the question number to bring up the "Go to Question" dialog box or use the Page Down and Page Up hardware buttons to go to the next or previous question. Note: the carriage return Graffiti stroke (top right to bottom left) is the same as tapping the OK button on the "Go to Question" screen.

<Preferences>
Preferences

TrivWriter has several options that can be set via the Preferences menu option:

Font - Sets the font used for the question field. This setting is ignored for multiple choice questions (standard font always used).
Lines - Sets whether lines are displayed in the question field or not.
Sound - Sets whether sound is turned On, Off, or set to match the System Game Sounds preference.
Hardware Btns - Sets whether the hardware buttons can be used. On some screens, this links the 4 hardware buttons with the on-screen buttons at the bottom from left-to-right (e.g., pressing the Datebook button is the same as tapping the "OK" button).
M.C. Template - Sets whether a multiple choice question template is automatically inserted or not. If checked, a template with a spot for the question itself and 4 answer choices is inserted when a multiple choice question with an empty description is found.


<Menu Options>


Different menus and menu options are available on the Header, Categories, Question, and Note screens.
TrivWriter Menu:

Preferences... - Displays the Preferences screen. The Graffiti shortcut for this option is "/R".
New Module... - Creates a new TrivWriter module. You will be prompted to enter a name for the module and then brought to the Header screen.
Import... - Allows you to import data from a Memo Pad record or Doc file. See Importing Data.
Select Module... - Displays a screen from which you can choose a TrivWriter module to use (listed alphabetically).
Delete Module... - Displays a screen from which you can delete a TrivWriter module. Note: this does not delete the corresponding Triv module generated from the TrivWriter module.
Generate Triv Module - Exports the current TrivWriter module to a Triv module. If an error occurs (e.g., a missing question or answer), an error message will be displayed, and you will be brought to where the error was found.
About TrivWriter - Displays information about TrivWriter. The Graffiti shortcut for this option is "/I".

Edit Menu - This the standard Palm Edit menu.
Go Menu (called the Find menu on the Note screen):

Header - Go to the module Header information screen. The Graffiti shortcut for this option is "/H".
Categories - Go to the Categories screen.
Questions - Go to the Questions screen.
Find... - Go to the Find screen, where you can perform a search through the descriptions, answers, and notes of the current TrivWriter module (in that order). Tap on the Info tips button for details on the available search options. The Graffiti shortcut for this option is "/F".
Find Again - Repeat the last Find command. The Graffiti shortcut for this option is "/A".
Mark Question - Mark the current question (see other options below). Available only on the Questions screen. The Graffiti shortcut for this option is "/M".
Go to Mark - Go to the marked question. The Graffiti shortcut for this option is "/T".
Go Question Number... - Go to a specific question number. The Graffiti shortcut for this option is "/Q".
Go Next Empty Question - Go to the next question that has a blank description or answer. The Graffiti shortcut for this option is "/E".
Swap with Marked Question - Swap the current question with the marked question. The current question description, answer, answer type, and note information are swapped out and the same data from the marked question are swapped in to the current question number (and category and difficulty).
Launch Triv - Go to the Triv application (Triv must be in main memory for this to work).
Launch TrivFind - Go to the TrivFind application (TrivFind must be in main memory for this to work).

Beam Menu - Beam the TrivWriter application and modules to another Palm device:

TrivWriter Application - Beams TrivWriter.prc.
Current Module - Beams the current TrivWriter database.
All Modules - Beams all loaded TrivWriter databases.
Note: Use the Beam menu inside Triv to beam Triv modules.


<Importing Data>
Importing Data

TrivWriter allows you to import data from Memo Pad records or Doc files. You can choose to either Create New Module or Append to Current module. Each record or file must begin with a #triv moduleName line, and in the case of Doc files, that should also be the name of the file. All other keywords are optional during importing and can be entered in TrivWriter later.

Except for question and answer lines, each input line should begin with a pound sign (#). To begin a question or answer line with a pound sign, precede it with a backslash (\). Embedded carriage returns are not allowed. Blank lines are ignored. The complete list of keywords is:

KeywordAbbreviation and UsageExampleComments#triv#triv moduleName#triv Trillionaire_2Required as the first line for both Doc files and Memo records. Should match the file name for Doc files. Do not use special characters that might cause trouble in file names such as semicolons and slashes. moduleName can be up to 25 characters long.#moduleType#m shortDescription#m GenusShort description of module (up to 31 characters).#writer#w authorName#w Robert JenAuthor of the module (up to 31 characters).#created#c creationDate#c July 1, 2003Date the module was created (up to 31 characters).#updated#u updatedDate#u July 8, 2003Date the module was last updated (up to 31 characters).#version#v versionNumber#v 1.1.0Version of module (up to 31 characters).#shortName#s categoryNumber name#s 4 GeographycategoryNumber must be between 1 and 6. name can be up to 20 characters long.#description#d categoryNumber description#d 4 geography and nature triviacategoryNumber must be between 1 and 6. description can be up to 255 characters long.#info#i extraInfo#i The others are New York's, New Hampshire's, and Delaware'sAdditional text displayed at end of the following question when its answer is revealed in Triv (up to 255 characters combined with the question).#note#n writerNotes#n Maybe replace choice d with DenverNotes on the following question for writer's use only (up to 2047 characters).#### comment## This is a comment that is completely ignoredComment that is not imported into TrivWriter.

The remaining lines are question and answer line pairs (do not begin with a pound sign).

Question lines can be up to 255 characters long. For example, What is the capital of Massachusetts?. Each module can have a maximum of 504 questions.

Answer lines should be formatted according to answer type as documented for TrivWriter above except for multiple choice answers:

Alphabetic - All capital letters, 1 to 10 characters long. e.g. BOSTON.
Multiple Choice - List the 4 choices, separated by semicolons (;). The correct answer must be marked by a leading asterisk (*). TrivWriter will format the answer choices in the order listed. E.g., Albany;*Boston;Concord;Dover.
Numeric - 1 to 5 digits. E.g., 90210.
True/False - Lower case t for "true" or f for "false".


When appending to the current module (primarily for Memo Pad records), the #triv keyword is required to identify the record, but is otherwise ignored. It is recommended that the other header tags only be used in the first record.

Each imported record or file should have a multiple of 18 questions and will be padded to a multiple of 18 otherwise.

Here is a sample input file:#triv MyFirstModule#m Genus#w Your Name#c July 1, 2003#u July 8, 2003#v 1.1.0## Category information#s 1 Entertainment#d 1 movie, television, and music trivia#s 2 History#d 2 history and government trivia#s 3 Science#d 3 science and math trivia#s 4 Geography#d 4 geography and nature trivia#s 5 Literature#d 5 literature, art, and religion trivia#s 6 Sports#d 6 sports and games trivia## Start of trivia questions#i Extra info for question 1#n Note for question 1## Comment that won't be importedWhat is the capital of Massachusetts?Albany;*Boston;Concord;DoverWhat is the meaning of life?42## Remaining questions omitted in this example

Note that in addition to the character limits given above, data must also fit in the allotted spaces. You should view each question in TrivWriter to make sure it fits (i.e., 7 or fewer lines when wrapped, with multiple choice options counting as 4 of those lines).

<Import Error Descriptions>
If applicable, the error messages displayed during the import list the line number on which the error occurred and the beginning of the text which caused the error. Here is a complete, alphabetical list of the possible import errors with more details and possible ways to fix them:



"Could not open Doc file" - An error occurred while trying to open the selected Doc file. The database is either corrupt or inaccessible for unknown reasons. If the Doc file isn't in main memory, try moving it there first.
"Data is too long (max ... chars)" - A question, answer, extra information, or notes field is too long. You need to shorten it (the limits are listed in the Keywords Table above).
"Doc file ... has unknown version (not 1 or 2)" - As of this writing, the version of the Doc file (stored in its header) must be 1 or 2, which actually corresponds to whether the data is compressed or not. TrivWriter does not understand other versions, which indicate either an incompatible Doc writer or a corrupt Doc header.
"Doc file ... is empty" - The selected Doc file had no data. Note: this doesn't mean that it is 0 bytes long, since each Doc file has header information as well.
"Duplicate category" - A category number has been found twice for either the Category Name or Category Description.
"Invalid category number found" - Category numbers must be between 1 and 6 (see the Keywords Table above).
"Invalid keyword found" - The second character in a line beginning with a pound sign (#) was not part of a valid keyword. To begin a line with an actual pound sign, precede it with a backslash (\).
"Multiple choice answer is too long" - A multiple choice answer is too long to fit on a single line (including the standard a/b/c/d prefix). Shorten the answer choice however you can (use synonyms, abbreviations, ampersands for the word "and", etc.).
"Multiple choice question does not have correct answer marked with an asterisk" - Each multiple choice question must have one of its answer choices preceded by an asterisk to indicate the correct answer.
"Multiple choice question has fewer than 4 answer choices" - Each multiple choice question must have exactly 4 answer choices (separated by semicolons).
"Question is too long (max 255 chars overflowed when choices appended)" - For multiple choice questions, each answer choice is appended to the question in a standard format. This caused the current question to become too long, so the question or one of the answer choices needs to be shortened.
"Question takes up more than 7 lines" - In the standard (smallest) font, the current question (including multiple answer choices) exceeds 7 lines on the screen. The question or one of the answer choices needs to be shortened.
"Record is too long (max 2 KB)" - The import has found a record (including question, answer, extra information, and notes) that is over 2,048 bytes long. You need to reduce the length of record. It is possible that a missing carriage return has unintentionally concatenated multiple records.
"Sorry, TrivWriter (and Triv) modules are limited to 504 questions. Please create a new module." - The current TrivWriter module has too many questions. If you selected the Append to Current option on the Import screen, then you should select the Create New Module option instead. Otherwise, you will need to split your Doc file into multiple files.
"Sorry, you do not have enough free memory to create more questions." - TrivWriter has run out of memory. This generally means that your device's main memory is full. Use the Launcher's Delete menu option to make some more room.


For each error displayed, there are three buttons you can tap:



Abort - Terminate the import. You will be left with an incomplete TrivWriter module, which you will probably want to delete (it may be useful to see where it ends, however).
Ignore - Ignore the current error but continue the import.
Ignore All - Ignore the current error, continue the import, and ignore all future errors.


<Other Documentation>


In the "Apps" folder, the file TrivWriterDoc.prc is a Doc-formatted version of this file. This file can be installed on your PalmPilot for reference if you have a Doc reader installed. You can download the free PalmReader (http://www.palmdigitalmedia.com/product/reader/browse/free).

In the "Docs" folder the following files can also be found:

TrivWriterDoc.html - Documentation for TrivWriter readable in a web browser such as Netscape Communicator or Internet Explorer.
TrivWriterDoc.txt - Documentation for TrivWriter readable in any text editor.


Triv's VERSION.txt file contains additional release notes for TrivWriter (initially released with Triv 3.4.0).

<Updates and Contact Information>


TrivWriter Version 1.1.1, October 14, 2003
TrivWriter is Copyright (C)2003 by Robert Jen.

The latest copy of TrivWriter (bundled with Triv), Triv data modules, and other PalmPilot and Macintosh software can be found at http://www.rjen.com (specifically http://www.rjen.com/Pilot/Triv.html). Questions, comments, and any other email can be sent to the author Robert Jen at mailto:rjen@rjen.com. Your feedback is much appreciated.