Loose Leaf Publishing Using Antenna House Formatter and CSS for Pagination

LOOSE-LEAF PUBLISHING
UsingAntenna House and CSS
Eliot Kimber
Contrext
Balisage 2019

About the Author
■ Independent consultant focusing on DITA
analysis, design, and implementation
■ Doing SGML and XML for cough 30 years cough
■ Founding member of the DITATechnical
Committee
■ Founding member of the XMLWorking Group
■ Co-editor of HyTime standard (ISO/IEC 10744)
■ Primary developer and founder of the DITA for
Publishers project (dita4publishers.org)
■ Author of DITA for Practitioners,Vol 1 (XML Press)
Balisage Pre-Conference Symposium 2019 2

Agenda
■ What?
■ Why?
■ CSS paged media
■ Producing Point Pages
■ Conclusions and Further Work

WHAT?

The Client: Municode
■ Leading supplier of
municipal code
■ 2000+ clients
■ Replacing outdated
typesetting system that was
obsolete 20 years ago
– But it does loose leaf
■ Shifting focus from print to
digital
■ Print still essential
■ Looking for process
improvements

Target System
■ CSS for pagination
■ Antenna House Formatter
for rendering to PDF
■ Custom processing to
implement loose leaf
■ Same source used for web
delivery
■ Source authored as highly-
constrained HTML5
■ Change boundaries are
marked manually
– Automatic detection of
changes is not a
requirement

What Is Loose Leaf?
■ Pages that reflect changes
from the previously-
published version
■ Page numbers are not
changed
■ If pages are added, create
“point pages”: 12.1, 12.2, etc.

WHY LOOSE LEAF?

The Use Case: Municipal Code
■ Muncipal code is the codified
laws for a city, town, county
or similar legal entity
■ Can be 1000s of pages
■ Updated frequently
– Every city council meeting

Why Loose Leaf?
■ People who use the code
depend on their paper copies
■ Would be impractical to
republish and redistribute for
every update
■ Loose leaf is the only
practical solution for paper
updates here

Why CSS for Pagination?
■ Client insisted on it
■ Authoring directly in HTML5
■ Wanted to use a standard
technology
■ Did not have XSL-FO skills
and knowledge
■ Did not have XSLT skills and
knowledge
■ Layout requirements are
challenging but still
achievable (mostly)
■ Compelling cost advantages
– Easier to implement
– Separation of concerns
– Can hire CSS people

Why Antenna House Formatter?
■ Most complete CSS paged
media implementation
■ Demonstrated ability to
meet layout requirements
■ Mature product with good
reputation

CSS FOR PAGINATION

CSS Paged Media
■ Adds rules, properties,
values, etc. to CSS
specifically for paged media
■ Page master definition
■ Page edge regions (running
heads and feet, etc.)
■ Generated text features
■ Additional typographic
features
■ Scattered across a number of
different specifications
■ Not fully baked

Practical CSS Pagination Realities
■ Today only commercial tools
provide sufficiently complete
implementations
■ Proprietary extensions are
required to meet many
layout requirements
■ Need to preprocess HTML or
generate HTML from non-
XML source
■ Specs are constantly
changing
– Hard to find answers to
some questions
– Hard to keep up with
changes
■ No single source of practical
instruction (today)
– See Liam Quin and me

CSSValue Proposition
■ Easy syntax to learn and use
compared to XSL-FO
■ Cleaner separation of
concerns between data
processing and visual design
■ Can share core CSS with
browser and paged
deliverables
■ CSS is “cool”
■ XSL-FO is “what the heck is
XSL-FO?”
■ Complexity of required XSLT
much lower
■ On balance: compelling
solution

“Augmented HTML” is Required
■ CSS can only decorate
■ Need to synthesize:
– Tables of contents
– Indexes
– Complex running heads and
feet
■ Can simplify CSS by adding
containers or attributes
■ CSS has selector limitations
– Can’t look ahead
– May require new classes
based on descendants or
following elements
■ May need to reorder or
otherwise modify source as
authored

CSS Example: @page Rule—Defines a
page master
@page portrait-first:right {
size: 8.5in 11in;
margin-left: 7.5pc;
margin-right: 7.5pc;
counter-reset: footnote;
counter-reset: page 1;
@bottom-left {
content: element(updateLabel);
vertical-align: top;
margin-top: 1pc;
font-family: "New Century Schoolbook", serif,
'Arial Unicode';
font-size: 8pt;
}
@bottom-center {
content: string(prefolio, first) '200B’
counter(page) '200B’
string(postfolio, first);
margin-top: 1pc;
font-family: "New Century Schoolbook",
serif, 'Arial Unicode';
font-size: 10pt;
}
@bottom-right {
content: '00a0';
margin-top: 1pc;
font-family: "New Century Schoolbook", serif,
'Arial Unicode';
font-size: 10pt;
}
}

CSS Example: Start A Page Sequence
section[data-type = 'loep'],
section[data-type = 'supphistory']
{
page: portrait-first portrait;
break-before: right;
}

Differences from XSL-FO
■ Any element can start a page
sequence
■ Edge region model different
(and more limited)
■ No table markers
■ No index entry features
■ No concept of “folio”–page
numbers are just counters
■ No flow model
■ Can use CSS grid (if
implementation supports it)
■ See LiamQuin for details

PRODUCING POINT
PAGES

The Challenges
■ Identifying pages in the
change set
■ Determining page numbers
for pages
– Changing page number
from formatter-assigned
page number
– Constructing point page
numbers
■ Ensuring change sets end on
even pages
■ Updating page numbers
■ Capturing page history
■ Generating full-doc tables of
contents

General Solution:
Post Process the AreaTree
■ AHF can produce an “area
tree” document
■ XML representation of the
formatted pages
■ AHF can take area tree as
input to produce final forms
(PDF, etc.)
■ Area tree is not standard but
is reasonably stable
■ Structure is logical and easy
to understand
<AreaRoot xmlns="http://www.antennahouse.com/names/XSL/AreaTree"
font-size="10pt" is-first="true" is-last="true" version="605.0"
is-CSS="true" display-role="root">
<PageViewportArea output-volume-break="false" generated-by="html" counter-reset="footnote"
is-first="true" is-link-destination="true" id="x99999" width="612pt" height="792pt"
abs-page-number="1" orig-abs-page-number="1" page-number="1" format="1" stacking-context="true"
display-role="root" in-job="false">
<PageReferenceArea generated-by="html" is-first="true" is-last="true" width="612pt"
height="792pt" display-role="block">
<PageRegionViewportArea region="none" generated-by="html" counter-reset="footnote"
is-first="true" is-last="true" top-position="36pt" bottom-position="36pt"
left-position="36pt" right-position="36pt" width="540pt" height="720pt" region-name=""
display-role="root">
<PageRegionReferenceArea generated-by="html" is-first="true" width="540pt" height="720pt"
display-role="block">
<BlockArea line-height="14pt" generated-by="html" text-align="justify"
font-family=""New Century Schoolbook", serif" display="block" id="x99999"
font-size="10pt" is-first="true" bottom-position="395.75pt" width="540pt"
height="324.25pt" display-role="root">

General Challenge:
Injecting Additional Data Into AreaTree
■ Need to capture data needed
for post processing:
– Change set boundaries
– Imposed page numbers
– Source element type types
(section, figure, table,
generated, etc.)
– Page numbers with
structure
■ Three basic solutions:
1. Structured IDs
2. Magic character
conventions
3. Data in unused page edge
regions
■ Use “marker” elements to
inject arbitrary information

Markers and Structured IDs
■ AHF necessarily captures IDs
of all elements that are not
explicitly omitted
■ Use ID values as structured
fields:
<areaTreeMarker
id="take:take-begin:job=S103:d20p61”
/>
<areaTreeMarker
id="marker:section:update-
ins:start:portrait:id=instruction_sheet"
>
■ Use CSS to key on ID values:
div.section-body
areaTreeMarker[id ^= 'take:take-begin']
{
display: block;
break-before: right;
}
section > section +
areaTreeMarker[id ^= 'take:take-end'],
section > section >
areaTreeMarker[id ^= 'take:take-end'],
div.section-body
areaTreeMarker[id ^= 'take:take-end']
{
display: block;
break-after: right;
}

Magic Characters:
Structured Page Numbers
■ Display page numbers have
three parts:
– Prefolio (“CH-1”)
– Folio (the page number)
– Postfolio (“-”)
■ Need to distinguish for post
processing:
– Find page numbers
– Change the number
■ Solution:
– Use @class and @id for page
number references:


<a id="pageref:d2816e27" class="frontmatter"
href="#x8A66ACBA2357"/>

■ Use non-breaking space to
separate folio parts

ToYour Corner:
Using Page Edge Regions
■ Capture page number
format
■ Capture numeric page
number
■ Use corner regions
<MarginRegionViewportArea
visibility="hidden"
region-name="bottom-right-corner">
<MarginRegionReferenceArea visibility="hidden"
display-role="block">
<BlockArea
visibility="hidden" display-role="block">
<LineArea visibility="hidden" display-role="block">
<TextArea text="^pnf:1" visibility="hidden"/>
</LineArea>
</BlockArea>
</MarginRegionReferenceArea>
</MarginRegionViewportArea>

AreaTree Update Process
1. Set page number and
format
2. Update page numbers
3. Filter pages
4. Renumber absolute page
numbers
5. Final update processing
6. Update page number
database

Updating Page Numbers
■ AHF generates normal
integer page numbers
■ Will need to change some
– Different start page
– Numbers pulled from page
database
– Point page numbers
■ Width of number will likely
change
■ In some contexts, need to
adjust the horizontal position
■ In particular,ToC entries
■ Challenge: how wide is the
new number?

Page Number Widths Solution:
Generate Exemplars in the AreaTree
■ HTML preprocess generates
elements for each character
in each font and size:
<char-samples
id="util:char-samples">
<char-sample class="body">
<char-set class="number-set sz8pt"
id="util:char-set:body-sz8pt"
>
<decimal>.</decimal>
<char>0</char>
<char>1</char>
<char>2</char>...
</char-set>
...
</char-sample>
...
</char-samples>
■ In area tree, can look up by font
family, size, and character:
<xsl:key name="char-samples"
match="at:BlockArea[starts-with(@id,
'util:char-set:')]//at:TextArea"
use="at:make-char-sample-key(@font-family,
@font-size, @text)"
/>
...
<xsl:variable name="key" as="xs:string"
select="at:make-char-sample-key(
$font-family,
$font-size,
$text)"
/>
<xsl:variable name="result" as="element()?"
select="key('char-samples’,
$key,
root($context))[1]"
/>

Page Number Database
■ Two parts:
– Record of each physical
page
– Mapping of elements to the
pages they started on
■ Updated when final version
is published
■ Serves:
– Update instructions
– List of effective pages
– Supplement history
– Table of contents
■ Implemented as a version-
controlled XML file today

SUMMARY

In Summary
■ It works!
■ Not that hard once I figured
out how to do it
■ CSS offers compelling
advantages…
■ …but requires commercial
solutions today
■ Hand marking of change sets
avoids a hard problem
■ Area tree is proprietary but it
is not opaque

More to Be Done
■ Automatic detection of
changes
■ Auto-insertion of changed
pages
■ Better automate capturing
legacy page number data
■ Refine inefficient processing
■ Clean up area tree before
generating PDF
■ More robust page database

Resources
CSS: https://www.w3.org/TR/#tr_Cascading_Style_Sheets_(CSS)_Working_Group
Antenna House Formatter: https://www.antennahouse.com/formatter/
CSS Pagination Book (rough draft): https://drmacro.github.io/css-pagination-book/
CSS training (Liam Quin): https://www.delightfulcomputing.com/course-css-for-
xml-people.html
Graham,Tony. “Decision making in XSL-FO formatting.” Presented at Balisage: The
Markup Conference 2013, Montréal, Canada, August 6 - 9, 2013. In Proceedings of
Balisage:The Markup Conference 2013. Balisage Series on MarkupTechnologies, vol.
10 (2013). https://doi.org/10.4242/BalisageVol10.Graham01.

Loose Leaf Publishing Using Antenna House Formatter and CSS for Pagination

More Related Content

More from Contrext Solutions

Recently uploaded

Loose Leaf Publishing Using Antenna House Formatter and CSS for Pagination