[Maven-plugins-cvs] cvs commit: maven-plugins/sdocbook/xdocs users-guide.xml

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

perolesen    04/04/12 06:41:44

  Added:       sdocbook/xdocs users-guide.xml
  Log:
  Added a users guide
  
  Revision  Changes    Path
  1.1                  maven-plugins/sdocbook/xdocs/users-guide.xml
  
  Index: users-guide.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
  
    <properties>
      <title>Users Guide - sdocbook</title>
      <author email="po...@no...">Per Olesen</author>
    </properties>
  
    <body>
  
      <section name="Introduction">
        <p>
          We assume you have some sources of DocBook XML documents, that you wish to process
          and convert into pdf or html output.
        </p>
      </section>
  
      <section name="Basic usage">
        <p>
          Put you DocBook sources into dir which "maven.sdocbook.src.dir" property points to.
        </p>
        <p>
          Simply typing "maven sdocbook" will generate both html and pdf. The html is produced
          directly from the sources. The pdf output is done in a two-step process, first converting
          sources to FO using the <a href="http://docbook.sourceforge.net/">DocBook stylesheets</a> and then
          converting the FO output to pdf using the <a href="http://xml.apache.org/fop/">Apache FOP</a> processor.
        </p>
      </section>
  
      <section name="Parameterizing stylesheets">
        <p>
          The stylesheets which this plugin uses can be controlled with parameters.
          For examle, they implement various extensions, which you need to enable if you want them in output.
        </p>
        <p>
          Taking the stylesheets which convert into html as example, you could set the "draft" option by setting
          the property "maven.sdocbook.html.params==-param draft.mode yes" in your project.properties.
        </p>
      </section>
  
      <section name="Using another version of stylesheets">
        <p>
          The plugin includes a specific version of the <a href="http://docbook.sourceforge.net/">DocBook stylesheets</a>
          but these are developed in a separate project, and might very well be available in newer versions than
          included in this plugin.
        </p>
        <p>
          Then it is lucky, that you can point to a newer version :-)
          You simply need to set the "maven.sdocbook.stylesheets.dir" property to point to the location
          of the version you want to use.
        </p>
        <p>
          One way of doing this is to manually get a distribution of the stylesheets you want and point to
          the location where you unzip them.
          Another way of doing this is to let your project depend on the version of the stylesheets as a maven
          dependency, and then pointing the maven.sdocbook.stylesheets.dir property into you maven.repo.local.
          This requires that the docbook stylesheets are in a repository you can access.
          The maven repository at Ibiblio has some <a href="http://www.ibiblio.org/maven/docbook/">here</a>.
        </p>
      </section>
    </body>
  </document>