Authoring Tips

Here are some tips for those that are using rbmake to create content for the Rocket eBook:

To indicate a page-break in your file, use the tag <HR NEW-PAGE>. (While this is not the way that the Rocket eBook represents a page break internally, it is an unambiguous indicator to rbmake of what you want to do, and thus avoids any problems with unintended page breaks coming from web sites that use <HR SIZE=0> as a really narrow line.) If you have documents that use the raw line-break tag, give rbmake the -z option or set the Allow-Old-Style-Page-Breaks option in your option file.
If you want book-style paragraphs, don't format them into your document manually. Just use regular <P> tags, give rbmake the -b option, and it will take care of the rest. This gives you the greatest flexibility because you can create both web-style and book-style ebooks from the same source document.
You can include title, author, genre, etc. information right in your ebook's source HTML using META tags and the TITLE. For example:
```
<HTML><HEAD>
<TITLE>War and Peace</TITLE>
<META NAME="author" CONTENT="Tolstoy, Leo">
<META NAME="genre" CONTENT="Historical Fiction">
</HEAD><BODY> ...
```
The full list of what you can put into the NAME attribute is: "author", "ISBN", "publisher", "genre" (starting with version 0.98), and the special tag "rocket-menu" (described next).
If you want to affect what goes into the "Go To" menu on the Rocket eBook, there are three ways you can do this.
1. Put META tags into your source HTML that define the items that you want to create:
```
<META NAME="rocket-menu" CONTENT="Contents=page1.html">
<META NAME="rocket-menu" CONTENT="Maps=page22.html#Maps">
```
  The format of the CONTENT attribute is "description=URL" -- the description is the text that gets put into the Go-To menu, and the URL is the location that the reader will visit if the user clicks on that menu item. A relative URL is relative to the current page, as you would expect.
  Note that you can sprinkle such META tags anywhere in your documents as long as at least one Go-To item gets defined before the first page is complete (using either META tags or options -- see below). The reason for this is that the .info page must include a MENUMARK indicator, and the .info file is written out as soon as the first page is complete (allowing the info page to be the first thing in the file). If you're using the -j (join) option, you don't have to worry about this, because all the source pages get turned into one big destination page, and thus all joined pages get parsed before the first page is stored in the book.
2. Another way to indicate what gets put into the Go-To menu is to use the -g command-line option or the "Menu-Item" option-file option. For instance:
  rbmake -g "Author Afterward=anote.html" foo.html
  and:
  Menu-Item: Index=foo.html#index
3. The final way to add items to the Go-To menu is to use the old kludgey way that the RocketWriter did things. Avoid this method unless you've got old content that already uses it and you just don't want to change it. In this method, you need to format your own menumark.html file, you need to reference the menumark file via a link from your main document, and you need to have link-following turned on. I won't go into any further details of this method, since you don't want to use this unless you've already got things set up this way.
While the Rocket eBook only supports a subset of the HTML 3.2 character entities, rbmake translates the vast majority of the HTML 4.0 entities into characters that the ReB understands. For instance, “ is a left-double-quote character, but rbmake has to translate it into a CP1252 character for the Rocket eBook to be able to render it.
The Rocket eBook only supports a subset of HTML 3.2's tags. Some tags (such as defined-lists and tables) are translated by rbmake into simpler tags that the ReB understands, which helps web documents to look better than they would otherwise. However, if you're authoring your own content, you should keep things fairly simple. The ReB doesn't know about FONT tags, so rbmake translates font-size changes into BIG and SMALL tags using a simple heuristic (starting with version 0.98).

HTML Tags

The rbmake library can handle the following tags in a meaningful way:

A
Anchor items are used for hyper-linking and anchor names.
B
Mark bold text.
BIG
Switch to the large font.
BLOCKQUOTE
Indent the enclosed items a level deeper.
BODY
The body of the HTML page (follows the HEAD).
BR
Force a line break.
CENTER
Center the enclosed items.
CODE
Use a fixed-pitch font for the enclosed text.
DIV
Line-oriented text divisions (nested DIV tags are still buggy).
DD
The definition in a defined list. Must occur inside DL and be preceded by DT.
DL
Defined lists are emulated by rbmake by using paragraph breaks and BLOCKQUOTEs. The result has slightly more empty space than a typical defined-list should have (and which the ReB doesn't support), but it is quite readable.
DT
The topic in a defined list. Must occur inside DL and be followed by DD.
EM
Enclose emphasized text. Since the ReB doesn't support this, we translate it into I.
FONT
Font changes are normally ignored except when the size changes between 1-4 and 5-6. If such a transition happens, rbmake inserts the appropriate BIG/SMALL tag to switch between the two available font sizes.
FRAMESET
This item and all its contents are discarded.
H1-H6
Headings from largest (1) to smallest (6).
HEAD
The heading HTML section (where things like the TITLE go).
HR
A horizontal ruler. Also, <HR NEW-PAGE> marks a page break.
HTML
This tag should enclose the entire document.
I
Mark italic text.
IMG
An image.
LI
A list item (must occur inside either OL or UL).
META
Meta tags provide extra information to rbmake, such as the author of a document, or menu items for the "Go To" menu.
NOFRAMES
This item and all its contents are discarded.
NOSCRIPT
This item and all its contents are discarded.
OL
Start an ordinal list of items (see LI). The Rocket eBook doesn't currently number such lists, but instead treats it just like UL.
P
A paragraph break.
PRE
Enclose pre-formatted text.
SCRIPT
This item and all its contents are discarded.
SMALL
Switch to the small font.
STRONG
Enclose strong (bold) text. Since the ReB doesn't support this, we translate it into B.
STYLE
This item and all its contents are discarded.
SUB
Enclose subscripted text.
SUP
Enclose superscripted text.
TABLE
The ReB doesn't support tables, so we translate them into a containing DIV with nested BLOCKQUOTES for each column element in a row. Spans of columns or rows are treated just like normal items. See TR, TD, and TH.
TD
A table column. Must occur inside a TABLE tag after a TR tag. The rbmake table emulation turns this tag into a nested BLOCKQUOTE.
TH
A table header column. Works just like TD, but should eventually get bolded as well.
TITLE
The document's title (must be in the HEAD section).
TR
The row of a table. Must occur inside a TABLE tag. The rbmake table emulation uses this tag to reset the columns back to 0.
TT
Teletype text (just like "CODE").
UL
An unenumerated (i.e. bulleted) list of items (see LI).