# Frequently Asked Questions

# Plugin Usage

How do I use the PDF Plugin ?

- First you must call the maven target `site` to generate all the xdocs files and the image ressources.
- Then you can call the `pdf` target to generate the pdf documentation for your project.

To automate the pdf creation you can add a post goal to the site like this :

    <postGoal name="site">
      <attainGoal name="pdf"/>
    </postGoal>

How do I use the PDF Plugin with a multiproject ?

To generate a PDF from documentations defined in several sub-projects, you must copy all the xdocs files from these projects.

Here is an example on how to do it :

    <attainGoal name="multiproject:site"/>
    <maven:reactor
      basedir="${basedir}"
      postProcessing="true"
      includes="**/project.xml"
      collectOnly="true"
      ignoreFailures="false"
      collectionVar="multiprojects"/>
    <!-- We copy the generated files to use them in the pdf -->
    <j:forEach var="reactorProject" items="${multiprojects}">
      <j:set var="fromDir" value="${reactorProject.context.getVariable('maven.gen.docs')}"/>
      <ant:copy todir="${maven.build.dir}/pdf/${maven.multiproject.aggregateDir}${reactorProject.artifactId}">
        <ant:fileset dir="${fromDir}" force="true">
          <ant:include name="**/*.*"/>
        </ant:fileset>
      </ant:copy>
    </j:forEach>
    <attainGoal name="pdf"/>

You can also createa dynamic menu using Velocity macro in your navigation.xml file. For example :

    <project name="$pom.name">
      <body>
        <links/>
        <menu name="Overview">
            #if ($overviewPageCreate == "true" )
            <item name="${overviewPageLinkTitle}" href="${overviewPageLink}.html"/>
            #end
        </menu>
        <menu name="Sub-Projects">
            #foreach ($reactorProject in $multiprojects)
            <item name="$reactorProject.name" href="/${aggregateDir}${reactorProject.artifactId}/index.html"/>
            <item name="$reactorProject.name test" href="/${aggregateDir}${reactorProject.artifactId}/test.html"/>
            #end
        </menu>
      </body>
    </project>

Which types of images can I use in my documents ?

You can use images types that FOP can use.

The table below summarizes the theoretical support for graphical formats within FOP.

Format | Type | Support Thru
--- | --- | ---
BMP (Microsoft Windows Bitmap) | bitmap | FOP native
EPS (Encapsulated PostScript) | metafile (both bitmap and vector), probably most frequently used for vector drawings | FOP native (limited support, see restrictions below)
GIF (Graphics Interchange Format) | bitmap | FOP native
JPEG (Joint Photographic Experts Group) | bitmap | FOP native
PNG (Portable Network Graphic) | bitmap | JIMI (using the property "maven.jar.jimi") or JAI (using properties "maven.jar.jaicore" and "maven.jar.jaicodec")
SVG (Scalable Vector Graphics) | vector (with embedded bitmaps) | Batik
TIFF (Tag Image Format File) | bitmap | FOP native or JAI (using properties "maven.jar.jaicore" and "maven.jar.jaicodec"), depending on the subformat. See TIFF for more details.(JIMI also supports TIFF, but this has not been implemented within FOP).

How can I insert png images in my pdf ?

You must download and put somewhere on your disk JAI or JIMI (on your repository is a good place for it).

Then you must register the one you installed with for JIMI :

    maven.jar.jimi=${maven.repo.local}/jimi/jars/jimi-X.Y.Z.jar

Or for JAI :

    maven.jar.jaicore=${maven.repo.local}/jai/jars/jai_core-X.Y.Z.jar
    maven.jar.jaicodec=${maven.repo.local}/jai/jars/jai_codec-X.Y.Z.jar