Make Books | Download | How To Run | Palm Markup Language | Converting | Tips

Palm Markup Language

This page explains how to use the Palm Markup Language (PML) to specify formatting and other information in a text file for later reading using the eReader.

PML commands start with a backslash, "\", and usually consist of a single character after that. Some PML commands are paired, such as those that specify italicized text. Other commands are directives, such as the "\p", which specifies a page break. PML is not meant to be an industrial-strength markup language, but it is easy to understand, easy to parse, and creates high-quality electronic books.

Since PML and Palm DropBook are not without flaws, there is a page of Tips and Pitfalls.

Let's Dive Right In

palmsample.txt contains examples of formatting text, specifying chapters, etc. Use it to start from, or just as an example when making your own books.

The following table specifies the Palm Markup Language commands, and what they do.

\p New page
\x New chapter; also causes a new page break. Enclose chapter title (and any style codes) with \x and \x
\Xn New chapter, indented n levels (n between 0 and 4 inclusive) in the Chapter dialog; doesn't cause a page break. Enclose chapter title (and any style codes) with \Xn and \Xn
\Cn="Chapter title" Insert "Chapter title" into the chapter listing, with level n (like \Xn). The text is not shown on the page and does not force a page break. This can sometimes be useful to insert a chapter mark at the beginning of an introduction to the chapter, for example.

\c Center this block of text; close with \c on beginning of line
\r Right justify text block; close with \r on beginning of line

\i Italicize block; close with \i
\u Underline block; close with \u
\o Overstrike block; close with \o
\v Invisible text; close with \v (can be used for comments)
\t Indent block. Start at beginning of a line, close with \t at end of a line
\T="50%" Indents the specified percentage of the screen width, 50% in this case. If the current drawing position is already past the specified screen location, this tag is ignored.
\w="50%" Embed a horizontal rule of a given percentage width of the screen, in this case 50%. This tag causes a line break before and after it. The rule is centered. The percent sign is mandatory.

\n Switch to the "normal" font, which is specified by the user
\s Switch to stdFont; close with \s to revert to normal font
\b Switch to boldFont; close with \b to revert to normal font (deprecated; use \B instead)
\l Switch to largeFont; close with \l to revert to normal font
\B Mark text as bold. Unlike the \b tag, \B doesn't change the font, so you can have large bold text. You cannot mix \b and \B in the same PML file.
\Sp Mark text as superscript. Should not be mixed with other styles such as bold, italic, etc. Enclose superscripted text with \Sp.
\Sb Mark text as subscript. Should not be mixed with other styles such as bold, italic, etc. Enclose subscripted text with \Sb.
\k Make enclosed text into small-caps; close with \k. Any characters enclosed in \k tags (including those with accents) are made uppercase and are rendered at a smaller point size than a regular uppercase character.

\\ Represents a single backslash
\aXXX Insert non-ASCII character whose Windows 1252 code is decimal XXX. See the PML character table for details.
\UXXXX Insert non-ASCII character whose Unicode code is hexidecimal XXXX. See the Extended PML character table for details.
\m="imagename.png" Insert the named image. See the section on Images below.
\q="#linkanchor"Some text\q Reference a link anchor which is at another spot in the document. The string after the anchor specification and before the trailing \q is underlined or otherwise shown to be a link when viewing the document.
\Q="linkanchor" Specify a link anchor in the document.
 
\- Insert a soft hyphen. A soft hyphen shows up only if it is necessary to break a word across a line.
\Fn="footnote1"1\Fn Link the "1" to a footnote whose name is footnote1, tagged at the end of the PML document. See the section on Footnotes and Sidebars below.
\Sd="sidebar1"Sidebar\Sd Link the "Sidebar" text to a sidebar whose name is sidebar1, tagged at the end of the PML document. See the section on Footnotes and Sidebars below.
\I Mark as a reference index item. Enclose index item (and any style codes) with \I and \I. See Creating Dictionaries for more information.

Examples


\pThis is a new page

\xChapter III\x

\X1Chapter III, part A\X1

\p\C="Introduction"The following story is one of my favorites...

\cProperty of
Gateway Senior High School
\c

\rJustify my love
\r

This stuff is \ireally\i cool.

I just read \uMoby Dick.\u

This is a \obig\o mistake.

Copyright 1917\v Date of magazine serialization \v

\tOnce upon a time
there was a wicked queen
called Esmerelda.\t

Mammals:\T="40%"Lions
\T="40%"Tigers
\T="40%"Bears

He walked away.
\w="80%"
Later that day, he ran into an old friend.

\nIn the normal ways...

The \stitle page\s should be formatted...

I just \bcan't\b believe that you...

This \lREALLY\l is a large tiger...

This \Bbold\B text can be either \l\Blarge bold\B\l or \s\Bsmall bold\B\s.

e\Spx + 2\Sp = 9

C\Sb2\SbH\Sb3\SbO\Sb2\Sb should be used in moderation.

See also \kanteater\k.

The DOS prompt said "C:\\windows\\"

The man said \a147Yeah.\a148

Arrows can point \U2190 left or right \U2192.

A Yield sign looks like this: \m="yieldsign.png".

See the \q="#detailedinstructions"Detailed Instructions\q for how to install your eBook.

\Q="detailedinstructions"\bDetailed Instructions\b - This section
describes how to install an eBook to your handheld device.

Very long words like anti\-dis\-establish\-ment\-arian\-ism may benefit from
the use of soft hyphens.

The Emerson case\Fn="emerson"[1]\Fn will be very important...

For more information, see the \Sd="moreinfo"sidebar\Sd.

\I\Baardvark\B\I \in.\i a large burrowing nocturnal mammal that feeds especially on termites and ants

Footnotes and Sidebars

Footnotes and Sidebars are specified with an XML-like syntax at the end of the PML document. For example,

<sidebar id="sidebar1">
Here's some \itext\i for a sidebar.
</sidebar>

would specify the sidebar to be displayed when the user taps on a sidebar link in the text that was specified using the \Sd tag.

Any text or PML placed after the first footnote or sidebar is ignored as part of the book text.

Sidebars and footnotes can include most PML features, but there are some PML tags that cannot be used inside of a sidebar or footnote.

These include

Chapters \x, \X, \C
Links \q, \Q
Footnotes     \Fn
Sidebars\Sd

See the palmsample.txt file for examples of how to use many of the PML tags.

Images

The following rules are intended to guarantee that images in your eBook will be viewable on all platforms that eReader runs on.

On low-resolution Palm OS handhelds, an image wider than 158 pixels or taller than 148 pixels will be represented in the text by a thumbnail that the user can tap to view the entire image. Images smaller than 158 x 148 will be presented in-line with the text.

On high-resolution Palm OS handhelds (those having screens of 320x320 pixels or more), images smaller than 158 by 148 pixels will be pixel-doubled. Images larger than 158x148 may be shown in-line with the text, if they will fit on the screen.

On non-Palm OS platforms, small images will be scaled up appropriately. Large images will be scaled down to fit on the page; in this case the user can tap on the image to view the entire image and zoom in or out.

For DropBook to find the image, it must be present in a directory whose name matches that of the PML text file. For example, if "pmlsample.txt" contains a reference to an image called "intro.png", then there must be a directory called "pmlsample_img" that contains intro.png. The directory's name is the name of the PML file (without the .txt extension) with "_img" appended.

Images must be in PNG format and cannot be filtered or interlaced. Image depth must be 8 bits or less. Any color table may be used for color images.

Image files must be less than or equal to 65505 bytes in size, since they are embedded into the .pdb format of the book; Palm database records are limited to 65505 bytes in length. Since images are compressed, the actual image displayed by the reader may be much larger than 64K.

Any or all of these restrictions may eventually be removed.

Adding a Title, Cover Art, and Other Meta-information to Your eBook

DropBook normally presents a dialog in which the title and other information for the eBook may be specified. This information may be embedded in the PML file instead.

To specify the eBook title as it will appear in the Open dialog on the handheld, place a block of invisible comment text at the beginning of the file using \v tags. Inside this comment block, put the string TITLE="My eBook", where "My eBook" is replaced with the name of your eBook. It should look something like this:

\vTITLE="Palm Sample Document"\v

You can also specify the author using the AUTHOR meta-tag, the publisher with PUBLISHER, copyright information with COPYRIGHT, and the eBook ISBN with EISBN. A fully-specified set of meta-information might appear in PML as:

\vTITLE="Palm Sample Document" AUTHOR="Sam Morgenstern" PUBLISHER="eReader.com" EISBN="X-XXXX-XXXX" COPYRIGHT="Copyright \a169 2004 by Sam Morgenstern"\v

Cover art: If an image named "cover.png" is present in the eBook, it is assumed to be the cover art for the eBook. See the rules for images for sizing and other information.

Some or all of this information may appear in the book information dialog in eReader, and may be used for other purposes in future products.

Creating Dictionaries

The \I PML tag is used to delimit an index item. Example: \Iaardvark\I

Each entry must start in the normal font. If DropBook shows an error beginning with "No styles permitted before...", there is probably a missing end style tag before the text shown in the error message.

Links, chapters and other PML structures are not permitted in dictionaries. Images, however, are.

A special dictionary entry, "(Front matter)" is shown before other entries in the list of entries, and should be used to include pronunciation symbols and other front matter.

Note that use of dictionaries requires eReader Pro.