RbMake Class

Overview

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 RbMake_cleanup().

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, and RbMakeFinishInfoFunc.

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 list).

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 previously-added page).

Next, you call RbMake_create() to start the .rb file itself going.

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 the rest.

Finally, you call RbMake_finish() to finalize and close the .rb file.

RbMake Options

Here are the available options that you can set in the RbMake object:

RbMake_{get,set}AllowHRSize0PageBreaks(): 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 works).
RbMake_{get,set}CoverImage(): 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 included.
RbMake_{get,set}CreateHkeyFile(): 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: <P><BIG><B>word(s)</B></BIG>definition</P>.
RbMake_{get,set}EnhancePunctuation(): Set this to "1" if you want single and double quotes to be changed into their "curly" variety, while also changing multiple adjacent dashes into emdashes.
RbMake_{get,set}FollowLinks(): 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.
RbMake_{get,set}IncludeAudio(): 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).
RbMake_{get,set}IncludeImages(): 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).
RbMake_{get,set}PageJoining(): 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.
RbMake_{get,set}TextConversion(): 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).
RbMake_{get,set}UseBookParagraphs(): 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.
RbMake_{get,set}VerboseOutput(): 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.
RbMake_addMenuItem(): 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).
RbMake_addSubstRules(): 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.

Other Accessors

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 RB_TEXTCONV_* value.

Use RbMake_findIncludeOpt() to turn a string value into an RB_INCLUDE_* value.