Deprecation note: NewPage

[pgundlach]

The command <NewPage> is now (version 4.5.14) deprecated. Please use <ClearPage> instead.

The problem with <NewPage> is that page ship out is not immediate. See the following example:

<Layout xmlns="urn:speedata.de:2009/publisher/en"
    xmlns:sd="urn:speedata:2009/publisher/functions/en">
    <Pageformat height="7cm" width="6cm" />

    <Pagetype name="t" test="true()">
        <AtPageShipout>
            <PlaceObject>
                <Textblock>
                    <Paragraph>
                        <Value>shipout value: </Value>
                        <Value select="$shipout"/>
                        <Value> page: </Value>
                        <Value select="sd:current-page()"></Value>
                    </Paragraph>
                </Textblock>
            </PlaceObject>

        </AtPageShipout>
    </Pagetype>

    <Record element="data">
        <SetVariable variable="shipout" select="'A'"/>
        <PlaceObject>
            <Textblock>
                <Paragraph>
                    <Value>Should be: B</Value>
                </Paragraph>
            </Textblock>
        </PlaceObject>
        <SetVariable variable="shipout" select="'B'"/>

        <NewPage />

        <SetVariable variable="shipout" select="'C'"/>
        <PlaceObject>
            <Textblock>
                <Paragraph>
                    <Value>Should be: D</Value>
                </Paragraph>
            </Textblock>
        </PlaceObject>
        <SetVariable variable="shipout" select="'D'"/>
    </Record>
</Layout>

which leads to

When you use <ClearPage> instead, everything is fine:

<Layout xmlns="urn:speedata.de:2009/publisher/en"
    xmlns:sd="urn:speedata:2009/publisher/functions/en">
    <Pageformat height="7cm" width="6cm" />

    <Pagetype name="t" test="true()">
        <AtPageShipout>
            <PlaceObject>
                <Textblock>
                    <Paragraph>
                        <Value>shipout value: </Value>
                        <Value select="$shipout"/>
                        <Value> page: </Value>
                        <Value select="sd:current-page()"></Value>
                    </Paragraph>
                </Textblock>
            </PlaceObject>

        </AtPageShipout>
    </Pagetype>

    <Record element="data">
        <SetVariable variable="shipout" select="'A'"/>
        <PlaceObject>
            <Textblock>
                <Paragraph>
                    <Value>Should be: B</Value>
                </Paragraph>
            </Textblock>
        </PlaceObject>
        <SetVariable variable="shipout" select="'B'"/>

        <ClearPage />

        <SetVariable variable="shipout" select="'C'"/>
        <PlaceObject>
            <Textblock>
                <Paragraph>
                    <Value>Should be: D</Value>
                </Paragraph>
            </Textblock>
        </PlaceObject>
        <SetVariable variable="shipout" select="'D'"/>
    </Record>
</Layout>

Since there is a change in semantics you need to update from

(output anything)
<NewPage />
<NewPage />
(output anything)

which creates an empty page while

(output anything)
<ClearPage />
<ClearPage />
(output anything)

does not. To get the same behaviour, you need to force a new page:

(output anything)
<ClearPage />
<ClearPage force="yes" />
(output anything)

You can now set the matter which will be used for the new page:

<ClearPage matter="mainmatter"/>

which sets the matter at the beginning of a new page. See the following example:

<Layout xmlns="urn:speedata.de:2009/publisher/en"
    xmlns:sd="urn:speedata:2009/publisher/functions/en">
    <!-- <Trace objects="yes"/> -->
    <Pageformat height="7cm" width="6cm" />
    <DefineMatter name="beta" prefix="β-" resetbefore="yes" />
    <DefineMatter name="delta" prefix="δ-" resetbefore="yes" />

    <Pagetype name="t" test="true()">
        <AtPageShipout>
            <PlaceObject>
                <Textblock>
                    <Paragraph>
                        <Value>shipout value: </Value><Value select="$shipout"/>
                        <Br />
                        <Value>page: </Value><Value select="sd:visible-pagenumber(sd:current-page())"></Value>
                    </Paragraph>
                </Textblock>
            </PlaceObject>

        </AtPageShipout>
    </Pagetype>

    <Record element="data">
        <ClearPage matter="beta"/>
        <SetVariable variable="shipout" select="'A'"/>
        <PlaceObject>
            <Textblock>
                <Paragraph>
                    <Value>Should be: B</Value>
                </Paragraph>
            </Textblock>
        </PlaceObject>
        <SetVariable variable="shipout" select="'B'"/>

        <ClearPage matter="delta"  />

        <SetVariable variable="shipout" select="'C'"/>
        <PlaceObject>
            <Textblock>
                <Paragraph>
                    <Value>Should be: D</Value>
                </Paragraph>
            </Textblock>
        </PlaceObject>
        <SetVariable variable="shipout" select="'D'"/>
    </Record>
</Layout>

which produces (with two runs!) this output: