FO Page Layout

From ConTeXt wiki

Overview

In FO, one sets up paper size and dimensions at the start of a document and then later calls on these setups. The most straightforward way to accomplish the same thing in ConTeXt is to break the documents into parts, and define page dimensions and layout at each part.

First, let's look at page setup in FO for comparisons' sake:

<fo:simple-page-master  
  master-name="first"
  page-height="11in"   
  page-width="8.5in"
  margin-top="0.5in"   
  margin-bottom="0.5in"
  margin-left="1in"  
  margin-right="1in">

   <!--set up room for a  header-->
   <fo:region-body margin-top="1.0in"/>

</fo:simple-page-master>

Note how both page dimensions (the physical height of a page) and the layout (the margins) are contained in the simple-page-master element. In ConTeXt, these two qualities are separate.

Physical Page Dimensions

Let's build different layouts in a ConTeXt document, starting from top to bottom.

First, let's start with the basic document:

\enableregime[utf]
\setuppagenumbering[state=stop, way=bytext]
\starttext

The \part tells ConTeXt to break a document into the largest division, forcing a page break.

\part{}

Now we'll define the page size for the first part of the document. (Note that part can refer to any generic division; use part for the main divisions, when you want to change page layout.)

\definepapersize[firstPart][width=8.5in, height=11in]
\setuppapersize [firstPart]

We'll add some dummy text :

Some text for our first part.

Let's repeat what we already did, altering our page height from 11 to 10 inches.

\part{}
\definepapersize[secondPart][width=8.5in, height=11in]
\setuppapersize [secondPart]
Text for second part.
\stoptext

Page Layout

We still haven't set up other page qualities like margins. Let's do this now, all at once:

\part{}

\definepapersize[firstdPart][width=8.5in, height=11in]
\setuppapersize [firstPart]

% define layout for first part
\definelayout[
    topspace=.5in, 
    bottomspace=.5in,
    cutspace=1in,
    backspace=1in, 
    header=2in, 
    footer=2in, 
    rightmargin=1in, 
    leftmargin=1in,
    width=5in, 
    height=10in, 
 ]

Text for first part.

The "topspace" value refers to the space at the very top of a page, and is roughly equivalent to the "margin-top" attribute in FO. The "bottompace" value refers to the space at the very bottom of a page, and is roughly equivalent to the "margin-bottom" attribute in FO. The "backspace" value indicates the space in the left of the page and is roughly equivalent to "margin-left" attribute in FO. The "cutspace" value indicates the space in the left of the page and is roughly equivalent to "margin-left" attribute in FO. No text will occur in either one of these regions.

If you pages are not double sided (not part of a book), the "backspace" value will determine how much space occurs between the left edge of the paper and any text. It always touches the "leftmargin" region. If you have a double sided layout, the "backspace" value will flip from right to left side of your pages, but will always be in the gutter, or the spine of a book that is bound.

The values ConTeXt "header", "footer" "leftmargin" and "rightmargin" are roughly equal to the FO <fo:region-body margin-top="2in"/>, <fo:region-body region-after="2in"/>, <fo:region-body region-start="1in"/>, and <fo:region-body region-end="1in"/> respectively. Like their FO counterparts, the ConTeXt values set up margins at the top, bottom, left, and right of the page for marginal notes.

The values "leftmargin" and "rightmargin" have no affect on the actual width of the body text. You could set "leftmargin" to 5in, and your body text would not change its width. When you set width to 5 inches, the width of your body text will in fact be 5 inches. (This contrasts with height, as I explain below.) If you the sum of your "backspace", margins, and width exceed the total page width, your layout will not work.

In contrast, the "header" and "footer" do change the overall height of your body text. If you increased the header by one inch, your body text would be 1 inch smaller. The height actually refers to the total height of the toppace, header, body text, footer, and bottomspace. If you set the header to 2 inches, and set the footer to 2 inches, and set the height to 4 inches, then the actual body height would be:

4 - 2 - 2 = 0 (!)

You would have no room for your body text at all. If you meant to set your body height to 4 inches, you would set height to 8 inches (2 + 2 + 4 = 8).

FO ConTeXt conversions for physical page layouts
FO ConTeXt
<fo:simple-page-master margin-top="x">
\definelayout topspace=x
<fo:simple-page-master margin-bottom="x">
\definelayout bottomspace=x
<simple-page-master margin-left="x">
\definelayout backspace=x
<simple-page-master margin-right="x">
\definelayout cutspace=x
<fo:region-body margin-top="x"/>
\definelayout headerdistance=x
<fo:region-before extent="x"/>
\definelayout header=x
<fo:region-after extent="x"/>
\definelayout footer=x
<fo:region-start extent="x"/>
\definelayout left-margin=x
<fo:region-after extent="x"/>
\definelayout right-margin=x

Changing Layouts for First, Odd and Even Pages

FO lets you create different pages sizes and layouts for the first page, and for odd and even pages. Here is how to do the same in ConTeXt

First Page

In order to define different physical dimensions for your first page, use "1" as your first option:

\definelayout[1][
    topspace=.5in,     % the space at the very top of the page
    backspace=2in,     % the space in the gutter 
    header=2in,        % the space for headers
    footer=2in,        % the space for footers
    leftmargin=1in,    % the space for margin notes
    rightmargin=1.5in, % the space for right margin notes
    width=3in,         % the width of the body text
    height=7in         % the height of the body text
]

Odd and Even Pages

If you simply want to mirror odd and even pages, put this command at the top of your document:

\setuppagenumbering[alternative=doublesided, state=stop]

For more flexibility, you can add a position argument to your \definelayout command.

\definelayout[odd]
             [backspace=1in,
              cutspace=1.25in,
              width=middle,
              height=9in]
\definelayout[even]
             [backspace=1in,
              cutspace=1.25in,
              width=middle,
              height=8in]
\setuplayout % needed to add this or the first page wouldn't format
\starttext
\showframe
\dorecurse{12}{\input dawkins \par}
\stoptext

Creating Headers and Footers

Simple Headers and Footers

In FO, you create headers and footers with the static-content element:

<fo:static-content
  flow-name="even-page">
  Title
</fo:static-content>

With ConTeXt, we place headers and footers in the body of the text wherever we want them with the commands \setupheadertexts and \setupfootertexts. These commands takes 4 arguments, the first for the left margin on odd pages, the second for the right margin on odd pages, the third for the left margin on even pages, and the fourth for the right margin on even pages. For simplicity's sake, let's leave the middle two options empty, so we get headers and footers on the even and odd pages, naturally alligned with the left margin, allowing us to think of the header and footer as one block of text.

\setupheadertexts[left(even) header][] [][right(odd) header]
\setupfootertexts[left(even) footer][] [][right(odd) footer]

Since headers and footers will apper on whatever page you issue these commands, we must define header and footer text after we issue the \part command. If we don't, and ConTeXt needs to put blank pages at the end of a part, these blank pages will erronously contain the headings from the new part.

Controlling the Placement of Headers and Footers

The \setupheader and \setupfooter commands give us some control over header and footer placement. If we want a completely eliminate a header or footer for just one page, we use this command in conjunction with the state=high option, which not only eliminates the text of the header or footer, but the space it occupieds as well, pushing the body text into the header or footer region:

\setupheader[state=high] 
\setupfooter[state=high]

Other values for "state" are "stop", which stops the placement of headers and footers; "start", which starts them again if they have been stopped; "empty", which preserves the space for the header or footer but does not show the text; and none, which completely eliminates both the space and the text for a header or foooter.

We'll not use the \setupheader command in this tutorial, instead relying on other methods.

Changing Headers and Footers for the Firstpage

We have already seen how we place a different header on odd and even pages. To start a different header or footer on the first page, we need the \setuphead command. The command determines the placement of text on the first page of a division in a document, such as part. We will use this command in conjunction with a \definetext command in this way:

\definetext[partStart1][header][Part Header]
\setuphead[part][header=partStart1]
\part{}

For our sake, the \definetext command takes three options. The first is a name you choose to give it. The second is the postion. The third is the text itself.

Once we set up the defintion for the text, we recall it in the very next line in the header=partStart1 option.

Note how we pace the definition for the header before we issue the \part command. This contrast with all the other formatting commands we use for page layout, which come after the \part command.

Formatting Text in Headers and Footers

We'll need special commands to format our text in headers and footers. In order to make justify text left or right, we'll use the \hfill command. The \hfill command tells ConTeXt to fill in as much space horizontal space as possible.

% force the odd header to the right and the even header to the left
% (where it would appear, anyway).
\setupheadertexts[\hfill left(odd) header][] [][right(even) header
\hfill]

% an hfill command on either side of the word middle 
% forces the word to be centered
\setupheadertexts[left \hfill middle \hfill right][] [][right header]

Since ConTeXt won't allow us to create paragraphs in headers and footers as we would in normal text, we need the \vbox command if we want more than one line in a header or footer. The command \vbox stands for vertical box, the basic paragraph unit that ConTeXt uses behind the scenes. In order to break a line inside a \vbox, we use \vskip.

Example Documents

Here are two example documents, illustrating all the formatting. The first is a plain old ConTeXt document. The second is a TeXML document.

page setup1

page setup1 texml

Summary

  • We use the \part command to change page formatting, or put another way, to start a new run of pages.
  • Unlike FO, which defines page formatting at the start of a document, ConTeXt formatting commands are placed in the vicinity of \part.
  • We use \definelayout to set both the physical properties of a page as well as its layout.
  • We place the \setuphead command before the \part command. We place all other commands after \part.
  • The \setuphead command allows us to control the headers and foooters for a new run of pages.
  • We use the \vbox and \hfill commands to format text within a header or footer.


To Do

  • Find out if there is a corresponding value of footerdistnace in FO.