JCite and DocBook Together

Peter Arrenbrecht‘s JCite – Java Source Code Citation System – looks like something we could use to keep our DocBook-based developer documentation in sync with Java examples.DocBook Colophon

One of JCite’s strengths is in generating HTML content with <span>s for syntax highlighting. Yet, JCite also supports “plain” citations, pulling in content without extra markup, instead only escaping special characters like <, >, and &.

I tried it with a small sample DocBook <chapter>, chap-jcite.xml. That chapter uses JCite to cite Java code from a Test class. (Sorry, no, I haven’t yet worked out how to plug JCite for DocBook into WordPress.)

 <para>The following example cites an entire Java class.</para>

 <programlisting language="java"
 >[jcp:org.forgerock.doc.jcite.test.Test]</programlisting>

 <para>The following example cites a single Java method.</para>

 <programlisting language="java"
 >[jcp:org.forgerock.doc.jcite.test.Test:--- mainMethod]</programlisting>

When the file is processed, the output contains cited code from Test.java

 <programlisting language="java"
 >package org.forgerock.doc.jcite.test;

/**
 * Test class for trying JCite.
 */
public final class Test {
    /**
     * Print a message, then print args one per line.
     * @param args Program arguments.
     */
  // --- mainMethod
    public static void main(final String[] args) {
        System.out.println(&quot;This is just a test.&quot;);
        for (String arg : args) {
            System.out.println(&quot;\t&quot; + arg);
        }
    }
  // --- mainMethod
}</programlisting>

 <para>The following example cites a single Java method.</para>

 <programlisting language="java"
 >public static void main(final String[] args) {
    System.out.println(&quot;This is just a test.&quot;);
    for (String arg : args) {
        System.out.println(&quot;\t&quot; + arg);
    }
}</programlisting>

Pretty nifty. The ForgeRock doc build plugin gets syntax highlighting elsewhere, so in principle this should work for ForgeRock docs.

Where’s the JCite Maven plugin?

Advertisements

3 thoughts on “JCite and DocBook Together

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s