User Guide

The HTML Book Document

The HTML Book Document is a text file with a list of commands. Commands all have one line and start with a number sign #.

The easiest way to understand HTMLBook is to open HTMLBook and then to open the file "example".

The first line defines the page setup. Unlike HTML where the page dimensions are not defined, we need to define the size of the PDF page:

#pagesetup a4

It opens a file in the same folder which defines the dimensions of the pages. This is an xml file created by Apple. This one defines the default setup for an A4 page. You can create your own pagesetup file with the menu File:Make Page Setup.

In the document, you define the files which should be compiled to a book. For each file you write #file and the relative path to the file.

You can add headers and footers to your document. Define them with the commands #header and #footer.

We then define our margins, because we do not like the default margins of the page setup:

#margins 60 24 20 44

This sets the left, top, right and bottom border of the page. The unit is point (1/72 inch).

We then define the header and footer of each page with a html file:

#header htmlfiles/printheader.html #footer htmlfiles/printfooter.html

These files are small files in the htmlfiles folder. If you inspect them, you can see that the footer files has the words #page and #date. In fact, each page is filtered before it is rendered and the template words (starting with #) are replaced at runtime with actual values.

We also add another filter:

#ignoreafter <hr noshade>

This will remove all the footer text of the HTML files. They end with a ruler, then a date stamp and a link to the main page. We do not want that in the PDF document.

Then we start with the pages:

#file htmlfiles/intro.html #file htmlfiles/features.html #nextpage #file htmlfiles/content.html #nextpage #file htmlfiles/specifications.html

This will place one HTML page after the other into the PDF document. Pages which are too long are broken into pieces. Nextpage forces a pagebreak. Inspect also the content.html file. It contains a table of contents, where the pagenumber are variables with the number sign and the filepath. These variables will be replaced with the respective pagenumbers on runtime.

Run the preview

Select now the menu File:Run. The program parses all HTML files and creates a preview of the pages:

Each page is filtered: Variables starting with # will be replaced by their actual values:
- #date will be replaced by a date string.
- #page will be replaced the current page.
- #[label] will be replaced by a value defined in the dictionary. The dictionary contains:
  - The current page number of each file with the filepath as label.
  - The current page number of each defined anchor with the #anchor command
  - The text for each defined key with the #define command
Also, from each page, parts defined with the #ignorebefore and #ignoreafter commands are removed.
The page is rendered to a preview image.
The page is entered at the current page. If there is not enough space, the page is broken using its content: The program looks for the horizontal line above where the color is entirely white (or whatever background color was chosen).
New pages are created as needed or with the #nextpage command.

A small version of the preview is then visible on the right side of the window. You can browse through the document to see if everything renders as you wanted it. The gray area around the page is the margins defined by the pagesetup file, the gray lines are your margins.

Export to PDF

After running the preview, you can print to PDF. Select the menu File:Print ro PDF and select a file to save to.

You can only print after preview, because the program must build the dictionary from all files. You need also to rerun the preview if you change the document after running the preview.