How to create a PDF document for each tab

Users who need to generate one printable document aggregated from a group of documents.

By default Forrest generates a pdf file for each separate document of your project. As well you can create a pdf of the whole site. But sometimes it may be necessary to generate a pdf file out of selected tab, i.e. only for certain parts of the site.

• Understand how to create project-specific sitemaps by following the Using Forrest document.

The procedure outlined below will define a project sitemap.xmap and create a new pdf-tab.xmap based on the aggregate.xmap

Create your project's main sitemap.xmap

Simply copy the sitemap.xmap from the Forrest sitemaps at ${FORREST_HOME}/context/sitemap.xmap into your src/documentation directory (or wherever ${project.sitemap-dir} points to).

Create the aggregator sitemap pdf-tab.xmap

Copy the aggregate.xmap from Forrest sitemaps into your ${project.sitemap-dir} and rename it to pdf-tab.xmap

Edit project sitemap.xmap

Edit the project sitemap.xmap to comment-out the match for the sitemap like this:

<!--
<map:pipeline internal-only="false">
<map:select type="exists">
  <map:when test="{properties:sitemap}">
    <map:mount uri-prefix="" src="{properties:sitemap}" check-reload="yes" />
  </map:when>  
</map:select>
</map:pipeline
-->
    

Edit project sitemap.xmap to mount pdf-tab.xmap

Insert the following lines after the <map:match pattern="site.xml"> pipeline in the section called "SOURCE FORMATS".

...
<map:match pattern="pdf-tab.xml">
   <map:mount uri-prefix="" src="pdf-tab.xmap" check-reload="yes" />
</map:match>
...
    

Edit the file pdf-tab.xmap

The <map:match pattern="*.xml"> element should look like the following:

<map:match pattern="*.xml">
  <map:generate src="cocoon://abs-linkmap"/>
  <map:transform type="xpath">
	<map:parameter name="include" value="//*[@wholesite='true']"/>
	<map:parameter name="exclude" value="//*[@wholesite='false']"/>
  </map:transform>
  <map:transform src="resources/stylesheets/site2book.xsl" />
  <map:transform src="resources/stylesheets/aggregates/book2cinclude.xsl">
     <map:parameter name="title"
        value="{conf:project-name}: Still My Foo Site"/>
  </map:transform>
  <map:transform type="cinclude"/>
  <map:transform src="resources/stylesheets/aggregates/doc2doc-uniqueids.xsl"/>
  <map:transform src="resources/stylesheets/aggregates/docs2document.xsl"/>
  <map:serialize type="xml"/>
</map:match>
    

Edit your site.xml

Add the following entry to your site.xml in the <about> element

... 
<whole_foosite href="pdf-tab.html" label="sub site" />
    

Your site.xml should look like this ...

... 
<about label="About">
  <index label="Index" href="index.html" description="Welcome to MyProj"/>
  <changes label="Changes" href="changes.html"
    description="History of Changes" />
  <todo label="Todo" href="todo.html" description="Todo List" />
  <whole_foosite href="pdf-tab.html" label="pdf-tab" />
</about>
...
    

This allows you to link to it via a <link href="site:v0.60//whole_foosite"> reference.

Add to every element that should be included in the pdf-tab.pdf the attribute wholesite="true"

<sample-wiki label="Wiki page" href="wiki-sample.html"
  description="wiki-sample" wholesite="true"/>
	  

Explanation of the operation

Line 4 of our example
<map:parameter name="include" value="//*[@wholesite='true']"/> looks at your site.xml and will match every element containing the wholesite="true" attribute. For example, to use the "samples" tab ...

...
<samples label="Samples" href="samples/" tab="samples" wholesite="true">
...
</samples>
...
    

It matches all of the elements that contain wholesite="true" (in our example <samples> and its "children") for the content of the pdf file to be generated.

 
<samples label="Samples" href="samples/" tab="samples" wholesite="true">
 <sample2 label="Static content" href="sample2.html"      
   description="More Samples" wholesite='false'/>
 <sample-wiki label="Wiki page" href="wiki-sample.html"      
   description="wiki-sample" />
 <sample-ihtml label="ihtml page" href="ihtml-sample.html"      
   description="Test iHTML page" />
</samples>     	
    

This example shows that you can as well exclude site(s) from the aggregation by using the wholesite="false" attribute. This attribute will be as well inherited by all children of the element.

Line 8 defines the title of the pdf file by taking the content of the project-name variable in skinconf.xml and adding some funny text:
<map:parameter name="title" value="{conf:project-name}: Still My Foo Site"/>

Please provide feedback about this document via the mailing lists.

In the future, this ability will probably be incorporated into the main Forrest process.