Making pagination controls accessible to DITA writers

[chrispitude]

In our DITA flow, I used my RelaxNG DITA grammar creator (https://github.com/chrispy-snps/DITA-plugin-utilities) to create a specialized pagination attribute constrained to a set of values:

Code: Select all

 <attributedomain filename="paginateAttMod.rng" domain="paginate">
  <specialize attribute="paginate" from="base" model="(keep-with-next|keep-with-previous|top-of-page)*"/>
 </attributedomain>

Oxygen XML Author is clever enough to present only the allowed attribute values to our writers. In this example, I apply a keep-with-next directive to the paragraph before a figure:

paginate.gif

In Oxygen PDF Chemistry, our CSS file applies the pagination properties as follows:

Code: Select all

@media print {
  *[paginate~="keep-with-next"] { page-break-after: avoid; }
  *[paginate~="keep-with-previous"] { page-break-before: avoid; }
  *[paginate~="top-of-page"] { page-break-before: always; }
}

We have similar specialized attributes for cross-reference format and table/example/inline style controls:

Code: Select all

 <attributedomain filename="xformatAttMod.rng" domain="xformat">
  <specialize attribute="xformat" from="base" model="(\(equation\)|appendix|chapter|command|endnote|equation|example|figure|footnote|heading|page|partdiv|section|step|table|topic|unknown|_uselabel|_onpage)*"/>
 </attributedomain>

 <attributedomain filename="styleAttMod.rng" domain="style">
  <specialize attribute="style" from="base" model="(bold|italic|wide|smallfonts|tight)*"/>
 </attributedomain>

I wanted to share our approach in case it was useful to someone.

- Chris

[chrispitude]

I added the following alternate CSS file that the user can toggle on and off:

Code: Select all

/* implement visual markers for pagination properties */
*[paginate ~= "top-of-page"]::before(1000) {
	display: block;
    content: '\00a0';
    height:5px;
    border-top:5px dashed #f00;
    margin-left: -1000in;
    margin-right: -1000in;
}
*[paginate ~= "keep-with-previous"] {
    border-top:5px dotted #0f0 !important;
}
*[paginate ~= "keep-with-next"] {
    border-bottom:5px dotted #0f0 !important;
}

This makes the top-of-page dividers (red) and keep-with-previous, keep-with-next properties visible as follows:

pagination.png

[RAYTECH]

Hi Chris
With great interests, I walked through the instructions as indicated above, the generic plugin works perfectly well.
Because we are dealing with similar pagination requirements, my questions to you :
1. to port your html5 extension XSLT, is a RNG process required? It is not clear to me why, for a generic output class, the RNG based statement is attached to every type of DITA topics. What is that for?
2. to associate the alternate CSS for users to toggle on/off from within Oxygen, what are the procedure to do?
In particular, to make the output class visual marker work, what is the procedure? In other words, without a Pagenate attribute value, what is the procedure to develop such a visual marker?
Thank you in advance,
Ray

[chrispitude]

Hi Ray,

DITA supports three DITA schema formats - XSD, DTD, and RNG (RelaxNG). My DITA specialization utility creates RelaxNG schemas because RelaxNG is the easiest and most powerful of the three schema formats. You could also specialize a @paginate attribute in DTD, but I do not know how to do that. You could also skip specialization entirely and use @outputclass for pagination controls.

To provide visual pagination highlighting in the Oxygen editor that can be toggled on/off, I created an alternate CSS style as described here:

Configuring and Managing Multiple CSS Styles for a Framework

[RAYTECH]

Thank you for your reply! This works perfectly well even with an Outputclass enabled approach.

[chrispitude]

Hi Ray,

I'm glad you got it working!

Since my original message in 2019, we also support two additional properties, keep-together and allow-breaks-inside:

Code: Select all

*[paginate~="keep-together"] { page-break-inside: avoid; }
*[paginate~="allow-breaks-inside"] { page-break-inside: auto; }

For keep-together, I use the following editor CSS:

Code: Select all

*[paginate ~= "keep-together"] {
    background-color: #cfc !important;
}

I did not implement any editor highlighting for allow-breaks-inside (but there's no reason you couldn't).