xml-general-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From shan...@apache.org
Subject cvs commit: xml-site/targets/cocoon/howto/images note.gif
Date Mon, 15 Jul 2002 14:05:56 GMT
shannon     2002/07/15 07:05:56

  Added:       targets/cocoon/howto README.txt howto-author-core-docs.html
                        howto-html-pdf-publishing.html
                        howto-paginator-transformer.html
               targets/cocoon/howto/images note.gif
  Log:
  release 2.0.3 update
  
  Revision  Changes    Path
  1.1                  xml-site/targets/cocoon/howto/README.txt
  
  Index: README.txt
  ===================================================================
  Filename conventions
  How-To files in this directory should follow the following naming convention:
  
      howto-<descriptive-name-here>.xml
  
  Use hyphens between any words which follow "howto-". Please make sure your name will be sufficiently unique to distinguish it from future contributions. For example, if you are committing a how-to about Actions, don't name it howto-actions.xml. 
  
  Multi-page How-Tos
  If you are adding in a multi-page How-To to this directory please create a subdirectory with the same name as the main page of your How-To, minus the beginning phrase "howto-" and the ending phrase ".xml". Add "-<step number>" within filenames for pages which represent additional How-To steps. See the xmlform-wizard How-To directory structure for more information.
  
  
  
  
  1.1                  xml-site/targets/cocoon/howto/howto-author-core-docs.html
  
  Index: howto-author-core-docs.html
  ===================================================================
  <html xmlns:NetUtils="org.apache.cocoon.util.NetUtils">
  <head>
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <title>How to Author Core Documentation</title>
  <STYLE type="text/css">
  a.menu {
  	color: #FFFFFF;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:plain;
      text-decoration:none;
      padding-left: 14px
  }
  
  A.menu:hover {
  	color: #FFCC00
  }
  
  
  .menutitle {
  	color: #000000;
      text-align:left;               
      font-size:10px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 8px
  }
  .menuselected {
  	color: #FFCC00;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 14px
  }
  </STYLE>
  </head>
  <body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
  <table border="0" cellpadding="0" cellspacing="0" width="100%">
  <tr>
  <td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
  </tr>
  <tr>
  <td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">How to Author Core Documentation</font></td>
  </tr>
  <tr>
  <td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
  <table width="288" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr width="100%">
  <td align="left" valign="top" width="120">
  <table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
  <tr>
  <td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">Main</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">How-Tos</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="index.html">Index</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Using Cocoon</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="xmlform-wizard/howto-xmlform-wizard.html">XMLForm</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-paginator-transformer.html">Paginator</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-html-pdf-publishing.html">HTML-PDF</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Documentation</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-author-howto.html">Author How-To</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-author-faq.html">Author FAQ</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-author-snippet.html">Author Snippet</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">Author Docs</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Contribution</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-patch.html">Prepare patch</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-bugzilla.html">Bugzilla</a></td>
  </tr>
  <tr>
  <td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  </table>
  </td><td>
  <table cellspacing="15" cellpadding="0" border="0">
  <tr>
  <td>
   
  
   
  
    <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Overview</font>
  <hr style="color: #0086b2" size="1">
  
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  This How-To describes the steps necessary to author or revise core documentation for Cocoon. Documentation is considered "core" if it is included in any Cocoon guide. Currently there are three guides: CTWIG, user, and developer. Please note that this guide structure may be revised soon. As you probably have discovered by now, many gaps exist in current Cocoon documentation. Authoring new core documents is a valuable way contribute to the Cocoon community.
  </font>
  </p>
  
  
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Purpose</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Writing about Cocoon is not a trivial exercise. Understanding the Cocoon CVS and document organization takes time. In other words, many potential obstacles stand in your way. These guidelines were written to help you make the most productive use of your "volunteer" time. Following them not only saves your time but also saves the time of committers who will apply your work to the CVS.
  </font>
  </p>
  
  
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Intended Audience</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Cocoon users who would like to improve Cocoon's documentation. This includes authors, editors, proofreaders, and quality assurance testers.
  </font>
  </p>
  
  
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Prerequisites</font>
  <hr style="color: #0086b2" size="1">
  
  <blockquote>
  <ul>
  
  <li>
  <font face="verdana, helvetica, sans serif">Spend some time familiarizing yourself with status of existing Cocoon documents.</font>
  </li>
  
  <li>
  <font face="verdana, helvetica, sans serif">When evaluating doc-related issues, make sure you are referring to the most recent document versions from the CVS or Cocoon web site. Please note that sometimes the most recent version of any document will be found only in CVS HEAD.</font>
  </li>
  
  </ul>
  </blockquote>
  
  
  
  	
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Steps</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Here's how to proceed.
  </font>
  </p>
  
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>1. Join the cocoon-docs email list</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Find out what documentation efforts are already in process among other users and committers. Join the Cocoon <a href="mailto:cocoon-docs-subscribe@xml.apache.org">Docs List</a>.
  </font>
  </p>
  	
  
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>2. Find a job</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Look through Cocoon's documentation set in order to find content holes to fill or existing documents to improve. You don't have to be an author to contribute: editors, proofreaders, and quality assurance testers provide vital work as well.
  </font>
  </p> 
  	
  
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>3. Announce your effort</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Let others know about your efforts. Announce your plans on the cocoon-docs list. This will help to prevent any duplication of effort. It will also attract the interest of and valuable feedback from other users who have similar interests or expertise in your document's subject area.</font>
  </p>
  	
  
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>4. Do the work</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Perhaps the easiest way to start a new document is to use an existing document as a template. If you are revising an existing document, make sure you are using the most recent copy of the document from CVS HEAD. If you aren't working with a local CVS repository, you can access all CVS files through <a href="http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/">ViewCVS</a>.
  </font>
  </p>
  	
  	
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>5. Ask for help when you need it</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Writing effectively about a "glue" framework like Cocoon, which integrates many diverse technologies, is difficult, no doubt about it. Navigating your way through the CVS, Bugzilla, the patch process, as well as all of the steps of document creation can be overwhelming at first. Many of us have "been there" already and are available to help you. Don't hesitate to ask for assistance on cocoon-docs when you are confronted with a conceptual or technical problem you can't solve on your own. Don't waste your precious "volunteer" time pulling your hair out. Still, if you reach a point in your work where you are hopelessly stuck, you can always leave concise comments in a &lt;fixme&gt; element for others to fill down the road. This is in tune with open source, community-based development. Contribute what you can, when you have an irresistible "itch" to "scratch". Others will pick up where you left off.
  </font>
  </p>
  	
  	
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>6. Get some feedback</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  If you are working on a new or revised document, please post a text version of it to the cocoon-docs list to receive valuable comments from developers and users. Again, if you have technical holes in your content, be sure to add fixme comments to make it clear for others what particular areas you'd like for them to address.
  </font>
  </p> 
  	
  	
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>7. Review your work</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Look over your work for embarrassing spelling or grammatical errors. At least check your document with a spell checker before submitting it. 
  </font>
  </p> 
  	
  
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>8. Validate your document(s)</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Use the appropriate and most recent dtd to validate any new or revised documents. You will find all dtds in the src/documentation/xdocs/dtd directory. While a "docs" target (during Cocoon's build process) is capable of validating your files, it is far more efficient to troubleshoot validation and well-formedness problems with your own tools.
  </font>
  </p> 
  	
  	
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>9. Update any related pages</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  If your work impacts the content of other files, for example the menu file (known as book.xml), consider updating these documents as well. You can validate and check link targets within all your documents by performing a docs build. If you have a working copy of the cvs HEAD, run the appropriate build script inside the xml-cocoon2 directory, specifying docs as the build target. Here's an example: 
  </font>
  </p> 
  
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  ./build.[sh|bat] docs
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  	
  	
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>10. Prepare any related patches</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Any new document file is already a patch, at least as far as Bugzilla is concerned. However, if you also edited any existing documents, you will need to create a patch for them before submitting all files. If you don't know how to create a patch, follow the instructions in <a href="howto-patch.html">How to Prepare a Patch.</a>
  </font>
  </p> 
  	
  
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>11. Submit via Bugzilla</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Create an attachment for any documents, and submit it via Bugzilla. If you don't know how to submit via Bugzilla, follow the instructions in <a href="howto-bugzilla.html">How to Contribute a Patch via Bugzilla.</a>
  </font>
  </p> 
  	
  
  	
  
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Summary</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  The Cocoon documentation effort is based on the belief that open source documents can be as first-rate as the software on which they are based. However, such an endeavor is dependent upon vital forms of contributions from developers and users alike. This How-To gives you the information you need to join like-minded individuals in the effort to improve Cocoon docs. Take a minute to imagine how advanced the Cocoon community would become if more Cocoon users played a role in improving Cocoon docs. Think how much more we would learn. Think how many more innovative Cocoon-based solutions we could develop, based on our extended knowledge. Think about it.
  </font>
  </p>
  	
  
  	
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Comments</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Care to comment on this How-To? Got another tip? Help keep this How-To relevant by passing along any useful feedback to the author, <a href="mailto:shannon@apache.org">Diana Shannon</a>. Even better, join the Cocoon <a href="mailto:cocoon-docs-subscribe@xml.apache.org">Docs List</a> and share your feedback and ideas with other people who are committed to producing high quality Cocoon documentation!
  </font>
  </p>
  	
  	
  
  
  
  
  
  </td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td bgcolor="#0086b2"><img width="1" src="images/dot.gif" height="1"></td>
  </tr>
  <tr>
  <td align="center"><font size="-1" face="arial,helvetica,sanserif" color="#0086b2"><i>Copyright &copy; 1999-2002 The Apache Software Foundation. All Rights Reserved.</i></font></td>
  </tr>
  </table>
  </body>
  </html>
  
  
  
  1.1                  xml-site/targets/cocoon/howto/howto-html-pdf-publishing.html
  
  Index: howto-html-pdf-publishing.html
  ===================================================================
  <html xmlns:NetUtils="org.apache.cocoon.util.NetUtils">
  <head>
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <title>How to Publish XML Documents in HTML and PDF</title>
  <STYLE type="text/css">
  a.menu {
  	color: #FFFFFF;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:plain;
      text-decoration:none;
      padding-left: 14px
  }
  
  A.menu:hover {
  	color: #FFCC00
  }
  
  
  .menutitle {
  	color: #000000;
      text-align:left;               
      font-size:10px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 8px
  }
  .menuselected {
  	color: #FFCC00;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 14px
  }
  </STYLE>
  </head>
  <body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
  <table border="0" cellpadding="0" cellspacing="0" width="100%">
  <tr>
  <td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
  </tr>
  <tr>
  <td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">How to Publish XML Documents in HTML and PDF</font></td>
  </tr>
  <tr>
  <td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
  <table width="288" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr width="100%">
  <td align="left" valign="top" width="120">
  <table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
  <tr>
  <td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">Main</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">How-Tos</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="index.html">Index</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Using Cocoon</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="xmlform-wizard/howto-xmlform-wizard.html">XMLForm</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-paginator-transformer.html">Paginator</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">HTML-PDF</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Documentation</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-author-howto.html">Author How-To</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-author-faq.html">Author FAQ</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-author-snippet.html">Author Snippet</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-author-core-docs.html">Author Docs</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Contribution</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-patch.html">Prepare patch</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-bugzilla.html">Bugzilla</a></td>
  </tr>
  <tr>
  <td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  </table>
  </td><td>
  <table cellspacing="15" cellpadding="0" border="0">
  <tr>
  <td>
   
  
   
  
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Overview</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  This How-To shows you how to publish XML documents in HTML and PDF using Cocoon. It requires no 
  prior knowledge of Cocoon, XSLT or XSL-FO.
  </font>
  </p>
  
  
  
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Purpose</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  You will learn how to build a simple pipeline that converts XML documents on-the-fly to HTML or PDF using simple 
  XSLT transforms. This is similar to the <code><font face="courier, monospaced">hello.html</font></code> and <code><font face="courier, monospaced">hello.pdf</font></code> samples of the standard Cocoon installation. However, this How-To teaches you how to build these mechanisms yourself. Thus, you will get a better feel of how Cocoon publishing really works. 
  </font>
  </p>
  
  
  
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Intended Audience</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Beginning Cocoon users who want to learn how to publish HTML and/or PDF documents from XML data.
  </font>
  </p>
  
  
  
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Prerequisites</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Here's what you need:</font>
  </p>  
  
  
  <blockquote>
  <ul>
  
  <li>
  <font face="verdana, helvetica, sans serif">Cocoon must be running on your system. The steps below have been tested with Cocoon 2.0.2-dev, but they should work with any 2.x version.</font>
  </li>
  
  <li>
  <font face="verdana, helvetica, sans serif">This document assumes a standard installation where
  <code><font face="courier, monospaced">http://localhost:8080/cocoon/mount/</font></code> points to 
  the <code><font face="courier, monospaced">mount</font></code> subdirectory of the Cocoon installation. Calling this URL should display a page
  titled "Directory Listing of mount".
  <br> 
  If your installation runs on a different URL, you will have to adjust
  the URLs provided throughout this How-To as necessary. 
  </font>
  </li>
  
  <li>
  <font face="verdana, helvetica, sans serif">You must be able to create and edit XML files in the <code><font face="courier, monospaced">mount</font></code> subdirectory of the Cocoon installation.
  In a standard installation, this is <code><font face="courier, monospaced">webapps/cocoon/mount</font></code> under the directory of the Tomcat installation. 
  </font>
  </li>
  
  </ul>
  </blockquote>
  
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>You will not need a fancy XML editor for this How-To. Copying and pasting the sample code snippets into any text editor
  will do.</i></font></td>
  </tr>
  </table>
  </p>
  
  
  
  
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Steps</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Here's how to proceed.
  </font>
  </p>
  
  
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>1. Create the work directory under mount</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Under <code><font face="courier, monospaced">webapps/cocoon/mount</font></code>, create a new directory and name it <code><font face="courier, monospaced">html-pdf</font></code>. 
  All files used by this How-To will reside in this directory.
  </font>
  </p>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  After a browser refresh, <code><font face="courier, monospaced">http://localhost:8080/cocoon/mount/</font></code> should display the name of this new directory, among others. 
  </font>
  </p>
  
  
  
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>2. Create the XML example documents</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  To keep it simple we will use two small XML files as our data sources.
  Later, you will probably use additional data sources like live XML feeds, databases, and others.</font>
  </p>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  In the <code><font face="courier, monospaced">html-pdf</font></code> directory, create the following two files, and name them exactly as
  shown.
  </font>
  </p>
  
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Contents of file <b>pageOne.xml</b>:
  </font>
  </p>
         
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
  &lt;page&gt;
  &lt;title&gt;This is the pageOne.xml example&lt;/title&gt;
  &lt;s1 title="Section one"&gt;
      &lt;p&gt;This is the text of section one&lt;/p&gt;
  &lt;/s1&gt;
  &lt;/page&gt;
          </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Contents of file <b>pageTwo.xml</b>:
  </font>
  </p>
         
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
  &lt;page&gt;
  &lt;title&gt;This is the pageTwo.xml example&lt;/title&gt;
  &lt;s1 title="Yes, it works"&gt;
      &lt;p&gt;Now you're hopefully seeing pageTwo in HTML or PDF&lt;/p&gt;
  &lt;/s1&gt;
  &lt;/page&gt;
          </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
  Be careful about the use of lower/uppercase in filenames if you're working on a Unix or Linux system. 
  On such systems, <code><font face="courier, monospaced">thisFile.xml</font></code> is not the same as <code><font face="courier, monospaced">Thisfile.xml</font></code>.
  </i></font></td>
  </tr>
  </table>
  </p>
  
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
  To avoid any errors, use copy/paste when creating XML documents from examples on this page.
  </i></font></td>
  </tr>
  </table>
  </p>
  
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
  Do not leave spaces at the start of XML files. The &lt;?xml... processing instruction must
  be the first character in the file.
  </i></font></td>
  </tr>
  </table>
  </p>
  
  
  
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>3. Create the XSLT transform for HTML</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  The most common way of producing HTML in Cocoon is to use <b>XSLT transforms</b> to select and convert 
  the appropriate elements of the input documents.
  </font>
  </p>
  
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Copy the file shown below to the <code><font face="courier, monospaced">html-pdf</font></code> directory alongside your XML documents, naming it
  <b>doc2html.xsl</b>
  </font>
  </p>
  
         
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
  &lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"&gt;
  
  &lt;!-- generate HTML skeleton on root element --&gt;
  &lt;xsl:template match="/"&gt;
    &lt;html&gt;
      &lt;head&gt;
        &lt;title&gt;&lt;xsl:apply-templates select="page/title"/&gt;&lt;/title&gt;
      &lt;/head&gt;
      &lt;body&gt;
          &lt;xsl:apply-templates/&gt;
      &lt;/body&gt;
    &lt;/html&gt;
  &lt;/xsl:template&gt;
  
  &lt;!-- story is used later by the Meerkat example --&gt;
  &lt;xsl:template match="p|story"&gt;
      &lt;p&gt;&lt;xsl:apply-templates/&gt;&lt;/p&gt;
  &lt;/xsl:template&gt;
  
  &lt;!-- convert sections to HTML headings --&gt;
  &lt;xsl:template match="s1"&gt;
      &lt;h1&gt;&lt;xsl:apply-templates select="@title"/&gt;&lt;/h1&gt;
      &lt;xsl:apply-templates/&gt;
  &lt;/xsl:template&gt;
  
  &lt;/xsl:stylesheet&gt;     
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>       
  Basically what this does is generate an HTML skeleton and convert the input markup to HTML. We won't go
  into details here. Rather, our goal is to show you how the components of the publishing chain are combined.  
  </i></font></td>
  </tr>
  </table>
  </p>
  
  
  
  
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>4. Create the sitemap</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  We now have documents to publish and an XSLT transform to convert them to our HTML output format.
  What's left is to connect them in a <b>processing pipeline</b>. Then, the <b>sitemap</b> can select the pipeline based on the details of the browser request.
  </font>
  </p>
  
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  To tell Cocoon how to process requests made to <code><font face="courier, monospaced">html-pdf</font></code>, 
  copy the following snippet to a file named <b>sitemap.xmap</b> in the 
  <code><font face="courier, monospaced">html-pdf</font></code> subdirectory.
  </font>
  </p>
  
         
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
  &lt;map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"&gt;
  
      &lt;!-- use the standard components --&gt;
      &lt;map:components&gt;
          &lt;map:generators default="file"/&gt;
          &lt;map:transformers default="xslt"/&gt;
          &lt;map:readers default="resource"/&gt;
          &lt;map:serializers default="html"/&gt;
          &lt;map:selectors default="browser"/&gt;
          &lt;map:matchers default="wildcard"/&gt;
          &lt;map:transformers default="xslt"/&gt;
      &lt;/map:components&gt;
        
      &lt;map:pipelines&gt;
          &lt;map:pipeline&gt;
              &lt;!-- respond to *.html requests with 
                   our docs processed by doc2html.xsl --&gt;
              &lt;map:match pattern="*.html"&gt;
                  &lt;map:generate src="{1}.xml"/&gt;
                  &lt;map:transform src="doc2html.xsl"/&gt;
                  &lt;map:serialize type="html"/&gt;
              &lt;/map:match&gt;
              
              &lt;!-- later, respond to *.pdf requests with 
                   our docs processed by doc2pdf.xsl --&gt;
              &lt;map:match pattern="*.pdf"&gt;
                  &lt;map:generate src="{1}.xml"/&gt;
                  &lt;map:transform src="doc2pdf.xsl"/&gt;
                  &lt;map:serialize type="fo2pdf"/&gt;
              &lt;/map:match&gt;
          &lt;/map:pipeline&gt;
      &lt;/map:pipelines&gt;
  &lt;/map:sitemap&gt;
          </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>The important thing here is the first <b>map:match</b> element, which tells Cocoon how to process
  requests ending in *.html in this directory. Again, we won't go into details here, but that's where it happens.
  </i></font></td>
  </tr>
  </table>
  </p>
  
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>The above sitemap is already configured for PDF publishing. However, this capability is not fully functional at this time because we haven't created the required XSLT transform yet.</i></font></td>
  </tr>
  </table>
  </p> 
         
  
  
  
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>5. Test the HTML publishing</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  At this point you should be able to display the results in HTML: 
  </font>
  </p>
  
  <blockquote>
  <ul>
  
  <li>
  <font face="verdana, helvetica, sans serif">
  <code><font face="courier, monospaced">http://localhost:8080/cocoon/mount/html-pdf/pageOne.html</font></code>
  should display the first page with "Section one" in big letters.
  </font>
  </li>
  
  <li>
  <font face="verdana, helvetica, sans serif">
  <code><font face="courier, monospaced">http://localhost:8080/cocoon/mount/html-pdf/pageTwo.html</font></code>
  should display the second page with "Yes it works" in big letters.
  </font>
  </li>
  
  </ul>
  </blockquote>
  
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>If this doesn't work, you might want to double check the above steps first, and then look at the Cocoon
  logs in the webapps/cocoon/WEB-INF/logs directory. You will find lots of information there. Look for clues 
  in files that change in size when the error happens.
  </i></font></td>
  </tr>
  </table>
  </p>
  
  
  
  
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>6. Create the XSLT transform for PDF</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  PDF documents are created via XSL-FO documents which are XML documents that use a specific page-description
  vocabulary. (See <a href="#references">References</a> below for more info). The actual conversion to PDF is done by the 
  <code><font face="courier, monospaced">PdfSerializer</font></code> which uses software from <a href="http://xml.apache.org/fop">FOP</a>, another Apache
  Software Foundation project.   
  </font>
  </p>
  
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  To activate the PDF conversion, copy the code snippet shown below to the <code><font face="courier, monospaced">html-pdf</font></code> directory along with your XML documents, and name it
  <b>doc2pdf.xsl</b>
  </font>
  </p>
  
         
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
  &lt;xsl:stylesheet 
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
      xmlns:fo="http://www.w3.org/1999/XSL/Format"
  &gt;
      &lt;!-- generate PDF page structure --&gt;
      &lt;xsl:template match="/"&gt;
          &lt;fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"&gt;
              &lt;fo:layout-master-set&gt;
                  &lt;fo:simple-page-master master-name="page"
                    page-height="29.7cm" 
                    page-width="21cm"
                    margin-top="1cm" 
                    margin-bottom="2cm" 
                    margin-left="2.5cm" 
                    margin-right="2.5cm"
                  &gt;
                      &lt;fo:region-before extent="3cm"/&gt;
                      &lt;fo:region-body margin-top="3cm"/&gt;
                      &lt;fo:region-after extent="1.5cm"/&gt;
                  &lt;/fo:simple-page-master&gt;
  
                  &lt;fo:page-sequence-master master-name="all"&gt;
                      &lt;fo:repeatable-page-master-alternatives&gt;
                          &lt;fo:conditional-page-master-reference 
                             master-reference="page" page-position="first"/&gt;
                      &lt;/fo:repeatable-page-master-alternatives&gt;
                  &lt;/fo:page-sequence-master&gt;
              &lt;/fo:layout-master-set&gt;
  
              &lt;fo:page-sequence master-reference="all"&gt;
                  &lt;fo:flow flow-name="xsl-region-body"&gt;
                      &lt;fo:block&gt;&lt;xsl:apply-templates/&gt;&lt;/fo:block&gt;
                  &lt;/fo:flow&gt;
              &lt;/fo:page-sequence&gt;
          &lt;/fo:root&gt;
      &lt;/xsl:template&gt;
  
      &lt;!-- process paragraphs --&gt;
      &lt;xsl:template match="p"&gt;
          &lt;fo:block&gt;&lt;xsl:apply-templates/&gt;&lt;/fo:block&gt;
      &lt;/xsl:template&gt;
  
      &lt;!-- convert sections to XSL-FO headings --&gt;
      &lt;xsl:template match="s1"&gt;
          &lt;fo:block font-size="24pt" color="red" font-weight="bold"&gt;
              &lt;xsl:apply-templates select="@title"/&gt;
          &lt;/fo:block&gt;
          &lt;xsl:apply-templates/&gt;
      &lt;/xsl:template&gt;
  
  &lt;/xsl:stylesheet&gt;
  
         </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>This file is already referenced by the sitemap we created, so no additional configuration is needed.</i></font></td>
  </tr>
  </table>
  </p>       
  
  
  
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>5. Test the PDF publishing</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  At this point you should be able to display the results in PDF in addition to the existing HTML versions: 
  </font>
  </p>
  
  <blockquote>
  <ul>
  
  <li>
  <font face="verdana, helvetica, sans serif">
  <code><font face="courier, monospaced">http://localhost:8080/cocoon/mount/html-pdf/pageOne.pdf</font></code>
  should display the first page with "Section one" in big red letters.
  </font>
  </li>
  
  <li>
  <font face="verdana, helvetica, sans serif">
  <code><font face="courier, monospaced">http://localhost:8080/cocoon/mount/html-pdf/pageTwo.pdf</font></code>
  should display the second page with "Yes it works" in big red letters.
  </font>
  </li>
  
  </ul>
  </blockquote>
  
  
  
  
  
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Summary</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  I hope you're beginning to see that publishing PDF and HTML documents in Cocoon is not too complicated, once you know what goes where. 
  </font>
  </p>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  The nice thing is that all of our huge corpus
  of XML documents (actually, only two documents right now, but that's a start... ) is processed by just two XSLT files, one
  for each target format.
  </font>
  </p>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  If you need to change the appearance of the published documents, you have to change only these two XSLT transforms. There's no need to touch the source documents.
  </font>
  </p>
  
  
  
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Tips</font>
  <hr style="color: #0086b2" size="1">
  
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Tip 1: Dynamic XML data</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Using dynamic XML as the data source is very easy because the Cocoon FileGenerator can read URLs as well. 
  </font>
  </p>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  If you add the map:match element shown in bold below <b>before</b> the existing map:match elements in your sitemap.xmap file, requesting
  <code><font face="courier, monospaced">http://localhost:8080/cocoon/mount/html-pdf/meerkat.html</font></code>
  should display real-time news from Meerkat (assuming an Internet connection to Meerkat is available).
  </font>
  </p>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  The news will be displayed in a very rough format. However, this can be improved by writing a 
  specific XSLT transform for this Meerkat data and using it, instead of doc2html.xsl, in the meerkat.html pipeline.  
  </font>
  </p>
  
  
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  
  ...
  &lt;map:pipeline&gt;
  
  <b>
  
  &lt;map:match pattern="meerkat.html"&gt;
      &lt;map:generate src="http://www.oreillynet.com/meerkat/?_fl=xml"/&gt;
      &lt;map:transform src="doc2html.xsl"/&gt;
      &lt;map:serialize type="html"/&gt;
  &lt;/map:match&gt;
  
  </b>
  
  &lt;map:match pattern="*.html"&gt;
  etc...
  
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
  
  
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Tip 2: Two-step conversion</b></font>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  When you are generating multiple formats from a single data source, it is often a good idea to generate 
  an intermediate <b>logical document</b> that describes the output in a format-neutral way.
  </font>
  </p>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  This is obviously not needed in our simple example. If you're aiming for more complicated 
  publishing tasks, then you might want to read about this "publishing pattern" in Martin Fowler's 
  <a href="http://www.martinfowler.com/isa/htmlRenderer.html">Two Step View</a>
  article.
  </font>
  </p>
  
  
  
  
  
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">References</font>
  <hr style="color: #0086b2" size="1">
  
  <a name="references">
  <!--anchor--></a>
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  To go further, you will need to learn about the following technologies and tools.
  </font>
  </p>
  
  <blockquote>
  <ul>
  
  <li>
  <font face="verdana, helvetica, sans serif">
  Learning  
  <a href="http://www.google.com/search?as_sitesearch=xml.apache.org&as_q=cocoon+concepts+sitemap">
  Cocoon concepts</a> will help you understand how the sitemap, generators, transformers, and serializers work.
  </font>
  </li> 
  
  <li>
  <font face="verdana, helvetica, sans serif">
  Learning about <a href="http://www.w3.org/Style/XSL/">XSLT</a> will enable you to write your own transforms to 
  generate HTML, PDF or other formats from XML data. 
  Information about XSL-FO is available at the same address.  
  </font>
  </li>
  
  </ul>
  </blockquote>
  
  
  
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Comments</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Care to comment on this How-To? Got another tip? 
  Help keep this How-To relevant by passing along any useful feedback to the author,
  <a href="mailto:bdelacretaz@codeconsult.ch">Bertrand&nbsp;Delacr&egrave;taz</a>.
  </font>
  </p>
  
  
  
  
  </td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td bgcolor="#0086b2"><img width="1" src="images/dot.gif" height="1"></td>
  </tr>
  <tr>
  <td align="center"><font size="-1" face="arial,helvetica,sanserif" color="#0086b2"><i>Copyright &copy; 1999-2002 The Apache Software Foundation. All Rights Reserved.</i></font></td>
  </tr>
  </table>
  </body>
  </html>
  
  
  
  1.1                  xml-site/targets/cocoon/howto/howto-paginator-transformer.html
  
  Index: howto-paginator-transformer.html
  ===================================================================
  <html xmlns:NetUtils="org.apache.cocoon.util.NetUtils">
  <head>
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <title>How to use the Paginator Transformer</title>
  <STYLE type="text/css">
  a.menu {
  	color: #FFFFFF;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:plain;
      text-decoration:none;
      padding-left: 14px
  }
  
  A.menu:hover {
  	color: #FFCC00
  }
  
  
  .menutitle {
  	color: #000000;
      text-align:left;               
      font-size:10px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 8px
  }
  .menuselected {
  	color: #FFCC00;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 14px
  }
  </STYLE>
  </head>
  <body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
  <table border="0" cellpadding="0" cellspacing="0" width="100%">
  <tr>
  <td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
  </tr>
  <tr>
  <td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">How to use the Paginator Transformer</font></td>
  </tr>
  <tr>
  <td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
  <table width="288" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr width="100%">
  <td align="left" valign="top" width="120">
  <table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
  <tr>
  <td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">Main</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">How-Tos</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="index.html">Index</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Using Cocoon</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="xmlform-wizard/howto-xmlform-wizard.html">XMLForm</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">Paginator</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-html-pdf-publishing.html">HTML-PDF</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Documentation</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-author-howto.html">Author How-To</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-author-faq.html">Author FAQ</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-author-snippet.html">Author Snippet</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-author-core-docs.html">Author Docs</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Contribution</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-patch.html">Prepare patch</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="howto-bugzilla.html">Bugzilla</a></td>
  </tr>
  <tr>
  <td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  </table>
  </td><td>
  <table cellspacing="15" cellpadding="0" border="0">
  <tr>
  <td>
  	
  
  	<font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Overview</font>
  <hr style="color: #0086b2" size="1">
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  This How-To describes the how to use Cocoon's Paginator Transformer component. You can consider it a 'FilterTransformer' on pagination steroids. The Paginator Transformer filters specific data and counts pages as it transforms SAX events. It implements pagination rules based on easy-to-configure pagesheet documents.
    </font>
  </p>
  	
  	
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Purpose</font>
  <hr style="color: #0086b2" size="1">
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  XSLT-based approaches to pagination are problematic. First of all, it's somewhat complex to define the necessary declarative logic in XSLT. Additionally, an XSLT solution is rarely reusable across different pagination use cases. These problems spurred the creation of the Paginator Transformer. You can quickly add pagination capabilities to your webapp once you have configured a simple few rules within a single configuration file, the pagesheet.
    </font>
  </p>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  The Paginator Transformer works quite nicely for use cases involving a few tens of pages and, of course, for static generation of any number of pages. However, the Transformer must process an entire file before it can extract even a single page. Therefore, you are <b>strongly</b> advised against using it for books or other large documents on dynamic sites. Nevertheless, its output is cacheable. Thus, if the same page is requested, then the document will be reprocessed by the Transformer only when it has changed.
    </font>
  </p>
  	
  	
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Intended Audience</font>
  <hr style="color: #0086b2" size="1">
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Cocoon users who need pagination capabilities for their web documents. This includes frustrated users who are tired of implementing complex, XSLT-based approaches to pagination.
    </font>
  </p>
  	
  	
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Prerequisites</font>
  <hr style="color: #0086b2" size="1">
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Make sure you have the version 2.0.3 or greater of Cocoon. The PaginatorTransformer component source is located in the scratchpad area. Therefore, you need to use the following command to build a deployable cocoon.war which includes the scratchpad libraries.
    </font>
  </p>
  		
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  ./build.sh -Dinclude.webapp.libs=yes -Dinclude.scratchpad.libs=yes webapp 
  		</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  During the build process, the necessary configuration details for the PaginatorTransformer component are automatically copied to cocoon.xconf of cocoon.war. This means that you don't need to manually configure cocoon.xconf. However, if you are adding the paginator samples to Cocoon webapp that was <b>not</b> generated by the above build command, add the following snippet to your cocoon.xconf file, located in the WEB-INF directory of your deployed webapp.
    </font>
  </p>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Version 2.0.3:
    </font>
  </p>
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
    &lt;component 
       class="org.apache.cocoon.transformation.pagination.Paginator"
       role="org.apache.cocoon.transformation.pagination.Paginator"
     /&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Version 2.1:
    </font>
  </p>
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
    &lt;paginator 
       class="org.apache.cocoon.transformation.pagination.Paginator" 
       role="org.apache.cocoon.transformation.pagination.Paginator"
       logger="core.paginator"/&gt;
     /&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Sample files, not directly related to this How-To, are also copied during the build process to Cocoon webapp at webapp/samples/paginator. You can access them in your web browser using the following URI: 
   </font>
  </p>
    
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  http://localhost:8080/cocoon/samples/paginator/
    </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  	
  	
  	
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Steps</font>
  <hr style="color: #0086b2" size="1">
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Let's start with a simple example.
    </font>
  </p>
  		
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Simple Example</b></font>
  	  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Suppose you have an XML file, document.xml, as follows. 
  	  </font>
  </p>
  	  
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;images&gt;
      &lt;image /&gt;
      &lt;image /&gt;
      &lt;image /&gt;
      &lt;image /&gt;
      &lt;image /&gt;
      &lt;image /&gt;
      &lt;image /&gt;
  &lt;/images&gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  First, you need to write a <b>pagesheet.</b> Just as a stylesheet contains instructions for an xslt processor, a pagesheet contains instructions for the paginator filter. Here is the pagesheet dtd.
    </font>
  </p>
    
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;!ELEMENT pagesheet (items?, rules)*&gt;
  &lt;!ATTLIST pagesheet xmlns CDATA #IMPLIED&gt;
  
  &lt;!ELEMENT items (group)&gt;
  
  &lt;!ELEMENT group EMPTY &gt;
  &lt;!ATTLIST group 
     name CDATA #IMPLIED 
     element CDATA #IMPLIED &gt;
  
  &lt;!ELEMENT rules (link?, count?)*&gt;
  
  &lt;!ELEMENT link EMPTY &gt;
  &lt;!ATTLIST link 
     type ( unit | range ) #REQUIRED 
     num CDATA #REQUIRED 
   &gt;
   
   &lt;!ELEMENT count EMPTY &gt;
   &lt;!ATTLIST count 
     type ( element | char ) #REQUIRED 
     num CDATA #REQUIRED 
     name CDATA #IMPLIED 
     namespace CDATA #IMPLIED 
   &gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Let's say you want to paginate document.xml content based on a rule of three &lt;image&gt; elements per page. Here's a sample pagesheet, images.xml, which does just that.
    </font>
  </p>
  				
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;pagesheet xmlns="http://apache.org/cocoon/paginate/1.0"&gt;
  	&lt;rules&gt;
  		&lt;count type="element" name="image" num="3" /&gt;
  	&lt;/rules&gt;
  &lt;/pagesheet&gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
  	  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  You process a source file through a pagesheet filter in a sitemap snippet like this:
  	  </font>
  </p>
  	  
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;map:match pattern="page(*)"&gt;
    &lt;map:generate src="document.xml"/&gt;
    &lt;map:transform src="pagesheets/images.xml" type="paginator"&gt;
  	&lt;map:parameter name="page" value="{1}"/&gt;
    &lt;/map:transform&gt;
    &lt;map:serialize type="xml"/&gt;
  &lt;/map:match&gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
      
  	  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Accessing the URI for page one, page(1) yields:
  	  </font>
  </p>
  	  
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0" encoding="UTF-8" ?&gt; 
  &lt;images xmlns:page="http://apache.org/cocoon/paginate/1.0"&gt;
    &lt;image /&gt; 
    &lt;image /&gt; 
    &lt;image /&gt; 
    &lt;page:page 
       current="1" 
       total="3" 
       current-uri="/cocoon/samples/paginator/page(1)" 
       clean-uri="/cocoon/samples/paginator/page" /&gt; 
  &lt;/images&gt;
  
  
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
  	  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Clearly the above XML could have been transformed into something more meaningful. Note that the transformer must process all pages to obtain the value of <code><font face="courier, monospaced">total</font></code>. Currently, there is no way to avoid this.
  	  </font>
  </p>
  			
  			
  			
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Adding Navigation</b></font>
  		  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Given the Paginator's a full-blown pagesheet language, there's even more we can accomplish, most importantly, navigation.
  		  </font>
  </p>
  		  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  As an example, consider the following pagesheet, images2.xml.
  		  </font>
  </p>
  		  
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;pagesheet xmlns="http://apache.org/cocoon/paginate/1.0"&gt;
  &lt;items&gt;
    &lt;group name="item" element="images" /&gt;
   &lt;/items&gt; 
   &lt;rules&gt;
      &lt;rules&gt;
        &lt;count type="element" name="image" num="3"/&gt;
        &lt;link type="unit" num="1"/&gt;
      &lt;/rules&gt;
   &lt;/rules&gt;
  &lt;/pagesheet&gt;
  
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
      
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  The pagesheet rules demonstrate that the transformer understands how the page was encoded in the given URI request, i.e., that parentheses surround the value of page. They also reveal that the transformer can provide navigation links to available pages, in this case, plus or minus one position.
    </font>
  </p>
  	
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  In your sitemap.xmap file, if you change the pagesheet source to images2.xml as follows:
    </font>
  </p>
  		  
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;map:match pattern="page(*)"&gt;
  	&lt;map:generate src="document.xml" /&gt;
  	&lt;map:transform src="pagesheets/images2.xml" type="paginator"&gt;
  		&lt;map:parameter name="page" value="{1}" /&gt;
  	&lt;/map:transform&gt;
  	&lt;map:serialize type="xml" /&gt;
  &lt;/map:match&gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
      
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  processing the same page(1) request yields the following (pretty-printed for this document):
    </font>
  </p>
    
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;images xmlns:page="http://apache.org/cocoon/paginate/1.0"&gt;
    &lt;image /&gt; 
    &lt;image /&gt; 
    &lt;image /&gt; 
    &lt;page:page 
      current="1" 
      total="3" 
      current-uri="/cocoon/samples/paginator/page(1)" 
      clean-uri="/cocoon/samples/paginator/page"&gt;
    &lt;page:link 
       type="next" 
       uri="/cocoon/samples/paginator/page(2)" 
       page="2" /&gt; 
    &lt;/page:page&gt;
  &lt;/images&gt;
  
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  This result demonstrates:
    </font>
  </p>
  
  <blockquote>
  <ul>
  	
  <li>
  <font face="verdana, helvetica, sans serif">
  Page 0 does not exist, so no &lt;page:link&gt; is created for a previous page.
  	</font>
  </li>
  	
  <li>
  <font face="verdana, helvetica, sans serif">
  Page 2 exists, so &lt;page:link&gt; is created, along with 
  		<blockquote>
  <ul>
  		  
  <li>
  <font face="verdana, helvetica, sans serif">
  a value of "next" for its type attribute (useful for visualization), and
  		  </font>
  </li>
  		  
  <li>
  <font face="verdana, helvetica, sans serif">
  a value of page(2) for its URI attribute (useful for linking without XSLT-specific logic)
  		  </font>
  </li>
  		
  </ul>
  </blockquote>
  		
  </font>
  </li>
  		
  </ul>
  </blockquote>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Note that the URI is re-encoded using the same parentheses pattern, page(2).
    </font>
  </p>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Now, without changing anything, requesting page(2) yields the following (pretty-printed for this document):
    </font>
  </p>
    
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;images xmlns:page="http://apache.org/cocoon/paginate/1.0"&gt;
    &lt;image /&gt; 
    &lt;image /&gt; 
    &lt;image /&gt; 
    &lt;page:page 
        current="2" 
        total="3" 
        current-uri="/cocoon/samples/paginator/page(2)" 
        clean-uri="/cocoon/samples/paginator/page"&gt;
      &lt;page:link type="prev" uri="/cocoon/samples/paginator/page(1)" page="1" /&gt; 
      &lt;page:link type="next" uri="/cocoon/samples/paginator/page(3)" page="3" /&gt; 
    &lt;/page:page&gt;
  &lt;/images&gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
      
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  And requesting page(3) yields the following.
    </font>
  </p>
    
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;images xmlns:page="http://apache.org/cocoon/paginate/1.0"&gt;
    &lt;image /&gt; 
    &lt;page:page 
       current="3" 
       total="3" 
       current-uri="/cocoon/samples/paginator/page(3)" 
       clean-uri="/cocoon/samples/paginator/page"&gt;
    &lt;page:link 
       type="prev" 
       uri="/cocoon/samples/paginator/page(2)" 
       page="2" /&gt; 
    &lt;/page:page&gt;
  &lt;/images&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Note only one &lt;image&gt;. The original document, images.xml, only contained seven &lt;image&gt; elements: three for page one, three for page two, but only one for page three. Thus, the result here is the modulo (or remainder) of the division.
    </font>
  </p>
  	
  	
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Real-Life Examples</b></font>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Here are a few pagesheets examples which are a bit more complex.
    </font>
  </p>
  		
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">DirectoryGenerator Pagination</font>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Here's an example of paginating the contents of a directory using the DirectoryGenerator.
    </font>
  </p>
    
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;pagesheet xmlns="http://apache.org/cocoon/paginate/1.0"&gt;
  	&lt;rules&gt;
  		&lt;count type="element" name="file" 
  		  namespace="http://apache.org/cocoon/directory/2.0" 
  		  num="16" /&gt;
  		&lt;link type="unit" num="2" /&gt;
  		&lt;link type="range" value="5" /&gt;
  	&lt;/rules&gt;
  &lt;/pagesheet&gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  		
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  The rules state:
    </font>
  </p>
  	
  <blockquote>
  <ol>
  		
  <li>
  <font face="verdana, helvetica, sans serif">
  paginate 16 files per page
  		</font>
  </li>
  		
  <li>
  <font face="verdana, helvetica, sans serif">
  provide links to +/- 1 and +/- 2 pages (when available)
  		</font>
  </li>
  		
  <li>
  <font face="verdana, helvetica, sans serif">
  provide links to +/- 5 (when available)
  		</font>
  </li>
  	
  </ol>
  </blockquote>
  	  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  So, suppose we have a directory with 300 files. If we request page 10, the generated page will be:
  	  </font>
  </p>
  	  
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;dir:directory&gt;
  	&lt;dir:file ... /&gt;
  		[other 15 dir:file] 
  	&lt;page:page 
  	     xmlns:page="http://apache.org/cocoon/paginate/1.0" 
  	     current="10" 
  	     total="19" 
  	     current-uri="dir(10)" 
  	     clean-uri="dir" &gt;
  	  &lt;page:range-link page="5" type="prev" uri="page(5)" /&gt;
  	  &lt;page:link page="8" type="prev" uri="page(8)" /&gt;
  	  &lt;page:link page="9" type="prev" uri="page(9)" /&gt;
  	  &lt;page:link page="11" type="next" uri="page(11)" /&gt;
  	  &lt;page:link page="12" type="next" uri="page(12)" /&gt;
  	  &lt;page:range-link page="15" type="next" uri="page(15)" /&gt;
  	&lt;/page:page&gt;
  &lt;/dir:directory&gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
      
  			
  			
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Asymmetric pagination</font>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  We also have the ability to indicate different rules for each page, for example:
    </font>
  </p>
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;pagesheet xmlns="http://apache.org/cocoon/paginate/1.0"&gt;
  	&lt;rules page="1"&gt;
  		&lt;count type="element" name="b" num="5" /&gt;
  		&lt;link type="unit" num="1" /&gt;
  	&lt;/rules&gt;
  	&lt;rules&gt;
  		&lt;count type="element" name="b" num="10" /&gt;
  		&lt;link type="unit" num="2" /&gt;
  	&lt;/rules&gt;
  &lt;/pagesheet&gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
  	
  	
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Count types</font>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  The Paginator Transformer was designed to count. However, it's up to you to define what needs to be counted, either XML elements or characters (not yet implemented). By supplying values to the attributes of &lt;count&gt; in the pagesheet, you can specify exactly what needs to be counted.
    </font>
  </p>
    
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  The &lt;count&gt; element has two required and two optional attributes. The required attributes are:
    </font>
  </p>
    
  <blockquote>
  <ul>
       
  <li>
  <font face="verdana, helvetica, sans serif">
  <b>type</b> the method of counting the paginator should perform, either elements or characters. 
  When element is specified, the transformer counts startElement() SAX events. When chars is specified (currently not implemented), the transformer counts the primitive data type char.
       </font>
  </li>
       
  <li>
  <font face="verdana, helvetica, sans serif">
  <b>num</b> a number which how many times counted item (element or chars) must be present within the transformed page.
       </font>
  </li>
     
  </ul>
  </blockquote>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Optional attributes (when type="element" is specified) are:
    </font>
  </p>
    
  <blockquote>
  <ul>
        
  <li>
  <font face="verdana, helvetica, sans serif">
  <b>name</b> the name of the element, without any namespace prefix
        </font>
  </li>
        
  <li>
  <font face="verdana, helvetica, sans serif">
  <b>namespace</b> the URI of the namespace. If not specified, the default namespace is used.
        </font>
  </li>
     
  </ul>
  </blockquote>
  		
  	 
    
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Improving the Paginator Transformer</font>
  <hr style="color: #0086b2" size="1">
  
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  The PaginatorTransformer was developed, initially, to paginate a directory listing. It 
  works great when it paginates by counting elements, particularly elements which contain similar amounts of content to be displayed on pages. With documents, for example, it could paginate by counting sections or subsections. However, bear in mind that this approach does not always guarantee visually-balanced web pages.
    </font>
  </p>
    
  
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Nested Pagination</b></font>
  
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Furthermore, simply counting elements is not always simple. Consider the following:
    </font>
  </p>
    
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
   &lt;a&gt;
    &lt;b&gt;
     &lt;a&gt;
      &lt;b&gt;
       &lt;a&gt;
        &lt;b/&gt;
       &lt;/a&gt;
      &lt;/b&gt;
     &lt;/a&gt;
    &lt;/b&gt;
   &lt;/a&gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
      
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Let's say you want to paginate using one &lt;b&gt; per page. What should the transformed pages look like? Here's a few possible outcomes. Which one is the best? 
    </font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Page 1</font>
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
   &lt;a&gt;
    &lt;b&gt;
     &lt;a&gt;
      &lt;a/&gt;
     &lt;/a&gt;
    &lt;/b&gt;
   &lt;/a&gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
    
    
    
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Page 2</font>
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
   &lt;a&gt;
    &lt;a&gt;
     &lt;b&gt;
      &lt;a/&gt;
     &lt;/b&gt;
    &lt;/a&gt;
   &lt;/a&gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
    
    
    
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Page 3</font>
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;?xml version="1.0"?&gt;
   &lt;a&gt;
    &lt;a&gt;
     &lt;a&gt;
      &lt;b/&gt;
     &lt;/a&gt;
    &lt;/a&gt;
   &lt;/a&gt;
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
    
    
     
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  It appears the current code is buggy somewhere. With deep
  nesting as in this example, some SAX events are lost. This 
  creates a non-well-formed SAX stream which chokes subsequent
  transformers, such as XSLT, which may be sensitive to well-formedness.
    </font>
  </p>
    
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Does the above might look like a mental exercise to you? Perhaps, but consider 
  the structure of Cocoon Project's Document DTD 1.1. which includes nested &lt;section&gt; elements. Similar problems will emerge when paginating these documents based on this dtd. 
  It's isn't clear whether the solution adopted above is meaningful or not for a real-world  pagination. Suggestions on this are welcome.
    </font>
  </p>
    
    
    
  
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Character-based Pagination</b></font>
  
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Given the need to visually balance pages, a counting method for characters was added, even though it isn't implemented yet. Counting by characters is especially difficult when you think about the algorithms that perform chunking. 
    </font>
  </p>
    
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Assume you have a document like this:
    </font>
  </p>
    
      
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
   &lt;p&gt;this is some &lt;strong&gt;text&lt;/strong&gt; that happens 
   to be &lt;em&gt;chuncked&lt;/em&gt;&lt;/p&gt;
               ^
      </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
      
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Suppose that paginating by counting the chars results in a chunking point
  indicated by the caret above (between the letters u and n). 
  Ending a page at that position results in XML that is not well-formed as well as
  truncated words. Even if you find a way to provide well-formed XML, 
  you still must deal with word-break issues. Therefore, we need a way to 
  produce well-formed XML by continuing until the first 'block-level' element is encountered, for example, 
  &lt;p&gt; in this case. However, this means that the pagesheet must contain a list of
  such 'block-delimiting' elements. Currently, the Pagesheet parser and
  object model does <b>not</b> support this notion.
    </font>
  </p>
    
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Conclusion? Pagination at the char level is not trivial and will require a
  little bit of additional work on the transformer.
    </font>
  </p>
    
    
    
  
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Other Improvements</b></font>
  
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  One possible way to improve the concept is to count by XPath results. For example,
  you may want to count &lt;section&gt; elements included in other &lt;section&gt; elements. Another way to improve the design is to allow booleans to be used within counting
  rules. For example, you could count &lt;session&gt; AND &lt;chapter&gt; elements. Most likely, XPath will help here as well.
    </font>
  </p>
    
    
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Comments</font>
  <hr style="color: #0086b2" size="1">
  
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  Got an idea how to improve the Paginator Transformer? Post it to the <a href="mailto:cocoon-dev@xml.apache.org?subject=Paginator:">cocoon-dev</a> mailing list. Care to comment on this How-To? Help keep this document relevant by passing along any constructive feedback to the <a href="mailto:cocoon-docs@xml.apache.org?subject=Paginator:">cocoon-docs</a> mailing list.
    </font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Revisions</font>
  <hr style="color: #0086b2" size="1">
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  06-06-02: Content originally posted to cocoon-dev by Stefano Mazzocchi. 
    </font>
  </p>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  06-26-02: Edited and structured by Diana Shannon. Scratchpad samples also added.
    </font>
  </p>
    
  <p>
  <font color="black" face="verdana,helvetica,sanserif">
  06-27-02: Scratchpad samples revised by Stefano Mazzocchi.
    </font>
  </p>
    
    
  
  </td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td bgcolor="#0086b2"><img width="1" src="images/dot.gif" height="1"></td>
  </tr>
  <tr>
  <td align="center"><font size="-1" face="arial,helvetica,sanserif" color="#0086b2"><i>Copyright &copy; 1999-2002 The Apache Software Foundation. All Rights Reserved.</i></font></td>
  </tr>
  </table>
  </body>
  </html>
  
  
  
  1.1                  xml-site/targets/cocoon/howto/images/note.gif
  
  	<<Binary file>>
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: general-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: general-cvs-help@xml.apache.org


Mime
View raw message