dtk(1)

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.

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

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.