Forum Documentation

Where to find documentation

Where can I find information on some of the intriguing features and supported properties of Prince? The Documentation section of the website lists the syntax of properties but falls short of outlining their purpose, usage or effect. In particular I would like to find out about:

clear: inside | outside
float: inside | outside | top-if-necessary | bottom-if-necessary
hyphenate-patterns: url
line-stacking-strategy: grid-height
prince-linebreak-magic: auto


Documentation for some of the newer Prince features is still under development, while documentation for some of the more common CSS properties is available elsewhere online.

The inside and outside values for float and clear map to either left or right depending on whether the current page is a left or right page, making it easier to create duplex layouts. This is similar to the margin-inside and margin-outside properties.

The if-necessary page float values are intended to handle the case where you have a large block, such as a table or a figure, at some point in the text. If the block fits on the page where it occurs naturally in the text, then it will not be floated. But if the block doesn't fit and gets pushed to the next page, then it is likely that it will leave a large amount of empty space at the end of the previous page, which is undesirable. In this situation the block will be floated to the top or bottom of the page instead, and taken out of the normal flow altogether and leave no empty space where it was.

Note that page floats may change in the future, hopefully becoming simpler and yet more powerful. Some signs as to the direction they may go can be found in the CSS 3 working draft for Generated Content for Paged Media.

The hyphenate-patterns property specifies a file to load hyphenation patterns from. An example of such a file (en.hyp) can be seen in the hyph directory of the Prince installation. In future this property will be extended to support multiple hyphenation pattern files, and perhaps even specifying additional hyphenation patterns directly as strings.

The line-stacking-strategy property is from the CSS 3 Line module, and can be used to create layouts in which everything aligns to an integer multiple of the specified line height (the grid height).

The prince-linebreak-magic property applies some extra magic line breaking to try and break lines intelligently even in the absence of whitespace. Currently this involves breaking up URLs that would otherwise be treated as very long words. I've updated the documentation for this property, which also incorrectly stated that the property was not inherited, when in fact it is.
Thanks, some useful and interesting features there!