The RbMake class is used to create new .rb files. You need to have
called the RbMake_init() routine before you begin. When your
program is all done making .rb files, you should call
You start the creation of a new .rb file by calling
RbMake_new(), which returns a new RbMake object. You must pass in
3 function pointers that tell the code where to call-back as various
events happen: RbMakeAllowUrlFunc, RbMakeScheduleUrlFunc,
The first function is called when the code wants to know if an URL
shoud be accepted or not (and it is called for both HREF and IMG-SRC
items). If you return "true", the second function pointer will be called
to schedule the URL for retrevial (which typically means that you just
pass it on to the RbFetch_getURL() function, unless you're not using the
RbFetch class). The final function pointer is called when the .info file
is being finalized and is about to be written out. This function should
manipulate the supplied RbInfoHash as appropriate and then return.
After creating the RbMake object, you can now set whatever options you
desire within the RbMake object (see the separate option section for a
Next, you should call RbMake_addPageName() for each of the
known URLs that you will be adding to the .rb file. When the
"followLinks" option is not set, you need to have told rbmake about all
the upcoming pages or the hyperlinks will break. Even if the
"followLinks" option is set, you have more control over file order
by enumerating all the upcoming pages this way, and then you don't have to
check before adding each page to see if it has already been scheduled to
be included (which can happen if it was referenced in a link on a
Next, you call RbMake_create() to start the .rb file itself
You must now create all the RbPage
objects that need to go in the file and write each one out. The
easiest way to do this is to use the RbFetch
routines since they can take your URLs and do everything necessary to
add the content to your RbMake object.
If you want to add a menu item to the ReB's "Go To" menu, you can use
the RbMake_addMenuItem() function, once per item. You simply
specify the description and the URL as separate pointers, and RbMake does
Finally, you call RbMake_finish() to finalize and close the .rb file.
Here are the available options that you can set in the RbMake object:
- If this is set to "true", it allows the incoming HTML to specify a HR
(horizontal rule) tag with a size of "0" and have this indiate that a page
break should occur. Normally this is disabled, since some web sites can get
spurious page breaks this way. Also, the recommended way to specify a
page break in your source HTML is to use <HR NEW-PAGE> (which always
- Set this to an URL for an image that you want to be placed in front
of all other content in your book. The image is resized to fill as much of
the screen as possible in portrait mode. By default, no cover image is
- If you want to create a dictionary key file for the first HTML file
in a book, set this to "1" and a .hkey file will be generated (and the
info page will be properly modified to indicate that this is a reference
work). You must use the right combination of tags in your HTML to
indicate which words should be indexed:
- Set this to "1" if you want single and double quotes to be changed
into their "curly" variety, while also changing multiple adjacent dashes
- Set this to "-1" if you want the HTML parser to follow any depth of
links to other web pages. Specifying a positive value will limit how many
links deep we will traverse from a manually sheduled page. A
user-callback routine (that was specified via the
RbMakeAllowUrlFunc pointer when "new" was called) is first called
to ensure that you want the URL we found, and if you do, a user-callback
routine (that was specified via the RbMakeScheduleUrlFunc pointer)
will be called. By default, only the pages you schedule yourself are
included in the book.
- Set this to RB_INCLUDE_YES to include audio (.wav) files in your
book. The setting RB_INCLUDE_MATCH is also provided, but it behaves the
same as the "YES" setting -- it is up to your RbMakeAllocUrlFunc
routine to check this option and decide how to limit the audio files that
are included. The default, RB_INCLUDE_NO, includes no audio files (i.e.
the files are ignored without calling the RbMakeAllocUrlFunc).
- Set this to RB_INCLUDE_YES to include images in your book. The
setting RB_INCLUDE_MATCH is also provided, but it behaves the same as the
"YES" setting -- it is up to your RbMakeAllocUrlFunc routine to check
this option and decide how to limit the images that are included. The
default, RB_INCLUDE_NO, includes no images (i.e. the files are ignored
without calling the RbMakeAllocUrlFunc).
- If you set this to "1", all HTML/text pages will be joined into a
single document. If you set this to a larger value, that number of pages
will be joined together into a unified page (this is sometimes needed to
avoid going past the maximum page size limit in the ReB). By default, no
pages are joined together.
- If you set this to RB_TEXTCONV_SIMPLE_PARA, all text files will be
converted into HTML with paragraph breaks marked wherever an empty line
exists. If you plan to do your own conversion of text files into HTML in
some substitution rules you've provided, set this to RB_TEXTCONV_NONE.
The default setting is RB_TEXTCONV_PRE, which translates text files into
preformatted HTML (with all linebreaks intact, and a mono-spaced font).
- Set this to "1" to transform web-style paragraphs (i.e. those with an
empty line between paragraphs) into book-style paragraphs (i.e. with
indentation on the first line rather than a preceding empty line). The
default is to leave the paragraphs in web-style.
- If you set this to "1", the HTML parser will output any HTML errors
and warnings it finds to to the RbError_warn() function. The
default version of this function outputs the error to stderr, but you can
override this using the RbError_init() call. See the
RbError routines for more details.
- You can use this to add items to the "go to" menu (and rbmake takes
care of the low-level specifics of adding the menumark file).
- Calling this routine with an MBuf containing text to parse will add
the resulting substitution rules to the RbMake object. This causes the
associated rewriting rules to be used to modify HTML and/or text pages as
they get processed.
Use RbMake_getPageCount() to find out how many
text/HTML/image/audio files have been scheduled for inclusion in the book.
Use RbMake_getBinaryCount() to find out how many image/audio
items are scheduled for inclusion in the book (you can subtract this out
of the previous call to figure out how many text pages there are).
Use RbMake_getDoneCount() to discover how many pages have
already been successfully added.
Use RbMake_getHtmlDropCount() to discover how many text/HTML
pages could not be added to the book because the total number of pages
would have exceeded the maximum ToC size.
Use RbMake_getBinaryDropCount() to discover how many
image/audio pages could not be added to the book because the total number
of pages would have exceeded the maximum ToC size.
Use RbMake_getFileName() to discover what the name of the
.rb file is (or is going to be).
Use RbMake_getNewFileName() to discover what the temporary name
of the .rb file is during its creation.
Use RbMake_getInfoHash() to access the RbInfoHash object
that will be used to create the .info file.
Use RbMake_getTextConvOptName() to turn an RB_TEXTCONV_* value
into a human-readable string.
Use RbMake_getIncludeOptName() to turn an RB_INCLUDE_* value
into a human-readable string.
Use RbMake_findTextConvOpt() to turn a string value into an
Use RbMake_findIncludeOpt() to turn a string value into an