Apache Derby: DITA-sourced documentation

Requirements:

• The binary download of the DITA Toolkit Version 1.1.2.1 from SourceForge. Use ONLY this version.

• Derby's DITA source files, Apache FOP, and the build.xml file used with ant to build the output. These can ALL be extracted at once using svn:

  svn checkout https://svn.apache.org/repos/asf/db/derby/docs/trunk/

  Note that the https is required (not http) if you will be committing changes.

• Apache Ant version 1.9.2 or later

• Any JDK at level Java 6 or later. Java's reference implementation is at http://www.oracle.com/technetwork/java/javase/downloads/index.html.
• Set up your subversion configuration file according to the ASF instructions. Apache provides an initial configuration file file that sets properties, such as line endings, for various file types (more information is in the 'Properties' section of the subversion documentation). Add these DITA file types to your configuration file:

  *.dita = svn:eol-style=native
  *.ditamap = svn:eol-style=native

• If you are working on Fedora, or on another platform where the system 'svn' executable uses LIBMAGIC, then you need to specify an alternate subversion/config file in your home directory to ensure that the svn eol style is correct when you are adding new files to subversion with svn add. On my Fedora system, this worked:

  *.dita = svn:mime-type=text/xml;svn:eol-style=native
  *.ditamap = svn:mime-type=text/xml;svn:eol-style=native
  

To set up your environment for creating output from DITA-source:

1. Install the JDK for Java 6 or later.

2. Extract the DITA source files, Apache FOP, and the build.xml file from svn using the command described above. We will call the extraction home directory %DOC_ROOT%/trunk. For example, after extracting, the Getting Started with Derby DITA files would be located in %DOC_ROOT%/trunk/src/getstart/.

3. Place the downloaded DITA-OT1.1.2.1_bin-ASL.zip file into the lib directory where you have checked out the DITA source files, %DOC_ROOT%/trunk/lib. The first time you build one of the manuals, Ant will extract the DITA Toolkit to the %DOC_ROOT%/trunk/ directory. After extraction, the DITA Toolkit files should be located in %DOC_ROOT%/trunk/DITA-OT1.1.2.1/.

4. Install Apache Ant, and make sure to follow the instructions for setting your environment variables.

   If you encounter problems with running out of memory on the doc build, set the ANT_OPTS environment variable to "-Xms100m -Xmx200m".

5. Modify your CLASSPATH to include the fop.jar, avalon-framework-cvs-20020806.jar, and batik.jar files located in %DOC_ROOT%/trunk/lib/ in your CLASSPATH environment variable.

The simpliest way to determine the name of the file that contains the information that you want to update is to:

1. Go to the Derby Documentation Overiew page.

2. Under the section Latest Alpha Manuals, click the link for the HTML Pages for the manual that contains the information that you want to update.

3. An outline of the manual topics appears on the left side of the screen. Use the outline to find the topic that you want to update.

4. In the outline, right-click on the topic name and choose properties. The name of the file is at the top of the dialog. The address (URL) contains the path and name of the file. For example, if the address contains http://db.apache.org/derby/docs/dev/getstart/cgsquck19524.html, the fliename for the topic that you want to update is cgsquck19524.dita

Guidelines for writing Derby information using DITA is on the Derby Documentation Writing Guidelines page.

To learn more about DITA, how to create or edit DITA files, and find more XML editors that support DITA, go to:

http://dita.xml.org/

DITA is an XML specification. You can edit DITA files in any text editor, but XML editors allow you to insert and modifiy tags easily while conforming to the DITA DTD and schemas. It is HIGHLY recommended that you use an XML editor to avoid errors in tagging.

There are many different XML editors available at various costs and some for no cost at all. Make sure to read the licenses for any XML editor you use to modify Derby DITA documentation. Some XML editors include:

• Arbortext Editor
• oXygen
• XML Buddy (an Eclipse plugin)
• Altova XML Spy

Guidelines for writing Derby information using DITA is on the Derby Documentation Writing Guidelines page.

To learn more about DITA, how to create or edit DITA files, and find more XML editors that support DITA, go to:

http://dita.xml.org/>

To create output from the DITA source files:

1. From a command line, navigate to %DOC_ROOT%/trunk/.
2. Enter the desired ant command on the command line using the following syntax:

   ant <output_type>.<manual_id>

   The <output_type> is the format of the output you wish to create. The options are HTML or PDF. The <manual_id> is the id of the manual that you want to output. The id is the same as the name of the directory containing that manual's DITA source files in %DOC_ROOT%/trunk/src/. A list of the ids are shown in the table below. For example, to create PDF output for the Getting Started with Derby guide, enter the following command:

   ant pdf.getstart

To create PDF or HTML output for ALL manuals at once, specify the output type with no manual. For example:

ant pdf

or

ant html

To create both formats for just one manual, enter the manual with no type. For example, the command shown below builds PDF and HTM for the Getting Started with Derby guide:

ant getstart

The output files will be built by the ant file and placed in the %DOC_ROOT%/trunk/out/ directory. If any of the software is not set up and configured correctly, the build will fail.

The following table lists the manual id's for each Derby manual:

Dita files are named to provide a sense of what type of topic they contain as well as to which manual they belong. All DITA topics are classified as either concepts, tasks, or reference material. Thus, every file begins with either a "c", "t", or "r". In addition, the letters that appear immediately after this first one provide a shorthand id for the manual. For example, the Getting Started with Derby manual uses "gs", so a reference topic DITA file in that manual will start with "rgs". Subsequent letters in the file name may provide hints at the topic's section within the manual, as well as numbers distinguishing it from other DITA files.

It is suggested that any new DITA files that you may add follow this naming scheme to maintain organization of the files.

You may wish to modify the output created by the DITA Toolkit to fix organization, formatting, links, indexing, etc. To do this, you will have to modify the xsl files distributed with the DITA Toolkit. The instructions for which files to modify and how are included within the Toolkit documentation. To modify the PDF output, it is recommended that you make changes only to the dita2fo_shell.xsl file.

You are invited to submit your modified xsl files to derby-dev. If you wish to use a modified xsl file, just replace the version of the file in the toolkit with the new one.

Contribution guidelines

If you would like to participate directly in any Derby development (including documentation changes), be sure to read the guidelines found here.

How to create a patch

1. Open a Jira issue under the documentation component for Derby, if one has not already been created for this issue. You will be posting your patch to the entry. You can also create a documentation subtask to an existing JIRA entry for code changes if your change is to reflect a bug fix, new feature, etc.
   

2. Sync up your local svn copy with any changes checked into the server:

        cd <my_derby_loc>/trunk
        svn update

3. Make your changes.

   • If you are adding a new file, add a topicref for the new file to the ditamap. You need to place the topicref in the ditamap exactly where you want the new topic to appear in the manual. You must also add the file using svn. The example below shows adding a file named cgsnewditafile.dita to the Getting Started Guide, using the command line:

         svn add src/getstart/cgsnewditafile.dita 
         

     If you are using TortoiseSVN, you can add the file to svn through Windows Explorer.

     
     

     After you add the file to the repository, it's important to set the end-of-line property for the file to native. This is because people making documentation contributions work on different operating systems. You can set this property explicitly with the command shown below:

     svn propset svn:eol-style native src/getstart/cgsnewditafile.dita 

     However, the easiest way to manage the svn:eol-style property is to automatically set end of line for common file types by adding the Apache dev list of files to your ~/.subversion/config file.

     
     

   • If you are deleting a file, remove the topicref from the ditamap and delete the file using svn. The example below shows deleting a file named rdevcsecure131.dita in the Developer's Guide using the command line:

         svn del src/devguide/rdevcsecure131.dita
         

     If you are using TortoiseSVN, you can delete the file through Windows Explorer.

     
     

4. Test your changes.

   • At the very least run ant html.<manual_id> and ant pdf.<manual_id> to create the HTML and PDF outputs for the book that you are changing.
   • Verify that the PDF docs were actually created. If they weren't created, doublecheck that the fop.jar, avalon-framework-cvs-20020806.jar, and batik.jar files are in your CLASSPATH.
   • Make sure no new errors or build failures result from your changes.
   • Check that the output looks correct.
   • This is the documentation that users will read, so please check your writing for spelling, grammar, and punctuation mistakes.
   
   

5. Make the patch.

   • Be sure to create the patch from the trunk/ directory.
   • Run "svn stat" to see a list of the files that have been modified, added, or deleted.
   • Specify the JIRA issue in the patch name.
   • If you think that there will be comments on your patch you should consider adding a number to the end of the patch name to making tracking subsequent patches easier.
   
   

   The following command creates a patch with all the diffs in your working copy.

       svn diff > derby2222.diff
       

   The following command simply adds "ref" to the patch name, to indicate that the patch contains updates to the Reference manual.

       svn diff > derby2222-ref.diff
       

   You can also create a patch with changes for just one book, as shown below:

       svn diff src/tuning > derby2222-tuning1.diff
       

6. Create a zip file of the HTML (and perhaps DITA) files

   It will be necessary for the community to review your changes, and the best way to do that is to see the HTML output that reflects your changes. Since you have already created HTML output when testing your changes, simply add the relevant HTML files to a zip file.

   If you are new to DITA, it is a good idea to include the DITA files in the zip file. This will give the community the opportunity to review the tagging that you used to ensure that consistent tagging is used in all Derby topics.

   
   

7. Attach the zip file to the appropriate JIRA entry.

   Include the following information with your attachment:

   • Which manuals are affected by your changes, and whether you tested them for successful building.
   • For a feature, bug fix, or large overhaul of the documentation, a description of the detailed functionality or reasons for the changes documented is essential.
   • If you added or deleted files, post the results from "svn stat" in the JIRA issue.

You must be a Derby committer to commit Derby patches.

1. Set up your environment (download required software, checkout Derby documentation source, set environment variables) as described in the Setting up your environment section.

   • Don't forget to update your subversion configuration file with these entries:

     *.dita = svn:eol-style=native
     *.ditamap = svn:eol-style=native

   • If you already have your environment setup, then you need to check out the Derby documentation source into a new directory and prepare your environment to generate output.
     
   • If you use windows, you need to use a cygwin window to apply and commit the patch. Download cygwin from the cygwin Web site. When you open a cygwin window, you must use a FORWARD slash to change to a directory. For example:

          $ cd c:/authoring/derby/commits 

2. The instructions in the Submitting documentation patches section tell contributors to create patches at the trunk level, so download the patch to the trunk of your working copy.
   
   

3. Apply the patch using the GNU patch command:

   patch -p0 < patchname.diff

4. Check modifications with the svn status command and add or delete any files as necessary. Follow the instuctions to add or delete files.
   
5. Follow the instructions in the Creating output section to verify the doc build succeeds.
   
   
6. Commit the changes using the svn commit command.

   Please include the following information in the log message:

   • DERBY Jira issue.
   • Description of the change.
   • Name of the patch contributor if you didn't author this change.

   Sample commit syntax is shown below for changes made to the Developer's guide:

   
   svn commit --message "DERBY-1622: Add documentation for encrypting databases 
   using encryptionKey connection attribute. The patch derby1622-3.diff was
   contributed by Robin Williams." src/devguide
   
   svn commit --file /tmp/derby-1622.txt src/devguide
   

   The --message argument lets you enter the log message on the command line, and the --file argument lets you set the log message from a file.
   
   
7. Update the JIRA issue.

   Copy the statement that is returned when you commit the patch (for example: Committed revision 513081) and paste it into a comment in the JIRA issue. If the patch resolves the issue, mark the issue as resolved and remove the check from "Patch Available".