shannon 2002/07/03 14:36:44
Modified: src/documentation/xdocs/howto howto-html-pdf-publishing.xml
Log:
My edits
- fixed some line break problems
which had extra <br /> elements
- fixed long source code lines
which mangle browser windows
- some copy edits, basically breaking up
long sentences and clarifying language
- fixed links to localhost webapp which will
break on the live site
- changed many <em> elements to <code> or <strong>
Current css makes it difficult too hard to
read large amounts of <em> elements
- moved configuration info to prerequisites
Revision Changes Path
1.2 +84 -85
xml-cocoon2/src/documentation/xdocs/howto/howto-html-pdf-publishing.xml
Index: howto-html-pdf-publishing.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/documentation/xdocs/howto/howto-html-pdf-publishing.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- howto-html-pdf-publishing.xml 3 Jul 2002 20:27:14 -0000 1.1
+++ howto-html-pdf-publishing.xml 3 Jul 2002 21:36:44 -0000 1.2
@@ -3,7 +3,7 @@
<document>
<header>
- <title>How to publish XML documents in HTML and PDF</title>
+ <title>How to Publish XML Documents in HTML and PDF</title>
<authors>
<person name="Bertrand Delacrètaz" email="[EMAIL PROTECTED]"/>
</authors>
@@ -13,20 +13,15 @@
<s1 title="Overview">
<p>
-Without requiring any prior knowledge of Cocoon, XSLT or XSL-FO, this How-To shows
you how to publish XML
-documents in HTML and PDF using Cocoon.
-<br/>
-The steps below have been tested with Cocoon 2.0.2-dev but should work with any 2.x
version.
+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.
</p>
</s1>
<s1 title="Purpose">
<p>
-We will build a simple pipeline that converts XML documents into HTML or PDF
on-the-fly using simple
-XSLT transforms.
-<br/>
-This is similar to the <em>hello.html</em> and <em>hello.pdf</em> samples of the
standard Cocoon installation, but here you
-will be building it yourself, which should help you get a better feel of how this
works.
+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>hello.html</code> and
<code>hello.pdf</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.
</p>
</s1>
@@ -40,20 +35,20 @@
<p>Here's what you need:</p>
<ul>
-<li>Cocoon must be running on your system . </li>
+<li>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.</li>
<li>This document assumes a standard installation where
-<link
href="http://localhost:8080/cocoon/mount/";>http://localhost:8080/cocoon/mount/</link>
points to
-the <em>mount</em> subdirectory of the Cocoon installation. Calling this URL should
display a page
+<code>http://localhost:8080/cocoon/mount/</code> points to
+the <code>mount</code> subdirectory of the Cocoon installation. Calling this URL
should display a page
titled "Directory Listing of mount".
-<br/>
+<br />
If your installation runs on a different URL, you will have to adjust
-the URLs given in this document accordingly.
+the URLs provided throughout this How-To as necessary.
</li>
-<li>You must be able to create and edit XML files in the <em>mount</em>
subdirectory of the Cocoon installation.
-In a standard installation, this is <em>webapps/cocoon/mount</em> under the
directory of the tomcat installation.
+<li>You must be able to create and edit XML files in the <code>mount</code>
subdirectory of the Cocoon installation.
+In a standard installation, this is <code>webapps/cocoon/mount</code> under the
directory of the Tomcat installation.
</li>
</ul>
-<note>You will not need a fancy XML editor for this, copying and pasting the
examples into any text editor
+<note>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.</note>
</s1>
@@ -65,35 +60,23 @@
<s2 title="1. Create the work directory under mount" >
<p>
-Under <em>webapps/cocoon/mount</em>, create a new directory named
<em>html-pdf</em>.
+Under <code>webapps/cocoon/mount</code>, create a new directory and name it
<code>html-pdf</code>.
All files used by this How-To will reside in this directory.
-<br/>
-After a browser refresh, <link
href="http://localhost:8080/cocoon/mount/";>http://localhost:8080/cocoon/mount/</link>
-should display the name of this new directory, among others.
+</p>
+<p>
+After a browser refresh, <code>http://localhost:8080/cocoon/mount/</code> should
display the name of this new directory, among others.
</p>
</s2>
<s2 title="2. Create the XML example documents" >
<p>
-To keep it simple we will use two small XML files as our data source.
-Later, you will probably use other data sources like live XML feeds, databases,
etc.
-</p>
+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.</p>
<p>
-In the <em>html-pdf</em> directory, create the following two files, naming them
exactly as
+In the <code>html-pdf</code> directory, create the following two files, and name
them exactly as
shown.
</p>
-<note>
-Be careful about lower/uppercase in filenames if you're working on a unix or linux
system.
-On such systems, <em>thisFile.xml</em> is not the same as <em>Thisfile.xml</em>.
-</note>
-<note>
-To avoid any errors, use copy/paste when creating XML documents from examples on
this page.
-<br/>
-Also, do not leave spaces at the start of XML files - the <?xml... processing
instruction must
-be the first character in the file.
-</note>
-
<p>
Contents of file <strong>pageOne.xml</strong>:
</p>
@@ -119,17 +102,28 @@
</s1>
</page>
]]></source>
-
+
+<note>
+Be careful about the use of lower/uppercase in filenames if you're working on a
Unix or Linux system.
+On such systems, <code>thisFile.xml</code> is not the same as
<code>Thisfile.xml</code>.
+</note>
+<note>
+To avoid any errors, use copy/paste when creating XML documents from examples on
this page.
+</note>
+<note>
+Do not leave spaces at the start of XML files. The <?xml... processing
instruction must
+be the first character in the file.
+</note>
</s2>
<s2 title="3. Create the XSLT transform for HTML" >
<p>
-The most common way of producing HTML in Cocoon is to use <em>XSLT transforms</em>
to select and convert
+The most common way of producing HTML in Cocoon is to use <strong>XSLT
transforms</strong> to select and convert
the appropriate elements of the input documents.
</p>
<p>
-Copy the file shown below to the <em>html-pdf</em> directory alongside your XML
documents, naming it
+Copy the file shown below to the <code>html-pdf</code> directory alongside your XML
documents, naming it
<strong>doc2html.xsl</strong>
</p>
@@ -164,22 +158,21 @@
]]></source>
<note>
Basically what this does is generate an HTML skeleton and convert the input markup
to HTML. We won't go
-into details here, our goal is just to show you how the components of the
publishing chain are combined.
+into details here. Rather, our goal is to show you how the components of the
publishing chain are combined.
</note>
</s2>
<s2 title="4. Create the sitemap" >
<p>
-We now have documents to publish, and an XSLT transform to convert them to our HTML
output format.
-What's left is to connect these together when a request is made to Cocoon - that's
the role of the <em>sitemap</em>,
-which will select a <em>processing pipeline</em> based on the request received from
the browser.
+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 <strong>processing pipeline</strong>. Then, the
<strong>sitemap</strong> can select the pipeline based on the details of the browser
request.
</p>
<p>
-To tell Cocoon how we want it to process requests made to <em>html-pdf</em>,
-copy the following contents to a file named <strong>sitemap.xmap</strong> in the
-<em>html-pdf</em> subdirectory.
+To tell Cocoon how to process requests made to <code>html-pdf</code>,
+copy the following snippet to a file named <strong>sitemap.xmap</strong> in the
+<code>html-pdf</code> subdirectory.
</p>
<source><![CDATA[
@@ -199,14 +192,16 @@
<map:pipelines>
<map:pipeline>
- <!-- respond to *.html requests with our docs processed by doc2html.xsl
-->
+ <!-- respond to *.html requests with
+ our docs processed by doc2html.xsl -->
<map:match pattern="*.html">
<map:generate src="{1}.xml"/>
<map:transform src="doc2html.xsl"/>
<map:serialize type="html"/>
</map:match>
- <!-- later, respond to *.pdf requests with our docs processed by
doc2pdf.xsl -->
+ <!-- later, respond to *.pdf requests with
+ our docs processed by doc2pdf.xsl -->
<map:match pattern="*.pdf">
<map:generate src="{1}.xml"/>
<map:transform src="doc2pdf.xsl"/>
@@ -218,10 +213,9 @@
]]></source>
<note>The important thing here is the first <strong>map:match</strong> 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.
+requests ending in *.html in this directory. Again, we won't go into details here,
but that's where it happens.
</note>
-<note>The above sitemap is already configured for PDF publishing, but this is not
usable at this time as we haven't created
-the required XSLT transform yet.</note>
+<note>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.</note>
</s2>
@@ -231,16 +225,16 @@
</p>
<ul>
<li>
-<link
href="http://localhost:8080/cocoon/mount/html-pdf/pageOne.html";>http://localhost:8080/cocoon/mount/html-pdf/pageOne.html</link>
+<code>http://localhost:8080/cocoon/mount/html-pdf/pageOne.html</code>
should display the first page with "Section one" in big letters.
</li>
<li>
-<link
href="http://localhost:8080/cocoon/mount/html-pdf/pageTwo.html";>http://localhost:8080/cocoon/mount/html-pdf/pageTwo.html</link>
+<code>http://localhost:8080/cocoon/mount/html-pdf/pageTwo.html</code>
should display the second page with "Yes it works" in big letters.
</li>
</ul>
-<note>If this doesn't work, you might want to first doublecheck the above steps,
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
+<note>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.
</note>
</s2>
@@ -248,14 +242,14 @@
<s2 title="6. Create the XSLT transform for PDF" >
<p>
-PDF documents are created via XSL-FO documents, which are XML documents that use a
specific page-description
-vocabulary (see <link href="#references">References</link> below for more info).
The actual conversion to PDF is done by the
-<em>PdfSerializer</em> which uses software from <link
href="http://xml.apache.org/fop";>FOP</link>, another Apache
+PDF documents are created via XSL-FO documents which are XML documents that use a
specific page-description
+vocabulary. (See <link href="#references">References</link> below for more info).
The actual conversion to PDF is done by the
+<code>PdfSerializer</code> which uses software from <link
href="http://xml.apache.org/fop";>FOP</link>, another Apache
Software Foundation project.
</p>
<p>
-To activate the PDF conversion, copy the file shown below to the <em>html-pdf</em>
directory alongside your XML documents, naming it
+To activate the PDF conversion, copy the code snippet shown below to the
<code>html-pdf</code> directory along with your XML documents, and name it
<strong>doc2pdf.xsl</strong>
</p>
@@ -284,7 +278,8 @@
<fo:page-sequence-master master-name="all">
<fo:repeatable-page-master-alternatives>
- <fo:conditional-page-master-reference
master-reference="page" page-position="first"/>
+ <fo:conditional-page-master-reference
+ master-reference="page" page-position="first"/>
</fo:repeatable-page-master-alternatives>
</fo:page-sequence-master>
</fo:layout-master-set>
@@ -313,7 +308,7 @@
</xsl:stylesheet>
]]>
</source>
-<note>This file is already referenced by the sitemap that we created, so no
additional configuration is needed.</note>
+<note>This file is already referenced by the sitemap we created, so no additional
configuration is needed.</note>
</s2>
<s2 title="5. Test the PDF publishing" >
@@ -322,11 +317,11 @@
</p>
<ul>
<li>
-<link
href="http://localhost:8080/cocoon/mount/html-pdf/pageOne.pdf";>http://localhost:8080/cocoon/mount/html-pdf/pageOne.pdf</link>
+<code>http://localhost:8080/cocoon/mount/html-pdf/pageOne.pdf</code>
should display the first page with "Section one" in big red letters.
</li>
<li>
-<link
href="http://localhost:8080/cocoon/mount/html-pdf/pageTwo.pdf";>http://localhost:8080/cocoon/mount/html-pdf/pageTwo.pdf</link>
+<code>http://localhost:8080/cocoon/mount/html-pdf/pageTwo.pdf</code>
should display the second page with "Yes it works" in big red letters.
</li>
</ul>
@@ -336,28 +331,31 @@
<s1 title="Summary">
<p>
-Hopefully you're beginning to see that this is not too complicated once you know
what goes where.
-<br/>
+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.
+</p>
+<p>
The nice thing is that all of our huge corpus
-of XML documents (two documents actually, but that's a start..) is processed by
just two XSLT files, one
+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.
-<br/>
-Changing the appearance of the published documents would require changing these
XSLT transforms only, without
-touching the source documents.
+</p>
+<p>
+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.
</p>
</s1>
<s1 title="Tips">
<s2 title="Tip 1: Dynamic XML data">
<p>
-Using dynamic XML as the data source is very easy as the Cocoon FileGenerator can
read URLs as well.
-<br/>
+Using dynamic XML as the data source is very easy because the Cocoon FileGenerator
can read URLs as well.
+</p>
+<p>
If you add the map:match element shown in bold below <strong>before</strong> the
existing map:match elements in your sitemap.xmap file, requesting
-<link
href="http://localhost:8080/cocoon/mount/html-pdf/meerkat.html";>http://localhost:8080/cocoon/mount/html-pdf/meerkat.html</link>
+<code>http://localhost:8080/cocoon/mount/html-pdf/meerkat.html</code>
should display real-time news from Meerkat (assuming an Internet connection to
Meerkat is available).
-<br/>
-The news will be displayed in a very rough format, but this can be made better by
writing a
-specific XSLT transform for this Meerkat data and using it instead of doc2html.xsl
in the meerkat.html pipeline.
+</p>
+<p>
+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.
</p>
<source>
@@ -383,11 +381,12 @@
<s2 title="Tip 2: Two-step conversion">
<p>
-When you are generating multiple formats from a single data source, it is often a
good idea to first generate
-an intermediate <em>logical document</em> that describes the output in a
format-neutral way.
-<br/>
-This is obviously not needed in our simple example, but if you're aiming at more
complicated
-publishing tasks you might want to read about this "publishing pattern" in Martin
Fowler's
+When you are generating multiple formats from a single data source, it is often a
good idea to generate
+an intermediate <strong>logical document</strong> that describes the output in a
format-neutral way.
+</p>
+<p>
+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
<link href="http://www.martinfowler.com/isa/htmlRenderer.html";>Two Step View</link>
article.
</p>
@@ -398,16 +397,16 @@
<s1 title="References">
<anchor id="references"/>
<p>
-To go further, you will need to learn about the following technologies and tools:
+To go further, you will need to learn about the following technologies and tools.
</p>
<ul>
<li>
-Learning about the
+Learning
<link
href="http://www.google.com/search?as_sitesearch=xml.apache.org&as_q=cocoon+concepts+sitemap";>
-Cocoon concepts</link> will help you understand how the sitemap, generators,
transformers and serializers work.
+Cocoon concepts</link> will help you understand how the sitemap, generators,
transformers, and serializers work.
</li>
<li>
-Learning about <link href="http://www.w3.org/Style/XSL/";>XSLT</link> will allow you
to write your own transforms to
+Learning about <link href="http://www.w3.org/Style/XSL/";>XSLT</link> 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.
</li>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
