WYSIWYG DocBook Editor?

Those of you out there writing DocBook, especially those who do not do a lot of DocBook editing, what open source WYSIWYG DocBook editors do you use?

What DocBook authoring tools to you recommend to folks just getting started with DocBook? For example, what would you recommend for a software developer or architect who has not necessarily worked with a lot of non-WYSIWYG authoring tools? The DocBook authoring tools Wiki page seems to have been lost.

Supported solutions do exist, such as Syntext Serna, XMLmind, and Oxygen XML Editor. What about open source authoring tools, though? Perhaps you have set up XWiki with Wikbook.

Thanks for your suggestions.

ForgeRock: Case Study & White Paper templates

Core documentation rarely covers everything you want and need to know about building a solution. Core documentation can get you going on your laptop or in the lab. Yet, if your project is big or ambitious, you no doubt want to work with an expert partner who can help you take the project from idea to deployment.

Short case studies and white papers can help you get a feel for what a partner knows, and where the partner’s specific expertise lies. A short case study or white paper can be fairly quick for a partner to write after a successful implementation.

Of course to finish you have to get started. Sometimes technical experts who are great in their area feel challenged when presented with the blank wiki or word processor page. Therefore I have posted a draft How To on getting started with a case study or white paper, including proposed outlines for both.

Hope some of you find it useful. Feel free to login and change the content where you see room for improvement.

Right size examples?

Nothing illustrates a point as well as a good example. Sometimes even a mediocre example illustrates a point better than several paragraphs of text.

Trouble comes when the example is not complete enough to test automatically. One change in naming can make the code silently out of date.

Trouble also arises when the example is so realistic that an untrained eye cannot determine which trees are important in the forest of information.

The example above is too short to compile, but still full of extra information that could distract a reader from the essential points of getting a connection from the factory, binding as Babs Jensen, and finally closing the connection.

How have you solved this problem in your docs?

OpenDJ: LDAP API, Tools, and Examples

Late Thursday and early this morning Matt updated the OpenDJ community site to bring you links and descriptions, and explanations about the OpenDJ LDAP SDK.

The LDAP SDK, slated to become officially available in version 2.5, includes a modern Java API for LDAPv3, command-line tools for measuring performance and carrying out LDAP operations, and examples that demonstrate how to use the API.

Let us know how you are getting along with the SDK on the OpenDJ mailing list.

OpenDJ SDK: man pages

The network was down when I arrived at the office Tuesday morning. So I started filling in some man pages to fix a bug that Matt had opened.

After filling in the pages quickly and cobbling together some examples, I had a look (e.g. cd opendj3; mvn pre-site; man -M man -M  target/docbkx/manpages/dev-guide/OpenDJ-Dev-Guide/ modrate). I am pleasantly surprised by how well the DocBook XSL stylesheets lay out the pages in .roff and in HTML. The PDF needs work, though, probably some customizations. (Is the default termlength for a variablelist really 24 characters?)

So far the pages are not packaged into the build. Here’s a .zip of the 7 pages I did Tuesday.

The Examples sections are minimal so far. Should break tradition and put the Examples section near the top of the pages rather than at the end? Does anybody out there actually use man pages any more?

Core Documentation Author’s Guide

More core docs outlines are taking shape. I had not taken time out, however, to explain how to help write the content.

My first stab at a Core Documentation Author’s Guide can be found on the Developer Community Wiki.

The guide touches on getting started, contributing docs to a project, and finding and fixing doc bugs. There is also a section on starting your own doc project. I am not sure what I left out. If you are starting from scratch, let me know so I can show you what I have found so far.

As I wrote Monday, “Feel free to improve this guide.”

OpenAM: New Community Site

The OpenAM community site is now live at http://openam.forgerock.org/, alongside the OpenICF and OpenDJ community sites.

The sources for the OpenAM site are are visible under http://sources.forgerock.org/changelog/openam/trunk/opensso/openam-site/. If you have commit rights to the subversion repository, you can participate in updating and improving the site. I do not think there is a cron job yet to rebuild the site automatically when the sources are updated, but that should come. In the meantime no doubt somebody on the Dev list can push out an update.

All of the previous OpenAM web locations remain in place. If you were going to the wiki through openam.forgerock.org, however, update your bookmark to point to https://wikis.forgerock.org/confluence/display/openam/Home.

Docbkx-tools 2.0.13 available

Docbkx-tools 2.0.13 is out. I have been using 2.0.13-SNAPSHOT since shortly after the 2.0.12 release. Works well for me. Thanks to Cedric for making this release available.

Time to update your pom.xml file.

<plugin>
    <groupId>com.agilejava.docbkx</groupId>
    <artifactId>docbkx-maven-plugin</artifactId>
    <version>2.0.13</version>
    ...
</plugin>

A stable 2.0.13 means you no longer have manually to get the source from svn and then run mvn install. Co-authors who just want to write and not to mess with a local version of docbkx-tools will be happy you moved to the stable version.

Docbkx-tools, DocBook 5 XML, and Google Analytics

Today I feel dirty for two reasons. I feel dirty on the outside because I rode hard on the bike at lunchtime and we have no showers at the office, yet. I feel dirty on the inside because I found a solution to add Google Analytics code into HTML generated from DocBook 5 XML with docbkx-tools, but the solution is sort of an ugly hack.

Using the maven-antrun-plugin, I added another task for Ant.

<replace dir='${basedir}/target/docbkx/html/' token='&lt;/body&gt;'>
  <include name='**/**/*.html' />
  <replacevalue>&lt;script type="text/javascript"&gt;
    var _gaq = _gaq || [];
    _gaq.push(['_setAccount', 'UA-########-#']);
    _gaq.push(['_trackPageview']);
    (function() {
      var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
      ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
      var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
    })();
  &lt;/script&gt;&lt;/body&gt;</replacevalue>
</replace>

I would put that in a separate .xsl for HTML customizations, but I cannot find an appropriate parameter. I’m not chunking documents, so user.footer.content does not get used.

I tried going the external code file route, but either I get the <script> in the HTML and the FO (PDF, RTF) generation breaks, or I get <script> in the HTML (with parse="text").

Leave me a comment if you have solved this more elegantly.

OpenDJ: New Community Site

Yesterday the new OpenDJ community site went live at http://opendj.forgerock.org/, a few days after the OpenICF community site last week.

Community sites build as Maven site goals inside the projects, meaning that your contributions get rolled in as part of the normal site build process. To include the in-progress core docs, I added a copy-resources goal to the opendj-docs POM that puts all the HTML, EPUB, PDF, and RTF under the parent site content in a doc directory. Yet for most modules you can add a module-level site and then a link from the parent site.xml.

Maven supports site localization by keeping files side by side. Basically you put a localized copy of the site files under /code below the default site, where code is a language code such as fr or jp. I left copies of the Maven site archetype files for the French version under http://opendj.forgerock.org/fr as a reminder and an example. As we get more on the community sites, it would definitely be nice to have more languages than English. (The same is true of the core docs, by the way.)