RbPage Class


An RbPage object needs to be created for each page that you wish to add to an RbMake object. If you're using the RbFetch routines then you don't have to worry about any of this since the RbFetch routines create all your RbPage objects for you.

If you wish to make your own RbPage objects, you start by calling the RbPage_new() function with a pointer to an RbMake object, the URL of the file you wish to include, and the page-type of the URL (use RB_PAGETYPE_UNKNOWN if you want the page-type to be determined from the filename-suffix of the URL).

Next, you must add the content of the file to the RbPage by putting it into the MBuf object named "content". You do this by calling the function RbPage_appendContent() (one or more times) followed by the function RbPage_finishContent(). This handles everything for you, including sending HTML and text data to the parser in rbhtml.c. You can alternately supply your own data directly into the MBuf (if you know what you're doing).

For instance, an image's binary data can be directly added by using the RbPage_getContent() and RbPage_setContent() accessors. Since RbPage_getConvertImage() is "true" by default for an image, the RbPage_write() function will automatically convert the image into a B&W PNG for you. If, however, you have already placed a B&W PNG file into the "content" object, you should clear the flag by using RbPage_setConvertImage().

You can also just store HTML data directly into the content buffer since RbPage_getParsePage() is set by default for HTML and text pages. If you don't clear this flag (via RbPage_setParsePage()), the page will be parsed automatically and all the extra details are supplied (about how the page is layed out and where things are). The parsing is done by the RbHtml routines (which are also used if you call the above-mentioned content-adding functions).

Note also that if the page's substList array is set, the parsing of HTML and text data will be put off until the entire page has fully arrived and we have a chance to run all the substitution rules on the completed page.

Once the "content" is set, you simply call RbPage_write() to write out everything that is needed to represent the high-level page (which might write out one or more low-level page sections to the RbFile object).

Alternately, if something goes wrong during the data-acquisition stage (where you are gathering the data for the "content" object), you should call the RbPage_drop() method instead of the RbPage_write() method. This discards the page.

Use RbPage_getRbMake() to access the RbMake object that this page is associated with.

Use RbPage_makeRbRef() to transform an URL into an internal URI value that is relative to the current page (if possible) or specifies the appropriate ToC filename (and any applicable #fragment data).

Finally, there are a few support routines available for noting the extra details that an HTML page requires. These functions are RbPage_noteHidxName(), RbPage_usedHidxName(), RbPage_noteHidxPara(), and RbPage_delLastHidxPara(). Normally these functions are just used by the RbHtml routines, but if you're writing your own parser, you'll need to use these functions to build up the data that goes into the associated .hidx file.