#format wiki
#language en
#pragma section-numbers off
#acl IanRiley:read,write,delete,revert,admin All:read
#pragma supplementation-page on

<<TableOfContents>>

= PageBreak =

== Background and rationale ==

MoinMoin renders pages in HTML for display in browsers without pagination, as expected. When printing, different browsers will format the page differently, so sometimes the page breaks will be in awkward places (e.g. widowed headings, split images) and there is no way of controlling where these breaks occur. Also, it can be useful to save the print preview as a PDF (which is easily done under OS X), but likewise the page breaks will be undesirable. A macro to force a page break on printing would be useful, perhaps not for permanent inclusion in the page, but at least for rendering when printing or creating a PDF.

== Description ==

!PageBreak is a macro to insert a HTML division with a forced page break on printing.

Including an argument allows that arguments text to be printed on the page before the break. The argument text is escaped to make sure it is benign.

The argument text is only included in print view, and paging only occurs when printing from print view. 

== Usage ==

=== <<PageBreak(text)>> ===

{{{
Argument "text" is optional.

<<PageBreak>> or <<PageBreak()>> - forces a page break on printing.

<<PageBreak(text)>> - prints the text provided before forcing the page break.

}}}

In practice, the macro might need to be included before the first awkward break, then the page saved and checked for subsequent awkward breaks. 

For a public page, it is recommended that any instances of the macro be removed after printing, because they might not work appropriately on another browser, or if the content of the page is changed. Also, not to clutter the page edit history with such changes, it might be wise to create a temporary version of the page to be printed in the SandBox or under the user's WikiHomePage.

For a private page, that you will be using with the same operating system and browser, and for which you are responsible of any changes to the page content, the instances of the macro could remain.

== Example ==

{{{
...
blah blah
<<PageBreak(continued over)>>
blah blah
...
}}}
|| '''Page 1''' || '''Page 2''' ||
||<style="width: 50%" ^> <<BR>><<BR>>...<<BR>>blah blah<<BR>>continued over ||<style="width: 50%" ^> blah blah<<BR>>...<<BR>> ||

== Download & Release Notes ==
|| Download || Release Version || Moin Version || Release Notes ||
|| [[attachment:PageBreak-1.2.py]] || 1.2 || 1.9.2  ||  ||

== Copyright ==

 . @copyright: 2011 Ian Riley <ian.riley@internode.edu.au>

== License ==

GNU GPL, see COPYING for details.

== Known issues and limitations ==

 * --(Used before headings incompatible with wkhtmltopdf in [[PDF.py|PDF action]]. Only bottom half of heading displayed.)-- Fixed with inclusion of non-breaking space in Version 1.2.

 * --(The text provided in the argument is always included in the page. It would be better if this could be restricted to print contexts only.)-- Added with Version 1.1.

-----

 Hits:: <<Hits>>