Frontmatter and Mainmatter (and sections) — how to use them?

[Cicorione]

Hi Patrick,

I am trying to understand how to use the defaults frontmatter and mainmatter to differentiate the numeration from ToC and body, but I didn't really understand how this works.

Digging into the documentation I read that you can use <ClearPage> to add the attribute matter so I put a ClearPage tag in the record where it is saved the ToC (it is a one pass ToC) and another one in the record where I believe it is starting the body (body uses two records: section opening and section). Unfortunately it didn't work out , thus I moved the ClearPage tag into atPageCreation/Shipout masters but it started breaking things.

Maybe I had better to plan this at the beginning, on the DTP GUI software is usually a trivial stuff so I didn't care enough; or most likely I got this wrong and it doesn't require to change anything in the layout.

Before to write this I searched also in the examples but using matter and definematter I couldn't find anything as example for DefineMatters and generally sections.

Thanks in advance... 🙏

[pgundlach]

I see, there is almost no documentation on this topic. What a shame. I will write something.

[pgundlach]

Here is a small example:

<Layout xmlns="urn:speedata.de:2009/publisher/en"
    xmlns:sd="urn:speedata:2009/publisher/functions/en">
    <Pageformat height="4cm" width="7cm" />
    <Pagetype name="t" test="true()">
        <AtPageCreation>
            <PlaceObject row="1cm" column="5cm">
                <Textblock>
                    <Paragraph>
                        <Value select="sd:current-page()" />
                        <Value>, </Value>
                        <Value select="sd:visible-pagenumber(sd:current-page())"></Value>
                    </Paragraph>
                </Textblock>
            </PlaceObject>
        </AtPageCreation>
    </Pagetype>

    <!-- the defaults: -->
    <DefineMatter name="mainmatter" label="decimal" resetbefore="yes" />
    <DefineMatter name="frontmatter" label="lowercase-romannumeral" />
    <!-- my own definition -->
    <DefineMatter name="patrick" label="uppercase-romannumeral" resetbefore="yes" prefix="P-" />

    <Record element="data">
        <ClearPage matter="frontmatter" />
        <PlaceObject>
            <Textblock>
                <Paragraph>
                    <Value>frontmatter</Value>
                </Paragraph>
            </Textblock>
        </PlaceObject>
        <ClearPage matter="mainmatter" />
        <PlaceObject>
            <Textblock>
                <Paragraph>
                    <Value>mainmatter</Value>
                </Paragraph>
            </Textblock>
        </PlaceObject>
        <ClearPage matter="patrick" />
        <PlaceObject>
            <Textblock>
                <Paragraph>
                    <Value>patrick</Value>
                </Paragraph>
            </Textblock>
        </PlaceObject>
    </Record>
</Layout>

which prints (on each page)

frontmatter 1, i
mainmatter 2,1
patrick 3, P‐I

1,2,3 are the "real" page numbers, i, 1, P-I are the numbers defined by the matter definition. As a bonus, the page numbers shown in Adobe Acrobat are also the ones you see here (i, 1, P-I).

resetbefore makes the page number start again by one.

Think of a classic book where sometimes the page numbers in the table of contents are printed in roman numerals and the rest of the book (starting with 1) with "normal" figures.

[Cicorione]

I have several records combined and pages saved, my layout is not very linear.

Do the sections need to be into a single record or is Publisher "able" to recombine each section even though those are recalled from different records?

[pgundlach]

The data structure is not important. Just the clearpage with the matter name, independent from where you call it.

I cannot guarantee that SavePages / InsertPages works with the matters, since SavePages/InsertPages is very tricky to handle.

[Cicorione]

My layout is ignoring the matters, I placed these definitions on the "head" :

 <DefineMatter name="mainmatter" label="decimal" resetbefore="yes" prefix="b-"/>
 <DefineMatter name="frontmatter" label="lowercase-romannumeral" prefix="i-"/>

And the clearpage into the records that are drawing the pages, however I have a regular numeration without any prefix, is there a way to improve the "protocol" output regarding clearpage actions and sectioning?

Thanks... 🙏

[Cicorione]

Sorry Patrick I rectify my comments, I noticed the pages in the PDF client status bar are displayed as b-1, b-2, etc...

The mainmatter is applied at the wrong page and the frontmatter is ignored altough it is that special ToC page that is saved and recalled later... I am going to try with a custom matter and see what's going to happen...

[Cicorione]

OK, I am not sure what the sections should actually do... The structures of the pages are recognized:

However it doesn't affect the numeration on the pages:

As you can notice the page is A-2 but the number is 3, because it is actually the third page.

Bug? Pebcak? Half & Half? 🤷‍♂️

[pgundlach]

Without seeing a layout.xml, it is hard to tell. I believe the 3 comes from sd:current-page(), to get A-1 and so on, you need sd:visible-pagenumber(sd:current-page())

[Cicorione]

Here we are! That was exactly what I was looking for. 🙏

Let me speak frankly, this is a very important feature that need to be clearly exposed on the documentation. Actually I would say that it would beneficial if sd:visibile-pagenumber() it is by default an alias to sd:visible-pagenumber(sd:current-page()).

At least from your documentation I can't see any other scope to use it for:

Return the user visible page number (as defined by matters) for the given real page number.

Do you agree? 🤷‍♂️

[pgundlach]

Here we are! That was exactly what I was looking for. 🙏

Let me speak frankly, this is a very important feature that need to be clearly exposed on the documentation. Actually I would say that it would beneficial if sd:visibile-pagenumber() it is by default an alias to sd:visible-pagenumber(sd:current-page()).

beneficial: yes, necessary: no. I have added this, next version (4.19.38) will include the default value

At least from your documentation I can't see any other scope to use it for:

Return the user visible page number (as defined by matters) for the given real page number.

Do you agree? 🤷‍♂️

no: You can create a table of content for example and use the visible page numbers of the start pages of the chapters.

I will also “expand” the documentation on matters.

[Cicorione]

That makes sense!
Thanks!

[pgundlach]

Documented in 4.19.38

[Cicorione]

Thank you for expanding the documentation! 🙏