[jboss-svn-commits] JBL Code SVN: r13216 - in labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src: site and 2 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sat Jul 7 15:46:15 EDT 2007
Author: steve.ebersole at jboss.com
Date: 2007-07-07 15:46:15 -0400 (Sat, 07 Jul 2007)
New Revision: 13216
Added:
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/arbitrary-styles.apt
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/docbook-version.apt
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/jdocbook-style.apt
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/project-local-style.apt
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/formats.apt
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/staging.apt
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/style.apt
Removed:
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/main/java/org/jboss/maven/plugins/jdocbook/TestIt.java
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/docbook-support.apt
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/resource-staging.apt
Modified:
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/custom-xslt.apt
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/index.apt
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/usage.apt
labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/site.xml
Log:
fleshed out docs a bit more
Deleted: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/main/java/org/jboss/maven/plugins/jdocbook/TestIt.java
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/main/java/org/jboss/maven/plugins/jdocbook/TestIt.java 2007-07-07 19:02:56 UTC (rev 13215)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/main/java/org/jboss/maven/plugins/jdocbook/TestIt.java 2007-07-07 19:46:15 UTC (rev 13216)
@@ -1,40 +0,0 @@
-/*
- * Copyright (c) 2007, Red Hat Middleware, LLC. All rights reserved.
- *
- * This copyrighted material is made available to anyone wishing to use, modify,
- * copy, or redistribute it subject to the terms and conditions of the GNU
- * Lesser General Public License, v. 2.1. This program is distributed in the
- * hope that it will be useful, but WITHOUT A WARRANTY; without even the implied
- * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- * Lesser General Public License for more details. You should have received a
- * copy of the GNU Lesser General Public License, v.2.1 along with this
- * distribution; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
- *
- * Red Hat Author(s): Steve Ebersole
- */
-package org.jboss.maven.plugins.jdocbook;
-
-/**
- * {@inheritDoc}
- *
- * @author Steve Ebersole
- */
-public class TestIt {
- public static void main(String[] args) {
- String name = "//hola.txt";
- name = parse( name );
- System.out.println( "Parsed name : [" + name + "]");
-
- name = "classpath:" + name;
- name = parse( name.substring( 10 ) );
- System.out.println( "Parsed name : [" + name + "]");
- }
-
- private static String parse(String name) {
- while ( name.startsWith( "/" ) ) {
- name = name.substring( 1 );
- }
- return name;
- }
-}
Deleted: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/docbook-support.apt
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/docbook-support.apt 2007-07-07 19:02:56 UTC (rev 13215)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/docbook-support.apt 2007-07-07 19:46:15 UTC (rev 13216)
@@ -1,46 +0,0 @@
- ------
- DocBook Support
- ------
- Steve Ebersole
- ------
- 2 July 2007
- ------
-
-~~ Copyright © 2007 Red Hat Middleware, LLC. All rights reserved.
-~~
-~~ This copyrighted material is made available to anyone wishing to use, modify,
-~~ copy, or redistribute it subject to the terms and conditions of the GNU
-~~ Lesser General Public License, v. 2.1. This program is distributed in the
-~~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied
-~~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-~~ Lesser General Public License for more details. You should have received a
-~~ copy of the GNU Lesser General Public License, v.2.1 along with this
-~~ distribution; if not, write to the Free Software Foundation, Inc.,
-~~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-~~
-~~ Red Hat Author(s): Steve Ebersole
-
-docbook-support integration
-
- <docbook-support> is another maven packaging type, defined by the
- org.jboss.maven.plugins:maven-docbook-support-plugin plugin. The goal
- of the <docbook-support> is to define a common, resuable packaging bundle
- for DocBook support resources such as XSLT, images, fonts and css.
- The <jDocBook Plugin> can take advantage of a <docbook-support> dependency
- in two ways:
-
- [[1]] Because
-
- [[a]] dependencies are added to the classpath
-
- [[b]] the <jDocBook Plugin> can locate XSLT via classpath resources (see {{{examples/custom-xslt.html} example}})
-
- []
-
- users can reference XSLT stylesheets from a <docbook-support> dependency
- as a custom stylesheet (see the {{{usage.html}usage}} page).
-
- [[2]] Given the {{{staging.html}staging}} approach taken by this plugin
- for dealing with with resources (css, fonts and images) it automatically
- stages any css, font or image resources found inside a dependency of
- type <docbook-support>. See {{{examples/resource-staging.html}example}}.
\ No newline at end of file
Added: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/arbitrary-styles.apt
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/arbitrary-styles.apt (rev 0)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/arbitrary-styles.apt 2007-07-07 19:46:15 UTC (rev 13216)
@@ -0,0 +1,30 @@
+ ------
+ Arbitrary Styles
+ ------
+ Steve Ebersole
+ ------
+ 2 July 2007
+ ------
+
+~~ Copyright © 2007 Red Hat Middleware, LLC. All rights reserved.
+~~
+~~ This copyrighted material is made available to anyone wishing to use, modify,
+~~ copy, or redistribute it subject to the terms and conditions of the GNU
+~~ Lesser General Public License, v. 2.1. This program is distributed in the
+~~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied
+~~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+~~ Lesser General Public License for more details. You should have received a
+~~ copy of the GNU Lesser General Public License, v.2.1 along with this
+~~ distribution; if not, write to the Free Software Foundation, Inc.,
+~~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+~~
+~~ Red Hat Author(s): Steve Ebersole
+
+Applying Arbitrary Styles
+
+ Because of the plugin's use of {{{../staging.html}staging}} to
+ handle style resources, users can actually use resources from any
+ source as style elements. For example, here we use the <dependency>
+ plugin to unpack a zip file into the staging directory directly:
+
+ <todo : the example...>
\ No newline at end of file
Modified: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/custom-xslt.apt
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/custom-xslt.apt 2007-07-07 19:02:56 UTC (rev 13215)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/custom-xslt.apt 2007-07-07 19:46:15 UTC (rev 13216)
@@ -76,12 +76,12 @@
+----+
-* docbook-support classpath: URL
+* jdocbook-style classpath: URL
- See {{{../docbook-support.html}here}} for background discussion.
+ See {{{../style.html}here}} for background discussion.
- As a specific example of using an XSLT defined in a <docbook-support> package,
- consider the following docbook-support package distributed by the venerable
+ As a specific example of using an XSLT defined in a <jdocbook-style> package,
+ consider the following jdocbook-style package distributed by the venerable
Acme Corporation:
+----+
@@ -89,7 +89,7 @@
xslt/
com/
acme/
- fo.xslt
+ fo.xsl
+----+
Using that would be as simple as:
@@ -103,14 +103,14 @@
<dependency>
<groupId>com.acme</groupId>
<artifactId>acmeskin</artifactId>
- <type>docbook-support</type>
+ <type>jdocbook-style</type>
</dependency>
</dependencies>
<configuration>
<formats>
<format>
<formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/com/acme/fo.xslt</stylesheetResource>
+ <stylesheetResource>classpath:/xslt/com/acme/fo.xsl</stylesheetResource>
</format>
</formats>
</configuration>
Added: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/docbook-version.apt
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/docbook-version.apt (rev 0)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/docbook-version.apt 2007-07-07 19:46:15 UTC (rev 13216)
@@ -0,0 +1,30 @@
+ ------
+ Specific DocBook Version
+ ------
+ Steve Ebersole
+ ------
+ 2 July 2007
+ ------
+
+~~ Copyright © 2007 Red Hat Middleware, LLC. All rights reserved.
+~~
+~~ This copyrighted material is made available to anyone wishing to use, modify,
+~~ copy, or redistribute it subject to the terms and conditions of the GNU
+~~ Lesser General Public License, v. 2.1. This program is distributed in the
+~~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied
+~~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+~~ Lesser General Public License for more details. You should have received a
+~~ copy of the GNU Lesser General Public License, v.2.1 along with this
+~~ distribution; if not, write to the Free Software Foundation, Inc.,
+~~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+~~
+~~ Red Hat Author(s): Steve Ebersole
+
+Specific DocBook Version
+
+ The version of DocBook to use is itself defined as dependency. By default,
+ the version defined by the <jDocBook Plugin> is used, so that would depend
+ on the version of the <jDocBook Plugin> used.
+
+ It is however, possible to override that and say to use another version of
+ DocBook instead, simply by defining the new version as a dependency.
\ No newline at end of file
Added: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/jdocbook-style.apt
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/jdocbook-style.apt (rev 0)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/jdocbook-style.apt 2007-07-07 19:46:15 UTC (rev 13216)
@@ -0,0 +1,129 @@
+ ------
+ Complete jdocbook-style Example
+ ------
+ Steve Ebersole
+ ------
+ 2 July 2007
+ ------
+
+~~ Copyright © 2007 Red Hat Middleware, LLC. All rights reserved.
+~~
+~~ This copyrighted material is made available to anyone wishing to use, modify,
+~~ copy, or redistribute it subject to the terms and conditions of the GNU
+~~ Lesser General Public License, v. 2.1. This program is distributed in the
+~~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied
+~~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+~~ Lesser General Public License for more details. You should have received a
+~~ copy of the GNU Lesser General Public License, v.2.1 along with this
+~~ distribution; if not, write to the Free Software Foundation, Inc.,
+~~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+~~
+~~ Red Hat Author(s): Steve Ebersole
+
+Complete jdocbook-style Example
+
+ The intention in splitting the <jdocbook> plugin and <jdocbook-style> plugin
+ is the notion of separation-of-concerns; namely, let documentation content
+ developers focus on developing content, while documentation style developers
+ develop the "look and feel" of the produced output(s). This split represents
+ the "sweet spot" for this plugin, and is the main intended use-case. So let's
+ take a look at this approach from beginning to end.
+
+ Since an example, is worth (probably more than) a thousand words for most
+ of us, lets take a look at an example of the approach of combining these
+ two plugins. As I mentioned before, the venerable Acme Corporation produces a
+ <jdocbook-style> bundle for all their product manulas. As the person in charge
+ of Acme's latest product, WhizBang, you'll need to utilize that style bundle in producing
+ your manual.
+
+* The jdocbook-style bundle
+
+ Acme Corporation only produces manuals in PDF format. And they have a minimum
+ of custom images. Here is the source layout of the acme-manual-style
+ project:
+
++----+
+acme-manual-style/
+ images/
+ acme-corp-logo.svg
+ xslt/
+ acme-manual.xsl
+ pom.xml
++----+
+
+ <Generally, as a developer of a jdocbook project you would not need to
+ know such details about the source structure of the corresponding
+ jdocbook-style project. The above is included just in the interest
+ of completeness.>
+
+ That project source produces an artifact named acme-manual-style.jdocbook-style (the
+ artifact is really a jar file, but unfortunately Maven forces the artifact
+ to have an extension matching the name of the packaging, which here is
+ jdocbook-style). The contents of that archive are as follows:
+
++----+
+ images/
+ acme-corp-logo.svg
+ xslt/
+ acme-manual.xsl
+ META-INF/
+ ....
++----+
+
+ <See the documentation of the maven-jdocbook-style-plugin> project for more
+ details. The above was a very brief overview.>
+
+* The WhizBang manual project
+
+ First, we create the project directory structure:
+
++----+
+whizbang-manual/
+ src/
+ main/
+ docbook/
+ whizbang.xml
+ whizbang-front.gif
+ whizbang-back.gif
+ pom.xml
++----+
+
+ Let's take a look at the pom.xml for the WhizBang manual...
+
++----+
+<project>
+ ...
+ <groupId>com.acme</groupId>
+ <artifactId>whizbang-manual<artifactId>
+ <type>jdocbook</type>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifacId>maven-jdocbook-plugin</artifactId>
+ <extensions>true</extensions>
+ <dependencies>
+ <!--- This is the jdocbook-style discussed above -->
+ <dependency>
+ <groupId>com.acme</groupId>
+ <artifactId>acme-manual-style</artifactId>
+ <type>jdocbook-style</type>
+ </dependency>
+ </dependencies>
+ <configuration>
+ <formats>
+ <format>
+ <formatName>pdf</formatName>
+ <stylesheetResource>classpath:/xslt/acme-manual.xsl</stylesheetResource>
+ </format>
+ </formats>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+</project>
++----+
+
+ Those of you who have developed with DocBook before may not believe this,
+ but that's all there is to it. The plugin and Maven's dependency mechanism
+ take care of the rest.
\ No newline at end of file
Added: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/project-local-style.apt
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/project-local-style.apt (rev 0)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/project-local-style.apt 2007-07-07 19:46:15 UTC (rev 13216)
@@ -0,0 +1,51 @@
+ ------
+ Project Local Style
+ ------
+ Steve Ebersole
+ ------
+ 2 July 2007
+ ------
+
+~~ Copyright © 2007 Red Hat Middleware, LLC. All rights reserved.
+~~
+~~ This copyrighted material is made available to anyone wishing to use, modify,
+~~ copy, or redistribute it subject to the terms and conditions of the GNU
+~~ Lesser General Public License, v. 2.1. This program is distributed in the
+~~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied
+~~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+~~ Lesser General Public License for more details. You should have received a
+~~ copy of the GNU Lesser General Public License, v.2.1 along with this
+~~ distribution; if not, write to the Free Software Foundation, Inc.,
+~~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+~~
+~~ Red Hat Author(s): Steve Ebersole
+
+Project Local Style
+
+ As disucssed {{{../style.html}here}}, a jdocbook project may provide custom
+ style elements. Currently this is limited to images and css. These are
+ controlled by the <<imageResource>> and <<cssResource>> parameters. For example,
+ a common approach to developing DocBook-based documentation is to keep the
+ source and images in the same relative directory:
+
++----+
+<plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifacId>maven-jdocbook-plugin</artifactId>
+ <extensions>true</extensions>
+ <configuration>
+ <sourceDirectory>src/main/docs</sourceDirectory>
+ <sourceDocumentName>my-doc.xml</sourceDocumentName>
+ <imageResource>
+ <directory>src/main/docs</directory>
+ <includes>
+ <include>**/*.png</include>
+ <include>**/*.svg</include>
+ <include>**/*.gif</include>
+ </includes>
+ </imageResource>
+ ...
+ </configuration>
+</plugin>
++----+
+
Deleted: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/resource-staging.apt
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/resource-staging.apt 2007-07-07 19:02:56 UTC (rev 13215)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/examples/resource-staging.apt 2007-07-07 19:46:15 UTC (rev 13216)
@@ -1,35 +0,0 @@
- ------
- Resource Staging
- ------
- Steve Ebersole
- ------
- 2 July 2007
- ------
-
-~~ Copyright © 2007 Red Hat Middleware, LLC. All rights reserved.
-~~
-~~ This copyrighted material is made available to anyone wishing to use, modify,
-~~ copy, or redistribute it subject to the terms and conditions of the GNU
-~~ Lesser General Public License, v. 2.1. This program is distributed in the
-~~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied
-~~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-~~ Lesser General Public License for more details. You should have received a
-~~ copy of the GNU Lesser General Public License, v.2.1 along with this
-~~ distribution; if not, write to the Free Software Foundation, Inc.,
-~~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-~~
-~~ Red Hat Author(s): Steve Ebersole
-
-Resource Staging
-
-* Project local resources
-
- todo
-
-* docbook-support resources
-
- todo
-
-* Arbitrary resources
-
- todo
\ No newline at end of file
Added: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/formats.apt
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/formats.apt (rev 0)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/formats.apt 2007-07-07 19:46:15 UTC (rev 13216)
@@ -0,0 +1,124 @@
+ ------
+ Format
+ ------
+ Steve Ebersole
+ ------
+ 7 July 2007
+ ------
+
+~~ Copyright © 2007 Red Hat Middleware, LLC. All rights reserved.
+~~
+~~ This copyrighted material is made available to anyone wishing to use, modify,
+~~ copy, or redistribute it subject to the terms and conditions of the GNU
+~~ Lesser General Public License, v. 2.1. This program is distributed in the
+~~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied
+~~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+~~ Lesser General Public License for more details. You should have received a
+~~ copy of the GNU Lesser General Public License, v.2.1 along with this
+~~ distribution; if not, write to the Free Software Foundation, Inc.,
+~~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+~~
+~~ Red Hat Author(s): Steve Ebersole
+
+Format
+
+ Format is the term used to describe a particular output option for
+ a DocBook transformation. For example, we might talk about the PDF
+ output format, or the HTML output format.
+
+* Supported formats
+
+ The <jDocBook Plugin> has support for most of the standard DocBook defined
+ formats as (as of DocBook version 1.70.1 and later). For completeness,
+ here is the full list of supported formats (as defined by the
+ {{{xref/org/jboss/maven/plugins/jdocbook/gen/util/StandardDocBookFormatSpecification.html}StandardDocBookFormatSpecification}}
+ class):
+
+ * HTML-based
+
+ [eclipse] generates an eclipse documentation bundle
+
+ [html] generates chunked HTML
+
+ [html_single] generated non-chunked HTML
+
+ [htmlhelp] generates HTMLHelp style documentation
+
+ [javahelp] generates JavaHelp style documentation
+
+ [man] generates HTML-based *nix man pages
+
+ [website] generates a website (?)
+
+ [xhtml] generates XHTML-compliant documentation
+
+ []
+
+ * FO-based
+
+ [pdf] generates a PDF document
+
+ []
+
+ []
+
+* Configuring formats
+
+ Configuration of formats occurs via the {{{xref/org/jboss/maven/plugins/jdocbook/Format.html}Format}}
+ class. The list of configurable properties defined by the Format config
+ class include:
+
+ [formatName] This is the name of the output format. At least as of this
+ moment, this <<must>> map to one of the standard DocBook formats
+ detailed above; these values, then, simply act as overrides for the
+ values defined by the standard DocBook formats. This may change in
+ the future to allow arbitrary formats.
+
+ [targetFileExtension] The extension of the target output file.
+
+ [finalName] The final name of the output.
+
+ [stylesheetResource] URL to a custom style sheet. See {{{examples/custom-xslt.html}here}}
+ for examples of various URLs understood.
+
+ [imagePathSettingRequired] Does this format require the DocBook XSLT parameter
+ <img.src.path> to be set? Generally this is true only for output formats
+ which embed the images (i.e. PDF); HTML, for example, sets this to false.
+
+ [imageCopyingRequired] Does this format require copying of the image (and
+ css) resources to the format output directory? Generally, this and
+ the <imagePathSettingRequired> parameter should be mutually exclusive.
+ <Any situations where that is not the case?>
+
+ [doingChunking] Is this format performing chunking?
+
+ []
+
+ These {{{xref/org/jboss/maven/plugins/jdocbook/Format.html}Format}} values
+ are combined with the corresponding
+ {{{xref/org/jboss/maven/plugins/jdocbook/gen/util/StandardDocBookFormatSpecification.html}StandardDocBookFormatSpecification}}
+ values to determine the options used for that output format, with the
+ {{{xref/org/jboss/maven/plugins/jdocbook/Format.html}Format}} values given
+ precedence.
+
+* Minimal format configuragtion:
+
+ Here is a minimal configuration defining PFD and HTML output formats:
+
++----+
+<plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifacId>maven-jdocbook-plugin</artifactId>
+ <extensions>true</extensions>
+ <configuration>
+ <formats>
+ <format>
+ <formatName>pdf</formatName>
+ </format>
+ <format>
+ <formatName>html</formatName>
+ </format>
+ </formats>
+ </configuration>
+</plugin>
++----+
\ No newline at end of file
Modified: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/index.apt
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/index.apt 2007-07-07 19:02:56 UTC (rev 13215)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/index.apt 2007-07-07 19:46:15 UTC (rev 13216)
@@ -30,13 +30,12 @@
documentation, and to then render that single source into multiple formats
such as PDF or HTML.
- The purpose of the <jDocBook Plugin> is to allow these DocBook
- transformations to occur as a natural part of the users Maven build. The
- main difficulty with this has always been the fact that DocBook
- transformations are usually very closely tied to the user's local
- environment. The design goal with writing this plugin was to utilize Maven's
- dependency mechanism to bring all the pieces together on demand. Those
- pieces are:
+ The aim of the <jDocBook Plugin> is to allow these DocBook transformations
+ to occur as a natural part of the users Maven build. The main difficulty
+ with this has always been the fact that DocBook transformations were usually
+ very closely tied to the user's local environment. The design goal with
+ writing this plugin was to utilize Maven's dependency mechanism to bring
+ all the pieces together "on demand". Those pieces are:
[[1]] the DocBook distribution;
@@ -53,6 +52,13 @@
These are the ingredients that when mixed with the source file(s) and
stirred with an XSLT transformer produce the desired output(s).
+ XLST, fonts, images and css collectively define a "style". See the
+ maven-jdocbook-style-plugin for more information about the ability to
+ develop styles separately from the source documents. In fact a hope with
+ creating the jdocbook-style plugin in the first place is creation of
+ shareable styles reusable across many projects. {{{jdocbook-style.html}Here}}
+ is a discussion of using jdocbook-style bundles within jdobcook projects.
+
Currently, only SAXON is supported as the transformer factory. I have
had issues getting XALAN to work properly.
@@ -89,6 +95,12 @@
To provide you with better understanding of some usages of the <jDocBook Plugin>,
you can take a look at the following examples:
+ * {{{examples/jdocbook-style.html}Complete jdocbook-style example}}
+
+ * {{{examples/project-local-style.html}Using custom project-local images/css}}
+
+ * {{{examples/arbitrary-styles.html}Using arbutrary style images/css}}
+
* {{{examples/custom-xslt.html}Using custom XSLT}}
- * {{{examples/resource-staging.html}Staging resources}}
\ No newline at end of file
+ * {{{examples/docbook-version.html}Specifying DocBook version}}
\ No newline at end of file
Added: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/staging.apt
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/staging.apt (rev 0)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/staging.apt 2007-07-07 19:46:15 UTC (rev 13216)
@@ -0,0 +1,50 @@
+ ------
+ Staging
+ ------
+ Steve Ebersole
+ ------
+ 7 July 2007
+ ------
+
+~~ Copyright © 2007 Red Hat Middleware, LLC. All rights reserved.
+~~
+~~ This copyrighted material is made available to anyone wishing to use, modify,
+~~ copy, or redistribute it subject to the terms and conditions of the GNU
+~~ Lesser General Public License, v. 2.1. This program is distributed in the
+~~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied
+~~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+~~ Lesser General Public License for more details. You should have received a
+~~ copy of the GNU Lesser General Public License, v.2.1 along with this
+~~ distribution; if not, write to the Free Software Foundation, Inc.,
+~~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+~~
+~~ Red Hat Author(s): Steve Ebersole
+
+Staging
+
+ The <jDocBook Plugin> uses staging for handling of images, css and fonts in
+ a consistent manner. All of these resources might come from multiple sources
+ and DocBook, generally speaking, only allows defining a single path for
+ resources. To get around that, the <jDocBook Plugin> collects all those
+ resources together under a single staging directory. By default, this
+ is the <target/staging> directory, and each type of resource is under that.
+
+ In general there is not much to configure here, although you can point at alternate
+ source directories for css, fonts and images:
+
+
+ Or to an alternate location to use for staging:
+
++----+
+<plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifacId>maven-jdocbook-plugin</artifactId>
+ <extensions>true</extensions>
+ <configuration>
+ ...
+ <stagingDirectory>path/to/alternate/staging/dir</stagingDirectory>
+ </configuration>
+</plugin>
++----+
+
+ <todo : flesh this out, possibly with some examples of 'alternative staging'>
\ No newline at end of file
Copied: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/style.apt (from rev 13113, labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/docbook-support.apt)
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/style.apt (rev 0)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/style.apt 2007-07-07 19:46:15 UTC (rev 13216)
@@ -0,0 +1,94 @@
+ ------
+ Styles
+ ------
+ Steve Ebersole
+ ------
+ 2 July 2007
+ ------
+
+~~ Copyright © 2007 Red Hat Middleware, LLC. All rights reserved.
+~~
+~~ This copyrighted material is made available to anyone wishing to use, modify,
+~~ copy, or redistribute it subject to the terms and conditions of the GNU
+~~ Lesser General Public License, v. 2.1. This program is distributed in the
+~~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied
+~~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+~~ Lesser General Public License for more details. You should have received a
+~~ copy of the GNU Lesser General Public License, v.2.1 along with this
+~~ distribution; if not, write to the Free Software Foundation, Inc.,
+~~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+~~
+~~ Red Hat Author(s): Steve Ebersole
+
+Styles
+
+ Styles are composed of XSLT, images, css and fonts. These style components
+ may be pulled together from a number of different locations. Mainly, it is
+ intended that there are 2 main types of style components:
+
+ [jdocbook-style] - These are style components that are developed as part of
+ a separate project and packaged into a <jdocbook-style> artifact. The
+ intention is for these style bundles to be deployed into a Maven repo
+ and referenced just as a other project dependencies (with
+ type=jdocbook-style).
+
+ [project local] - These are style elements defined as part of the local
+ jdocbook project. Typically, these would either indicated either:
+
+ [[1]] overrides of some shared (ala, jdocbook-style) style element
+
+ [[2]] specific style elements of the local project (e.g. images
+ referred to from the project DocBook sources.
+
+ []
+
+ project local elements are generally limited to images, css, and fonts.
+
+ []
+
+* jdocbook-style integration
+
+ <todo : this section needs improving...>
+
+ <jdocbook-style> is another maven packaging type, defined by the
+ org.jboss.maven.plugins:maven-jdocbook-style-plugin plugin. The goal
+ of the <jdocbook-style> is to define a common, resuable packaging bundle
+ for DocBook style elements such as XSLT, images, fonts and css.
+ The <jDocBook Plugin> can take advantage of a <jdocbook-style> dependency
+ in two ways:
+
+ [[1]] Because
+
+ [[a]] dependencies are added to the classpath
+
+ [[b]] the <jDocBook Plugin> can locate XSLT via classpath resources (see {{{examples/custom-xslt.html} example}})
+
+ []
+
+ users can reference XSLT stylesheets from a <jdocbook-style> dependency
+ as a custom stylesheet (see the {{{usage.html}usage}} page).
+
+ [[2]] Given the {{{staging.html}staging}} approach taken by this plugin
+ for dealing with with resources (css, fonts and images) it automatically
+ stages any css, font or image resources found inside a dependency of
+ type <jdocbook-style>. See {{{examples/resource-staging.html}example}}.
+
+* Project local elements
+
+ <todo : this section need writing... ;)>
+
+ See {{staging.html}staging}}.
+
++----+
+<plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifacId>maven-jdocbook-plugin</artifactId>
+ <extensions>true</extensions>
+ <configuration>
+ ...
+ <imagesDirectory>path/to/alternate/image/dir</imagesDirectory>
+ <cssDirectory>path/to/alternate/css/dir</cssDirectory>
+ <fontsDirectory>path/to/alternate/fonts/dir</fontsDirectory>
+ </configuration>
+</plugin>
++----+
\ No newline at end of file
Modified: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/usage.apt
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/usage.apt 2007-07-07 19:02:56 UTC (rev 13215)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/apt/usage.apt 2007-07-07 19:46:15 UTC (rev 13216)
@@ -22,97 +22,38 @@
Usage
-* Formats
+ To understand usage of the <jDocBook Plugin>, there are really a few concepts
+ you must understand.
- Format is the term used to describe a particular output option for
- a DocBook transformation. For example, we might talk about the PDF
- output format, or the HTML output format.
+ [[1]] {{{formats.apt}Formats}} define the type of output(s) you wish to produce.
- * Supported formats
+ [[2]] {{{style.apt}Styles}} define how those format outputs should look.
- The <jDocBook Plugin> has support for most of the standard DocBook defined
- formats as (as of DocBook version 1.70.1 and later). For completeness,
- here is the full list of supported formats (as defined by the
- {{{xref/org/jboss/maven/plugins/jdocbook/gen/util/StandardDocBookFormatSpecification.html}StandardDocBookFormatSpecification}}
- class):
+ []
- * HTML-based
+ If you want to use local style element staging, it is also a good idea to
+ understand {{staging.html}staging}} as well.
- [eclipse] generates an eclipse documentation bundle
+* Minimal configuration
- [html] generates chunked HTML
+ The most basic cofiguration of the <jDocBook Plugin> is to simply tell it:
- [html_single] generated non-chunked HTML
+ [[1]] The DocBook soure file to be transformed
- [htmlhelp] generates HTMLHelp style documentation
+ [[2]] The formats into which the source should be transformed.
- [javahelp] generates JavaHelp style documentation
+ []
- [man] generates HTML-based *nix man pages
+ Here is a minimal configuration defining PFD and HTML output formats, for a
+ source file named source.xml:
- [website] generates a website (?)
-
- [xhtml] generates XHTML-compliant documentation
-
- []
-
- * FO-based
-
- [pdf] generates a PDF document
-
- []
-
- []
-
- * Configuring formats
-
- Configuration of formats occurs via the {{{xref/org/jboss/maven/plugins/jdocbook/Format.html}Format}}
- class. The list of configurable properties defined by the Format config
- class include:
-
- [formatName] This is the name of the output format. At least as of this
- moment, this <<must>> map to one of the standard DocBook formats
- detailed above; these values, then, simply act as overrides for the
- values defined by the standard DocBook formats. This may change in
- the future to allow arbitrary formats.
-
- [targetFileExtension] The extension of the target output file.
-
- [finalName] The final name of the output.
-
- [stylesheetResource] URL to a custom style sheet. See {{{examples/custom-xslt.html}here}}
- for examples of various URLs understood.
-
- [imagePathSettingRequired] Does this format require the DocBook XSLT parameter
- <img.src.path> to be set? Generally this is true only for output formats
- which embed the images (i.e. PDF); HTML, for example, sets this to false.
-
- [imageCopyingRequired] Does this format require copying of the image (and
- css) resources to the format output directory? Generally, this and
- the <imagePathSettingRequired> parameter should be mutually exclusive.
- <Any situations where that is not the case?>
-
- [doingChunking] Is this format performing chunking?
-
- []
-
- These {{{xref/org/jboss/maven/plugins/jdocbook/Format.html}Format}} values
- are combined with the corresponding
- {{{xref/org/jboss/maven/plugins/jdocbook/gen/util/StandardDocBookFormatSpecification.html}StandardDocBookFormatSpecification}}
- values to determine the options used for that output format, with the
- {{{xref/org/jboss/maven/plugins/jdocbook/Format.html}Format}} values given
- precedence.
-
- * Minimal format configuragtion:
-
- Here is a minimal configuration defining PFD and HTML output formats:
-
+----+
<plugin>
<groupId>org.jboss.maven.plugins</groupId>
<artifacId>maven-jdocbook-plugin</artifactId>
<extensions>true</extensions>
<configuration>
+ <sourceDocumentName>source.xml</sourceDocumentName>
<formats>
<format>
<formatName>pdf</formatName>
@@ -123,43 +64,4 @@
</formats>
</configuration>
</plugin>
-+----+
-
-* Staging
-
- The <jDocBook Plugin> uses staging for handling of images, css and fonts in
- a consistent manner. All of these resources miight come from multiple sources
- and DocBook, generally speaking, only allows defining a single path for
- resources. To get around that, the <jDocBook Plugin> collects all those
- resources together under a single staging directory. By default, this directory
- is <target/staging> directory, and each type of resource is under that. In
- general there is not much to configure here, although you can point at alternate
- source directories for css, fonts and images:
-
-+----+
-<plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifacId>maven-jdocbook-plugin</artifactId>
- <extensions>true</extensions>
- <configuration>
- ...
- <imagesDirectory>path/to/alternate/image/dir</imagesDirectory>
- <cssDirectory>path/to/alternate/css/dir</cssDirectory>
- <fontsDirectory>path/to/alternate/fonts/dir</fontsDirectory>
- </configuration>
-</plugin>
-+----+
-
- Or to an alternate location to use for staging:
-
-+----+
-<plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifacId>maven-jdocbook-plugin</artifactId>
- <extensions>true</extensions>
- <configuration>
- ...
- <stagingDirectory>path/to/alternate/staging/dir</stagingDirectory>
- </configuration>
-</plugin>
-+----+
++----+
\ No newline at end of file
Modified: labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/site.xml
===================================================================
--- labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/site.xml 2007-07-07 19:02:56 UTC (rev 13215)
+++ labs/jbossbuild/maven-plugins/trunk/maven-jdocbook-plugin/src/site/site.xml 2007-07-07 19:46:15 UTC (rev 13216)
@@ -27,12 +27,15 @@
<item name="Introduction" href="index.html"/>
<item name="Goals" href="plugin-info.html"/>
<item name="Usage" href="usage.html"/>
- <item name="docbook-support" href="docbook-support.html"/>
+ <item name="Style" href="style.html"/>
</menu>
<menu name="Examples">
+ <item name="Complete jdocbook-style Example" href="examples/jdocbook-style.html"/>
+ <item name="Project-local Style" href="examples/project-local-style.html"/>
+ <item name="Arbitrary Style" href="examples/arbitrary-styles.html"/>
<item name="Custom XSLT" href="examples/custom-xslt.html"/>
- <item name="Resource Staging" href="examples/resource-staging.html"/>
+ <item name="Using a Specific DocBook Version" href="examples/docbook-version.html"/>
</menu>
${reports}
More information about the jboss-svn-commits
mailing list