Page Layout Markup Specification
The Page Layout feature provides a mechanism by
which Epic can determine the structure of a document when published, and populate
the document instance with singleton tags that indicate that structure. This
feature can be used to create applications such as those that display a document's
line numbers in both the editor and composed output..
This namespace will be defined by the URL http://www.arbortext.com/namespace/PageLayout
. 1
Types of page layout markup
There are seven new pairs of singleton markup tags used to indicate page layout
in an xml document:
| Element identifiers |
Content model |
Description |
|
atipl:startpage and atipl:endpage |
#EMPTY |
The start and end of a page, as determined by the formatting engine. |
|
atipl:startspan and atipl:endspan |
#EMPTY |
The start and end of the spans on the page. A page typically contains one
or more spans |
|
atipl:startcolumn and atipl:endcolumn |
#EMPTY |
The start and end of the columns within each span. A span will have one or
more columns |
|
atipl:startfloat and atipl:endfloat |
#EMPTY |
Where floats start and end on the page. |
|
atipl:startrow and atipl:endrow |
#EMPTY |
Indicating a table structure, these tags indicate where each row starts and
ends according to the formatting engine. |
|
atipl:startentry and atipl:endentry |
#EMPTY |
Indicating a table structure, these tags indicate where each table entry (or
cell) starts and ends according to the formatting engine. |
|
atipl:startline and atipl:endline |
#EMPTY |
Indicates where each line breaks in the formatted output. Attributes on atipl:startline
reveal the type of content within the line (text, graphics, equation, gentext,
etc.) while the hyphen attribute on atipl:startline indicates if a hyphen
was inserted at the break. |
2
Page Layout attributes
The following are common attributes for all page layout markup.
| Name |
Attribute |
Value |
|
type |
type |
(forced|discretionary) "discretionary" |
|
location id |
location |
(inline|display) "inline" |
|
xmlns:atipl |
xmlns:atipl |
string |
|
error |
error |
string |
|
generic attribute |
attr[1–9] |
any |
The type and location attributes
are used to control the method for generating formatting characteristics for
an element. These attributes interact with the fosi fragments that control
the formatting of the atipl markup.
There are two types of page, span, column, and
line breaks: "discretionary", and "forced". A forced break is one that is
imposed by the document structure (e.g., a "Chapter" element that forces a
new page). A discretionary break is one that was chosen because of layout
rules in the formatting engine (e.g., the page was full).
A discretionary break may happen in one of two locations: "inline", or "display".
An inline discretionary break is one that occurs within a paragraph, that
is between a forced startline and the next forced endline. A display discretionary
break occurs between paragraphs, that is between a forced endline and the
next forced startline. A forced break can never be inline.
When the error attribute of a tag is non-empty it signifies that the
markup could not be inserted into the correct location in the source document.
This can happen, for example, when a page breaks inside of generated text.
The attr1 ... attr9 attributes are
generic attributes that can be used to customize page layout applications.
By convention attr1 is used to display generated text. See section
4 "Default FOSI Fragments" below for information on behavior when some of
these attributes are set.
3
Page layout markup
The following table lists all the page layout markup and each element's associated
attributes. Following the table is a short description of each pair of page
layout singletons. These include descriptions of any attributes that are not
part of the common set of attributes named in the section entitled "Page Layout
attributes".
| Name |
Attribute |
Value |
| atipl:startpage |
number |
NMTOKEN |
|
%commonattrs |
see "Page Layout Attributes" |
|
atipl:endpage |
%commonattrs |
see "Page Layout Attributes" |
| atipl:startspan |
number |
NMTOKEN |
|
columns |
NMTOKEN |
|
%commonattrs |
see "Page Layout Attributes" |
|
atipl:endspan |
%commonattrs |
see "Page Layout Attributes" |
| atipl:startcolumn |
number |
NMTOKEN |
| %commonattrs |
see "Page Layout Attributes" |
| atipl:startfloat |
class |
CDATA |
| flid |
CDATA |
| pagetype |
CDATA |
| %commonattrs |
see "Page Layout Attributes" |
| atipl:endfloat |
%commonattrs |
see "Page Layout Attributes" |
| atipl:startrow |
number |
NMTOKEN |
| %commonattrs |
see "Page Layout Attributes" |
| atipl:endrow |
%commonattrs |
see "Page Layout Attributes" |
| atipl:startentry |
number |
NMTOKENS |
| vspan |
NMTOKENS |
| hspan |
NMTOKENS |
| %commonattrs |
see "Page Layout Attributes" |
| atipl:endentry |
%commonattrs |
see "Page Layout Attributes" |
| atipl:startline |
typemask |
CDATA |
| %commonattrs |
see "Page Layout Attributes" |
| atipl:endline |
hyphen |
NMTOKEN |
| %commonattrs |
see "Page Layout Attributes" |
atipl:startpage and atipl:endpage
The startpage markup indicates the start of a page,
as determined by the formatting engine. It has an attribute number that
gives the sequential page number. This is not the same as the "folio" that
may be printed on the page by a particular stylesheet.
The endpage markup indicates the end of a page.
atipl:startspan
and atipl:endspan
The start and end of a multi-column area (called
a span) is indicated by the startspan and endspan markup. For example, a page
that contains two column text followed by a page wide table will consist of
two spans. The span number, which is reset on every page, is indicated by
the attribute number. The number of columns in each span is indicated
by the attribute columns.
atipl:startcolumn
and atipl:endcolumn
Columns within a span are indicated by the startcolumn
and endcolumn markup. startcolumn has a number attribute which indicates
the column number.
atipl:startfloat
and atipl:endfloat
Floats are parts of a document that do not appear
in document order. Rather, floats appear at the top or bottom of a page, span,
or column. The startfloat element has class, flid, and pagetype
attributes that refer to fosi concepts associated with every float.
atipl:startrow and atipl:endrow
Tables are marked up by indicating the rows and
columns. To indicate these structures, the startrow, endrow, startentry and
endentry markup is used. The number attribute of startrow is reset
on every page.
atipl:startentry
and atipl:endentry
Tables are marked up by indicating the rows and
columns. The startrow, endrow, startentry and endentry markup is used. The
number attribute of startentry is reset in every row. The tag atipl:startrow's
has attributes vspan and hspan which indicate that an entry
is spanning. The former indicates the number of cells spanned vertically,
the latter indicates the number spanned horizontally.
atipl:startline and atipl:endline
The startline and endline markup indicates the
lines selected by the formatting engine. The content of a line is indicated
by the typemask attribute. The bits that may appear in typemask
are given by the following table:
| Plain |
Gentext |
Content |
|
0x1 |
0x2 |
characters |
|
0x4 |
0x8 |
ruling |
|
0x10 |
0x20 |
kern, kernto, hyphpt, hardsp, passthru |
0x40 |
0x80 |
character fill (leader dots) |
|
0x100 |
0x200 |
graphic |
|
0x400 |
0x800 |
display equation |
|
0x1000 |
0x2000 |
inline equation |
|
0x4000 |
0x8000 |
forced line break |
Given these attributes, it is possible to discriminate
between generated text and document text. Often, lines that consist entirely
of generated text will behave differently in an application. For example,
they may not be numbered.
If a line ends in a hyphen, the character code
of the hyphen is put into atipl:endline's hyphen attribute.
4 Default FOSI Fragments
The page layout structure tags that are used to
embellish the document instance control the formatting of the instance for
both the screen and the printed output. The fosi fragments that determine
the formatting are in the file atipl-eic.fos in the Epic-install/lib directory.
This file documents the formatting characteristics of each type of tag. Some
of these are exposed to the user by setting generic attr1, attr2
, etc. attributes. Other formatting characteristics can only be changed
by editing the fosi fragment. To do this copy the entire file into your own
fosi and then make your edits. On a subset of atipl markup, the behavior of
some of the generic attributes is already defined in the FOSI fragments. The
following list describes the effect of setting those attributes.
atipl:startpage and atipl:endpage
The folio may be set for the attr1 attribute.
If the folio is set then it will appear as part of the line number. The format
of the line number will become "folio,\-\,lineno". The type of page to force
is controlled by the attr2 attribute. Valid values are: "next", "verso"
and "recto". The default is not to force a page break.
If the attr2 attribute is the string "fill",
then underfull errors will not be reported for this page and the page will
not be stretched if it is short.
atipl:startcolumn
and atipl:endcolumn
To force a column break, set attr2 to on
atipl:startcolumn to "force".
atipl:startline and atipl:endline
The default behavior defined in the FOSI fragments is to place the value of
attr1 into the output as generated text. (See also the startpage attr1
attribute.) The margin where the line numbers appear in the printed
output is indicated by attr2. This must be either "left" or "right".
It defaults to "right". The quadding of the number, relative to the page
center, is given by attr3. This only valid values are "in" and "out".
The default is "out". The end of a line may require special treatment at
the very end of a paragraph (where the break is no longer discretionary) and
for lines that have been modified. If they are modified and the line ends
up being too short it looks bad to stretch the line a lot (and underfull lines
are reported by the formatting engine). These lines should be ended with a
special "filler" space. The formatter will do this if attr2 is set
to "fill" on the atipl:endline tag.
5
Example Transformation
The following example illustrates the addition of atipl markup to a document
instance, and how the resulting composed output might appear. First the layout
tags are added to the document after which application code walks the document
and changes some of the attributes of those tags to suit the application.
The Original Document
The original document contains a book root element
and a paragraph element. The book “e-i-c” forces a new page set,
while the paragraph e-i-c just forces a new line.
<mybook>
<p>It was a dark and stormy night</p>
</mybook>
The Embellished Document
Consider the following sample document instance.
Assume that, when previewed using a FOSI, a discretionary line break occurs
between the words "and" and "stormy".
When the atipl markup is added, we get the following
embellished document instance:
<mybook><atipl:startpage type="forced" location="display">
<p><atipl:startline type="forced" location="display">
It was a dark and<atipl:endline>
<atipl:startline type="discretionary" location="inline">
stormy night<atipl:endline>
</p>
<atipl:endpage></mybook>
Notice that the start and end page markup was
inserted just within the mybook
element. However the start and end line markup must be inserted
inline, meaning within the paragraph.