texttodoc(1) · carta

NAME

texttodoc - convert ASCII text to PalmOS-ready e-text

SYNOPSIS

texttodoc [OPTIONS ...] FILES ...

DESCRIPTION

This manual page documents texttodoc, a utility for creating e-texts for perusal on a PalmOS device (3Com/USR/Palm Computing PalmPilot, IBM WorkPad, etc.), using standard e-text reader software.

Input to texttodoc is in the form of ASCII text, possibly including formatting tags (described below). For each input file or URL (http and ftp are supported), texttodoc outputs a PalmOS database, ready to install and read with any one of the popular document readers or editors.

INPUT FORMAT

Input to texttodoc is assumed to be an ordinary text file, with paragraphs separated by one or more blank lines. Each paragraph will be reflowed so that it wraps appropriately when viewed on the palmtop. The input may also contain formatting tags which produce special output:

.HR: Produce a horizontal rule.

.H1/.H2/.H3/.H4/.H5/.H6 text: Produce a heading of the specified level (1-6, 1 being most significant).

.BM/.BOOKMARK text: Insert a bookmark into the output document.

.TITLE text: Set the title of the output document.

.PRE: Begin a section of preformatted text. Everything between this and the end marker is passed through to the output document without reflowing.

./PRE: End a section of preformatted text.

Each tag must appear on a line by itself, and takes up the whole line. Although tags begin with a period (.) by default, the prefix string can be changed with the --tag-prefix option. Unrecognized tags are simply treated as text.

OPTIONS

-h, --help: Show summary of options.

-t STRING, --title STRING: Set the title of the output document. If no title is supplied, the title of the HTML page will be used.

-b, --backup: Set the backup bit in the output document.

-c NUM, --category NUM: Set the category of the output document. The category must be specified as a number from 0 (Unfiled) to 15.

--creator ID: Set the creator ID of the document. The default is "REAd", which is the standard DOC creator ID. TealDoc uses "TlDc".

--type ID: Set the database type of the document. The default is "TEXt"; no others are known to be used at this time.

-T: Set several TealDoc compatibility options; equivalent to "--teal-headers --teal-wrap-headers --teal-hrules --creator 'TlDc'".

-I: Install documents directly onto a connected PalmPilot instead of writing them to the local disk.

-p PORT: Specify the port to which the PalmPilot is connected; the default is /dev/pilot.

--verbatim: Do not reflow paragraphs; pass all text as it appears in the input. (To also turn off tag processing, see --no-tags.)

--no-tags: Do not process tags.

--tag-marker TEXT: Set the text which marks a tag. TEXT may be plain text or it may be a snippet of a regular expression; either way, it is matched only at the beginning of a line.

--teal-headers: Convert HTML <H1> through <H6> elements to TealDoc <HEADER> tags, in a variety of different styles.

--teal-wrap-headers: Current versions of TealDoc do not wordwrap <HEADER> tags; instead, they are cut off at the edge of the screen. With this option, long headers are wrapped into multiple <HEADER> tags so they are entirely readable when viewed in TealDoc.

--teal-hrules: Convert HTML <HR> elements to TealDoc <HRULE> tags. Without this option, horizontal rules are simulated by a string of punctuation (usually asterisks).

--teal-links: Attempt to use TealDoc features for intra-document linking. When a named anchor is encountered, a TealDoc <LABEL> tag is inserted; anchors which target the current document (i.e. HREF beginning with an octothorpe) are annotated with a <LINK> tag. This option is experimental, and is not automatically turned on by the -T (TealDoc) switch.

--teal-bookmarks: Use TealDoc <BOOKMARK> tags instead of setting bookmarks directly into the database. Since the latter method saves space in the file and doesn't require that the document be scanned, it is unlikely that you will need this option; it is included only for completeness, and is not turned on automatically by the -T switch.

BUGS

This is the first release; if you find a bug, please report it to the author.

AUTHOR

texttodoc was written by Rob Tillotson <[email protected]>.