--- name: "dtk" section: "1" platform: "linux" package: "palm-doctoolkit" version: "1.1.4" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/dtk" --- # dtk(1) convert various formats to Doc-format e-text ## NAME dtk - convert various formats to Doc-format e-text ## SYNOPSIS **dtk** \[ **-I** *inputformat* \] \[ **-O** *outputformat* \] \[ **-h \| --help** \] \[ *OPTIONS ...* \] *FILES ...* ## DESCRIPTION This manual pages documents **dtk,** the command-line user interface to Doc Toolkit. Doc Toolkit is a modular system for converting various input formats (text, HTML, etc.) into the Doc format, which is the de facto standard for large text documents on the Palm Computing(R) platform. ## OPTIONS The options described in this section are part of the Doc Toolkit core, and are always available. There may be additional options available, depending on the selected input and output formats. ### BASIC OPTIONS - **-h, --help** Show a summary of options, including those specific to the selected input and output format. - **-l, --list-formats** List all available input and output formats. - **-I, --input-format NAME** Select an input format. The default is to use the *Raw* input format, which performs no processing on the input. - **-O, --output-format NAME** Select an output format. The default is to use the *Basic* output format, which writes a plain Doc database. ### DOCUMENT ATTRIBUTES - **-t, --title STRING** Set the title of the output documents. If not specified, Doc Toolkit will try to get an appropriate title from the input, or simply use the filename. (If you are converting multiple documents at once, you probably should not use this option.) - **-b, --backup** Set the backup bit on the output documents. If the backup bit is set, the standard Palm Desktop application will back it up automatically once it has been installed on the palmtop. (Other backup systems, for example Pyrite and BackupBuddy, may use other means to decide what databases to back up.) - **-c, --category NUM** Set the category of the output documents. At present, it is not possible to specify categories by name, only by number, because of how categories are tracked by Doc reader applications. - **-C, --creator STRING** Set the creator ID of the output documents. The default is to use the standard Doc creator ID, but this may be changed by the output format you select. (For example, if you select the *TealDoc* output format, it sets the creator ID to that of TealDoc.) - **-T, --type STRING** Set the type of the output documents. The default is to use the standard Doc type, but this may be changed by the output format you select. ### PYRITE INTERACTION - **-S, --sync** Install the output documents directly onto a connected handheld, without saving them to disk. - **-i, --install** Place the output documents in Pyrite's installation spool, so that they will be installed on the handheld at the next sync. - **-U, --user NAME** With the **-i/--install** option, specify a user name to use instead of the default. ## INPUT FORMATS To select an input format, use the **-I** option. Unless otherwise specified, all input formats are capable of reading input compressed with gzip, and also of fetching input via HTTP or FTP (when a URL is specified instead of a simple filename). ### RAW INPUT The *Raw* input format is the simplest; it simply dumps the contents of the input into the output document as literal data. It has no options. ### TEXT INPUT The *Text* input format is almost as simple as the *Raw* format, except that it attempts to re-flow paragraphs (which are assumed to be separated by blank lines in the input). This process removes the hard line breaks and justification sometimes found in typical text files, and allows the Doc reader on the handheld to more readily reformat paragraphs for the small screen. The *Text* format has no options. ### TAGGED TEXT INPUT The *TaggedText* input format is exactly like the *Text* format, except that it also looks for nroff-like formatting tags in the input. These tags are converted to "formatting events" which can set bookmarks, insert nicely formatted headings, and the like. The standard tags are: - **.HR** Produce a horizontal rule. - **.H1/.H2/.H3/.H4/.H5/.H6** *text* Produce a heading; **.H1** is the most significant, **.H6** the least. - **.BM/.BOOKMARK** *text* Set a bookmark at the current position. - **.TITLE** *text* Set the title of the output document. - **.PRE** Begin a section of preformatted text. Everything between this tag and the end marker is passed through to the output document without paragraph reflowing, tag handling, or other processing. - **./PRE** End a section of preformatted text. Each tag must appear on a line by itself, and takes up the whole line. Unrecognized tags are simply treated as text. The *TaggedText* input format has the following options: - **--case-fold-tags** Allow tag names to appear in lower or mixed case. Otherwise, they must appear exactly as shown above. - **--tag-prefix** *STRING* Set the tag prefix (instead of "."). (This option only applies if you do not supply a custom regular expression using the **--tag-regexp** option.) - **--tag-regexp** *STRING* Set the regular expression used to recognize tags. The regular expression must define two named groups, *tag* and *arg,* which match the tag name and argument(s). ### HTML INPUT The *HTML* input format is nowhere near as sophisticated as the average web browser, but it produces acceptable results given a reasonably well-constructed page. The *HTML* input format has the following options: - **--no-anchor-bookmarks** Normally, each named anchor is bookmarked, on the general principle that if a spot is important enough to be linked to, it is probably a good place for a bookmark. This option turns that behavior off. - **--no-link-footnotes** Normally, each link in the input document is marked with a numbered footnote indicator, and all link targets are listed in a section at the end of the document. This option turns link footnoting off. The *HTML* input format supports the handheld's character set using entities. In addition to the standard ISO8859-1 entity set normally used with HTML 3.2, the following entities from HTML 4 are also supported: - **€** The Euro currency symbol. (Note: Most output formats do not support this character, since it is not part of the standard palmtop character set.) - **Œ** Uppercase OE ligature - **œ** Lowercase oe ligature - **Š** Uppercase S with caron - **š** Lowercase s with caron - **Ÿ** Uppercase Y with umlaut - **ˆ** Circumflex - **˜** Small tilde - **–** En dash - **—** Em dash - **‘** Left single quotation mark - **’** Right single quotation mark - **“** Left double quotation mark - **”** Right double quotation mark - **†** Dagger - **‡** Double dagger - **‰** Per-mille sign - **‹** Left single angle quotation mark - **›** Right single angle quotation mark - **ƒ** Latin lowercase f with hook (mathematical function definition) - **•** Bullet - **…** Horizontal ellipsis - **™** Trademark sign - **♠** Spade suit - **♣** Club suit - **♥** Heart suit - **♦** Diamond suit In addition, the *HTML* input format supports several entities which are not part of any standard DTD: - **&dcomma;** Double comma - **&grafcmd;** Graffiti "command" stroke icon - **&grafsc;** Graffiti "shortcut" stroke icon ## OUTPUT FORMATS To select an output format, use the **-O** option. ### BASIC OUTPUT The *Basic* output format is the simplest: it writes plain text to an ordinary Doc file. It has no options. ### TEALDOC OUTPUT The *TealDoc* output format supports some of the unique features of TealPoint's reader. The creator ID of output documents is set the same as the TealDoc application, and some formatting elements (headings and rules, mainly) are inserted using TealDoc's formatting tags. The *TealDoc* output format has no options. ## BUGS If you are using this package on a Debian system, please use the Debian bug reporting system at **http://www.debian.org/Bugs/** to report any problems you might find. Otherwise, please report bugs directly to the author. ## AUTHOR Doc Toolkit was written by Rob Tillotson \.