TequilaCat BookReader Shell user manual TequilaCat BookReader home page: http://tequilacat.org/dev/br/index-en.html TequilaCat BookReader Shell user manual This document explains how to read books on your mobile phone, using TequilaCat BookReader. Bookreader understands number of frequently used e-book formats like RTF, TCR, MS Office formats, Adobe PDF etc. Still Bookreader is optimized to view plain text format (TXT), and does not display colors/font styles etc. This help file explains usage of latest version on moment of its writing, TequilaCat BookReader 2.2.8. The contents could be generally applied to all 2.x versions, with some restrictions. Some described features are missing in older versions, other ones are mentioned shortly, another ones are not described, since (I may hope) theyłre self-evident. Please explore the program by clicking buttons options pressing phone buttons etc. I tried to follow user feedback to provide as much user friendliness as I could. General usage You convert e-books on your computer from original format (text, RTF, PDF etc) into Java format, suitable for mobile phones. Then you install these java files youłve created into your mobile phone, in a way recommended for your mobile phone. As these files are installed, they become Java applications on your phone, each application for each java file youłve installed. These are books - when you run them you see the text, can scroll and read. Created Java books are in format of Java Application Archive (JAR). Below I frequently use JAR, it means the same as Java application file, or Java book file. Also (optionally) a JAD file can be created for each JAR file. JAD is short text file containing its JAR file name and size plus some additional info. Some phones require this short JAD file to install created JAR books, some phones do not
refer to documentation to your phone. Each JAR file created by BookReader shell contains the book text, the fonts you selected and the BookReader Mobile Java program (so called MIDlet) that actually displays the book text. BookReader shell window BookReader shell window is split onto several areas. Left top corner contains fields where you fill in a book name youÅ‚re gonna create, and allows you to select a model of your phone. Below you see the task tree where all actions and settings of the BookReader are available. The tasks in the tree are grouped. The first group deals with e-books you convert into BookReader java format, the second group allows changing various options and settings, and the third group allows setting fonts for books, Clicking tasks in the tree brings up related controls at the right side of the window, and performs related tasks. At right side you see options and controls corresponding to the task youÅ‚ve selected in the task tree. At bottom you access the main actions: conversion of books, viewing this help file and exiting the BookReader. Adding books When you start shell first time it contains no books. Now youÅ‚re ready to add new books to convert them into the phone format. BookReader shell understands frequently used e-book formats: plain text, RTF, Adobe Acrobat PDF, MS Office, PDB/PRC (Palm e-books), HLP ? HTML. They are converted into the plain text when creating books, so no colors/font styles/embedded images are displayed on the phone (yet). Also BookReader shell understands frequently used archive formats: ZIP, RAR, HA, ARJ. When you add an archive, all contained books of supported formats are added. Archives may be nested, e.g. RAR may contain ZIP, and ZIP may contain e.g. PDF or PDB e-books. Please note: some formats are optional (require downloads), to keep installation small. You may click an “Add books" task, or drag and drop files from the Windows explorer. The books are added then, and optionally split into chapters if this option is enabled. All the added books are displayed as tree, chapters nodes attached to the book node. When a node is selected its text is displayed at right side, in content preview area. Large books take long time to preview on slow machines, so by default only 2000 symbols are displayed. Checking the corresponding checkbox displays whole text or selected chapter. When you close the BookReader shell, all selected books, their tables of contents and the selected options are stored till next time. Splitting book onto chapters Chapter splitting pane is located above the list of books. It defines how the text will be split into the chapters. If enabled, every added book is split onto chapters. Otherwise you can always re-split chapters with “Reformat chapters" task or small “recycle" button on the pane. The most important option is the list of words starting chapter headers, like prologue, epilogue, and part.  By default also Roman and Arabic letters with dot are considered as chapter headers, like 12. title or XXI. title . Also you may specify that line containing a single number is a chapter header. If the original e-book file has been changed by external program, it is reloaded. So you may edit the file in some word processor to fix the correct chapters, and reformat the text after saving changes. Sometimes default chapter splitting is not good. To make clear table of contents you may merge and rename chapters and books. Note to expert users: Chapter headers are treated as regexp template. Before book splitting, commas are replaced with pipes, and () are added. So Chapter,Part,Foreword is converted into the ^((?:\d+$)|Chapter|Part|Foreword) \d+$ are added if “use single numbers as chapter headers" is opted. Looks familiar, yeah? When “Use regexps" is clicked the field content is not converted
use direct PerlRE, and Power be with you. Selecting various options Most important fields are in top left corners. These are Phone model, Midlet name and Jar file name. Phone model should match your phone. Each phone has its own features and selecting correct model is important. If your exact phone is not listed, try selecting a phone of the same brand. If this does not work, select MIDP1.0 for older phones and MIDP2.0 for newer ones.  MIDP is a version of Java installed in your phone. You can find your exact Java version in tech. manual on your phone. Selecting Phone model affects some options, enabling features available for particular models only, and setting model-dependent fields. Also this defines font preview page appearance. Midlet name is name of book. This is how the java book will be labeled in the list of installed java applications, in the phone. If the book name is too long or contains non-English national letters, the phone may refuse to install it. If you have problems with installation of such books, try renaming them with Latin letters no more than 8-10 characters length. Jar file name is how the created Java book files will be named on your computer. If you opt “create each book in its folder" this is also the name of the folder. Clicking on “Configure" group caption you see the controls defining where Java books will be created, and how. You choose where books will be created: in the specific folder or in the folder of source book. You may protect your books with password. You may choose what to do when the java books are created: open folder, run some program or just do nothing, and define whether the program should exit on successful book conversion. “Change appearance" task brings up selection of icons for java book folders on computer, and for a book in phone. If you opt “create each book in its folder", these folders are optionally pictured with the icon you select. “Set options" item allows selection of java book properties. Most important are Max Jar Size and Text block size. Max Jar Size is maximal size of Java application (Jar file) accepted by your phone. For some phones this information is predefined, but for some newer or rare phones you should try to find it manually. Usually the allowed jar sizes are 50.000 and more. E.g. Nokia 6310 is limited to 32000, Nokia S40 (most their non-smartphones are S40) is limited to 64.000. When a book canÅ‚t fit into the maximal allowed JAR size, itÅ‚s split into several JAR files like book_1, book_2 etc (instead of book_, given JAR file name is used). These files can be installed into phone one by one, or all together. If the java book is created OK but you cannot install it in your phone, the chances are big youÅ‚ve exceeded Jar size limit. Typical reported errors are “Bad Jar File", “Jar file too big". Text block size is a size of a single text fragment. It sounds quite mystic, so IÅ‚ll try to explain this. When the book is converted into the Java book the original text is split onto smaller fragments, which is done to increase performance and convenience of reading. Typically most phones allow for text fragments 30.000 to 100.000 bytes. Old SiemensÅ‚s (up to 45th series, and CF62) allow for maximum 8000 only. When the fragment size is set too small, the number of text fragments grows big; this results in bigger Java book sizes. Also when you read the text fragments are read one by one, freezing book reading for some moments. The smaller the fragment is the more frequent freezes you meet. When the fragment size is set too big thereÅ‚s a risk your phone has not enough free memory. In this case the book will crash when you try to open it (run it) in the list of installed java programs. If you experience crashes when you run successfully installed (downloaded) book, try decreasing this size. ThereÅ‚s no point to make it less than 8000, since errors may occur, and all phones should allow this size at least. Configuring phone keys “Change key mapping" task brings up the key configuration pane. Initially it shows default mapping of phone keys to the actions available in BookReader MIDlet in the phone. You can override existing mapping by right-clicking on key mapping or on empty cell. In the popup menu you can select desired key to bind to the clicked action, or enter key code, or select top menu item "-" to unbind a key from an action. All overridden bindings (different from default ones) are shown in bold. You may also reset key bindings to default keys. You can select standard keys (0-9, *, #, DIAL/Joystick and directions keys), and the key codes for phone specific buttons (Soft keys). If you select the “Key code:" in the “Keys" dropdown list, fill in the key code for the key you want to assign. Actual key codes are shown by BookReader MIDlet in the phone (Info menu->Show key codes). Text preview Clicking on “Fonts/Preview" group caption you see the “Fonts" page. There you define fonts with which a book is displayed, and preview how it looks on your phone. The preview displays roughly how the text will look on your phone. Exactly same text display is hard to achieve, I am sorry but I write BookReader for mobile phones, not for Windows boxes. But still you can estimate how much lines youÅ‚ll see on phone screen, in a given font. By default you see default text in preview. Select a text in text preview on “Books" page, and it will be shown in “Fonts preview" page. If your phone configuration is known to BookReader shell, youÅ‚ll see screen of same size, optionally with the “skin" of your phone. If your phone is not listed, itÅ‚s not a problem - the BookReader Java program automatically retrieves size from the phone, except for some Samsungs and old Motorola models. If you own such Samsung or old Motorola, and thereÅ‚s a white strip under the text in the phone, try entering correct height and clicking “suppress white line". Also you can select color of background and letters (for each font), page margins, word wrap style, position and type of scrollbar. Choosing fonts and colors You may select several fonts for a book, and switch between them later when you read the book on your phone. For each font you select its face, size, color, bold/italic style and orientation (rotation). To read books with phone rotated in your hand, create one or more rotated fonts! Font may be rotated left and right. Displaying a text with rotated font allows better usage of a screen space on screens whose height is bigger than width. Also on some phones the manual scrolling is better when theyÅ‚re rotated. For each font an interline distance can be changed, negative values allow for much more compact text (more lines on the screen). There are 2 types of fonts BookReader can display: phone fonts, and windows fonts. Windows fonts 1) Windows fonts are the fonts installed in your Windows OS. When you create book with Windows font selected, its copy is put in every jar, taking space as 5-20 kilobytes of text or even more depending on character size. The advantage of the Windows fonts: On WinXP, if the “use smooth screen fonts" desktop option is enabled, Windows fonts are “smooth" (MS ClearType technology) which gives much better reading experience on mobile phone screens. Also, only Windows fonts can be rotated. Phone fonts 2) Phone fonts are fonts built into every phone. They donÅ‚t take much space in JAR files, so youÅ‚ll have more text per JAR file. Also, Unicode books (Chinese, Japanese, and other South-Asian languages) can be displayed in phone fonts only. They are of 3 sizes possible in phones: small, regular and big. Their actual pixel size and availability depend on a phone. Some phones have no big or small fonts, so all the phone fonts are rendered as regular. Sizes in the shell are given only as example. BookReader shell cannot know each font pixel size in every model, so you may test it on the phone and adjust a pixel height in the shell for each phone font (by trial and error). Phone fonts cannot be made “smooth", and cannot be rotated. Saving and restoring state of BookReader shell You can save your current state of the shell anytime into the file. Bookreader shell stores settings in BKS files (Book Set); they contain options, fonts and books, including table of contents (chapter list). Later on you may restore the book list and options by opening BKS file or dragÅ‚nÅ‚dropping it, just like opening any book. If you read books on several phones you may create several templates - BKS files without books, with configured fonts/options for each phone, and load them before adding actual books. Please note, the very book texts are not stored into BKS files, only book file paths and chapter list. If the book file has been renamed or removed, next time you start the shell or load BKS file this book will not be loaded. If the book has been modified its table of contents will be reset. Adding new formats support Any archive or text format support may be added into BookReader shell, given that you have an EXE file of converter working from command line. For details refer to the plugins\*.pd files. PD stands for Plugin Description. Also text postprocessors could be configured, that process plain text changing its formatting or encoding. E.g. russian users can enjoy automatic cyrillic encoding recognition. If you want you may configure external text formatters for plain text rectification (removal of empty lines, ends of lines etc). To define a converter as plain text postprocessor, omit extension list from the plugin description. Page design by Tequilacat, Panya