Page classes at work¶

The classes of Page breaks you write and Landscape pages are written on the blocks of this page for real, so this documentation’s PDF does what each block below says it asks for. On screen they change nothing, and this documentation’s public site, built with Sphinx, prints the page as ordinary pages. The ubc build html site styles the classes for print, so a browser printing that build breaks before the section and after the paragraph that ask for it, and turns the table’s pages — though it does not break before the need card, which its print styles leave in place, and it keeps the container on one page when the paper can hold it, as Letter and A4 do.

Each page class is a class on a block: a span of text marked with one breaks nothing, and a class written above a section title is the section’s, so break-after there falls after its last subsection. Where no page can end — a table cell, a footnote — a page class is refused and reported.

A section that starts a page¶

This section is classed break-before, written above its title, so in this documentation’s PDF its heading opens a new page. The spellings this builder reads:

The page classes, and how each is spelled¶
Written	Asks for
`break-before`; `break` on a table, a `needtable` or in a need’s (or a `needextract`’s) `:style:`; a raw `\newpage` (or `\clearpage`, `\pagebreak`, `\cleardoublepage`)	A new page before the block
`break-after`	A new page after the block
`keep-together`, `dont-break`	The block on one page, when a page can hold it
`landscape`, `ssp-landscape`	Landscape pages for the block
`portrait`, `ssp-portrait`	Portrait pages, inside a landscape section

There is no keep with next class: a heading keeps the first lines under it, and a line ending in a colon the block it introduces. Other blocks a page can hold stay together in a container classed keep-together, as the paragraph and table below do.

A container classed keep-together

.. container:: keep-together

   This paragraph and the table below are one ``container``
   classed ``keep-together``.
   The room left above cannot hold them both,
   so in this documentation's PDF they start the next page together.
   The table lists what the builder keeps together without being asked.

   .. list-table:: What stays together without a class
      :header-rows: 1
      :widths: 70 30

      * - Kept together
        - Tuned by
      * - A heading and the first three lines under it
        - ``heading_keep_lines``
      * - A line ending in a colon and the block it introduces
        - ``keep_introducers``
      * - Two lines of a paragraph, a listing or a table's body
          on each side of a break
        - ``orphans``, ``widows``
      * - A caption and its picture, or a listing's caption and its first lines
        - —
      * - An admonition's title and its body, or a need card's header and its body
        - —

This paragraph and the table below are one container classed keep-together. The room left above cannot hold them both, so in this documentation’s PDF they start the next page together. The table lists what the builder keeps together without being asked.

What stays together without a class¶
Kept together	Tuned by
A heading and the first three lines under it	`heading_keep_lines`
A line ending in a colon and the block it introduces	`keep_introducers`
Two lines of a paragraph, a listing or a table’s body on each side of a break	`orphans`, `widows`
A caption and its picture, or a listing’s caption and its first lines	—
An admonition’s title and its body, or a need card’s header and its body	—

A need that starts a page¶

A need takes no rst-class; its :style: carries page classes and bundles. In this documentation’s PDF this card starts a new page:

A need whose style breaks the page

.. my-req:: A requirement that starts a page
   :id: M_PDF_PAGE_BREAK
   :style: break, spotlight

   Its ``:style:`` is ``break, spotlight``:
   the bare ``break`` is sphinx-simplepdf's spelling
   of ``break-before`` on a need,
   and ``spotlight`` is a bundle of this documentation's,
   which in its PDF draws the card's frame in the brand.

My Requirement: A requirement that starts a page M_PDF_PAGE_BREAK

style: break, spotlight

Its :style: is break, spotlight: the bare break is sphinx-simplepdf’s spelling of break-before on a need, and spotlight is a bundle of this documentation’s, which in its PDF draws the card’s frame in the brand.

A block that ends a page¶

A paragraph classed break-after

.. rst-class:: break-after

This paragraph is classed ``break-after``,
so in this documentation's PDF the paragraph after it starts a new page.

This paragraph is classed break-after, so in this documentation’s PDF the paragraph after it starts a new page.

This is that paragraph, at the top of a new page in this documentation’s PDF. The table in the next section is classed landscape, so in this documentation’s PDF it starts a page of its own, taking its heading and the paragraph above it along, and the rest of this page stays empty. Without this paragraph in between, that page and the break above would fall in one place — two breaks in a row are one break — and the page could not show which of the two made it.

A table on a landscape page¶

The table below is classed landscape: in this documentation’s PDF it is printed on a landscape page, with this heading and paragraph, and the page after it is portrait again:

The page classes and the class bundles¶
Class	Asks for	Also spelled	Written on	Refused, and reported as	Printed from the site
`break-before`	A new page before the block; a heading or a line ending in a colon directly above moves with it	`break` on a table, a `needtable` or in a need’s (or a `needextract`’s) `:style:`; a raw `\newpage` (or `\clearpage`, `\pagebreak`, `\cleardoublepage`)	Any block, a section (above its title), a `container`	In a table cell or a footnote: `build.pdf_break_unplaceable`	`break-before: page`, but not before a need’s card, and not for a raw `\newpage`
`break-after`	A new page after the block	—	As `break-before`	As `break-before`	`break-after: page`
`keep-together`	The block on one page, when a page can hold it	`dont-break`	As `break-before`	As `break-before`; taller than a page: `build.pdf_keep_together_oversized`	`break-inside: avoid`
`landscape`	Landscape pages for the block, portrait again after it	`ssp-landscape`	A block, a section or a `container` at a document’s top level	In a list, an admonition, a card, a figure …: `build.pdf_landscape_refused`	A landscape page
`portrait`	Portrait pages, inside a landscape section	`ssp-portrait`	As `landscape`	As `landscape`	—
a bundle’s name	The type and colours of the element and all it holds	—	Any block, and a span of text	Not reached (not reported), e.g. a note drawn at the page foot or a placeholder’s two lines	The class’s rule in `extra_css`

In this documentation’s PDF, this paragraph after the table is on a portrait page again.