Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

DocumentationGuidelines/Publishing

Warning2.png
Draft Content
This page is currently under construction. Community members are encouraged to maintain the page, and make sure the information is accurate.


Target Formats

Since all content is stored within Eclipsepedia which use MediaWiki text format for structure and styling, it is recommended that projects leverage Mylyn WikiText for the publishing process. Mylyn WikiText allows for the export of mediawiki files into a variety of ouput formats. The sections that follow describe these formats and steps to produce the content in more detail.

Mylyn WikiText provides documentation describing how to generate various output formats. See the WikiText FAQ for details.

Eclipse Help

Mylyn WikiText can generate Eclipse Help directly from a MediaWiki. Improvements are being made to this process, see bug 299838. A working Ant build script used by the Mylyn project can be found here.

Some projects may choose to transform to formats such as DocBook or DITA as an intermediary step. This has the advantage of greater control over the output, with the disadvantage of complicating the build process.

DocBook

The following information comes from Authoring Eclipse Help Using DocBook page.

Introduction to DocBook

This page contains information about how to use DocBook for authoring Eclipse Help. If you are using DocBook in Eclipse and have questions, comments, etc., about integration, send a note to the WTP Incubator Dev List or contact me, David Carver.

DocBook is an XML format designed for technical documentation. This includes books, articles, and help. XSL Tools uses docbook for it's user documentation format. It allows the writer to focus on the content of the book, and not how it looks. This seperation of content from presentation allows the information to be presented in a wide variety of formats, including the Eclipse Help system.

More information about DocBook can be found at the following sites:

The DocBook Project

The DocBook Project provides a very popular and highly customizable set of DSSL and XSLT stylesheets for working with and generating DocBook content into a wide variety of formats. The project has been on going since 1999 and the most current version of the XSL Stylesheet are 1.74, June 2008. This project is continually being improved and patches applied. The stylesheets are free available for download. Note that it does make use of several other open source releated projects, so it may be necessary to check all licensing terms to make sure they meet your specific needs.

This HowTo will assume that the XSL Stylesheets are being used.

Getting Started

You'll need the following in your workspace:

  • The XSL Stylesheets from the DocBook Project. Create a Project for these and then import the ZIP file.
  • A plugin that will hold the end use documentation.
  • An ANT build script that will publish the documentation.
  • Xalan 2.7.1 or Saxon 6.5 installed for processing the XSL Stylesheets. Note: XSL Tools 0.5 includes Xalan 2.7.1.

Optional:

  • XSL Tools 0.5 or greater installed to allow for easy Launching and Testing of the process. XSL Tools also includes an XInclude ant task for helping to merge multiple docbook files into one complete package.

Creating the DocBook Files

It is recommended that Chapter 23: Modular DocBook Files be followed when creating eclipse help. There are several benefits for doing this:

  • Allows content to be re-arranged.
  • Allows for easier maintenance
  • Individual chapters can be previewed and worked on seperately from the main content.
  • Allows more than one person to work on a document.

The XSL Tools org.eclipse.wst.xsl.doc plugin can be viewed as an example.

Eclipse XSL Stylesheet

The Eclipse Platform Help System section in Chapter 25, outlines the basics of generating Eclipse Help with DocBook files. The stylesheet included with Docbook is designed for pre-eclipse 3.0. It uses some deprecated ways of generating the appropriate plugin.xml and toc.xml files need. The stylesheet below can be used with the one included by the DocBook Project to add eclipse 3.0 and greater support. 

<?xml version="1.0"?>
<!-- 
*******************************************************************************
 * Copyright (c) 2008 Standards for Technology in Automotive Retail and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     David Carver - STAR - Extended existing eclipse.xsl file to produce valid
 *                           eclipse 3.3 plugin.xml with a manifest file.
 *******************************************************************************/
 
 -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns:ng="http://docbook.org/docbook-ng" xmlns:db="http://docbook.org/ns/docbook"
	xmlns:exsl="http://exslt.org/common" version="1.0"
	exclude-result-prefixes="exsl db ng">
	<xsl:import href="eclipse.xsl"/>
	<xsl:param name="manifest">1</xsl:param>
	<xsl:param name="create.plugin.xml">1</xsl:param>

	<xsl:template name="plugin.xml">
	    <xsl:if test="$create.plugin.xml = '1'">
			<xsl:call-template name="write.chunk">
				<xsl:with-param name="filename">
					<xsl:if test="$manifest.in.base.dir != 0">
						<xsl:value-of select="$base.dir" />
					</xsl:if>
					<xsl:value-of select="'plugin.xml'" />
				</xsl:with-param>
				<xsl:with-param name="method" select="'xml'" />
				<xsl:with-param name="encoding" select="'utf-8'" />
				<xsl:with-param name="indent" select="'yes'" />
				<xsl:with-param name="content">
					<xsl:choose>
						<xsl:when test="$manifest = '1'">
						   <plugin>
								<extension point="org.eclipse.help.toc">
									<toc file="toc.xml" primary="true" />
								</extension>
				 		   </plugin>
						</xsl:when>
						<xsl:otherwise>
							<plugin name="{$eclipse.plugin.name}" id="{$eclipse.plugin.id}"
								version="1.0" provider-name="{$eclipse.plugin.provider}">
								<extension point="org.eclipse.help.toc">
									<toc file="toc.xml" primary="true" />
								</extension>
							</plugin>
						</xsl:otherwise>
					</xsl:choose>
				</xsl:with-param>
			</xsl:call-template>	    
	    </xsl:if>
	</xsl:template>
</xsl:stylesheet>

This stylesheet accepts two additional parameters:

  • manifest - The default value for this is 1, which means that it should generate a Manifest file for the documentation plugin. Set this to 0 to turn this feature off.
  • create.plugin.xml - The default value for this is 1, which means that the plugin.xml file should be generated and the appropriate toc.xml information added to it.

If you have created a plugin project already, and set up the initial toc.xml entry in the plugin.xml file, then you can turn this option off, and it will generate only the Toc.xml file that contains a link to the appropriate html entries.

ANT Build Script

As mentioned, you can use XSL Tools to help test individual chapters and see what they will look like. Do this by using the HTML stylesheets: docbook.xsl or chunk.xsl. It is recommended that the chunk.xsl stylesheets be used, and the base eclipse.xsl stylesheet imports this already. This splits the content into multiple html output files.

For generating the eclipse help plugin files, it is recommended to setup an ANT build script, and also use the XSL Tools xsl.xinclude ant task for merging the contents. The XSL Tools documentation generator build.xml looks like the following: 

<?xml version="1.0"?>
<project default="create-doc" basedir=".">

	<property name="current-loc" location="." />
	<property name="workspace" location=".." />
	<property name="htmldir" value="${current-loc}/html" />
	<property name="docbookdir" value="${workspace}/CommonUtilities/docbook-xsl/eclipse" />
	<property name="docbooksource" value="${current-loc}/docbook"/>
	<property name="xalan" value="org.apache.xalan.processor.TransformerFactoryImpl" />

    
	<!-- XSLT Chunking Properties -->
	<property name="base.dir" value="${htmldir}"/>
	
	<target name="merge">
		<xsl.xinclude in="${docbooksource}/xslhelp.dbk"
		              out="${docbooksource}/xslhelpcombined.dbk"
		/>
	</target>

	<target name="create-doc" depends="merge">

		<xslt force="true" style="${docbookdir}/eclipse33.xsl" in="${docbooksource}/xslhelpcombined.dbk" out="test.xml">
			<factory name="${xalan}" />
			<param name="manifest" expression="1"/>
			<param name="base.dir" expression="${htmldir}/"/>
			<param name="create.plugin.xml" expression="0"/>
			<param name="chunker.output.indent" expression="yes"/>
			<param name="navig.showtitles" expression="0"/>
			<param name="suppress.navigation" expression="1"/>
            <param name="generate.toc" expression="book      toc,title,figure
chapter   toc,title
section   title" />
		</xslt>
		
		<replace file="${current-loc}/toc.xml" token="${current-loc}/" value=""/>
	</target>

</project>

This script can be run independent of the workspace it was created and should be able to be run without change in a headless build. No system environment variables are used to gather information. The build script will output it's information into a directory called HTML in the current plugin. The only variables that may need to be updated are the $docbookdir and $docbooksource to indicate where the docbook files are stored.

The main processing is done in the create-doc, the xinclude resolutions are done in the merge target. It will generate table of contents for Book, Chapter, and Section elements. Running the build script will update the toc.xml in the plugin's root directory, and link automatically to the generated html documentation.

For more information about available parameters to be passed see:

CSS Doesn't Match Eclipse Style

The default stylesheet and formatting for the Eclipse Help generated by Docbook doesn't integrate well with the eclipse help system. Review Using CSS for more information on how to customize the look and feel.

DITA

The following sections come from Authoring Eclipse Help Using DITA.

Introduction to DITA

This page contains information about how to use DITA for authoring Eclipse Help. If you are using DITA in Eclipse and have questions, comments, etc., about integration, send a note to the WTP Dev List or contact me, Arthur Ryman.

DITA is an XML format designed especially for authoring Help information. Several WTP components have DITA-based Help, but up until know, the DITA source has not been checked into CVS. Instead the generated HTML has been checked in and privately kept in synch with the DITA source. The main reason for this cumbersome process is that the tools to process DITA have been proprietary.

DITA-OT

But all that has changed with the availability of the DITA Open Toolkit (DITA-OT) project at SourceForge. Now there is a freely available toolkit so anyone can author using DITA. The DITA Open Toolkit Home Page contains extensive documentation about DITA-OT, including notes on how to run the Ant scripts to build Help documentation.

Getting Started

You'll need to install DITA-OT on your development machine. DITA-OT1.2 does not work with Eclipse. You need DITA-OT1.2.1 which was released on April 5, 2006. Download the code from DITA-OT1.2.1, or some other mirror.

Unzip DITA-OT1.2.1_bin-ASL.zip to the root of your C: drive. This creates the directory c:/DITA-OT1.2.1. If you unzip the code to a different directory, you'll have to pass that in to the Ant build script as the property dita.ot.dir (see build.xml).

FYI, DITA-OT1.2.1 corrects a critical bug that prevented the scripts being run in Eclipse due to an Ant error. The critical bug is: 1431229 hardcoded path in MessageUtils.java.

DITA-OT requires an XML parser and XSLT engine. You can use Apache Xerces. If this is not included in the JRE you use to run Ant, you'll get a Class Not Found error. Either use a JRE that includes the required classes, or add the required classes to the classpath used by Ant.

Once DITA-OT and the required XML classes are installed, you can run the Ant build script. Do this after you edit the DITA source to generate the HTML pages. Perhaps one day the HTML generation will be automatic and incremental, just like the Eclipse JDT.

Initial DITA Contribution

The initial contribution to WTP of DITA Help source has been attached to bug 131837. This source and build scripts tailored to Eclipse have been commited to WTP CVS. These plugins have been released as tag v200604111302 and will be in the WTP 1.5 M6 build.

Some folks on the DITA-OT project have been asking for examples to illustrate the problems. All the code is in CVS. Here are the links to the five Help plugins we are startings with:

Here's the common plugin that contains the css, etc:

Next Steps

  • Add DITA build to WTP batch build
  • Delete generated HTML from CVS
  • Add support for multiple ditamaps per plugin
  • Add support for infopops

Problems Integrating DITA-OT into Eclipse

Here are my notes on integrating DITA-OT into Eclipse:

I've resolved as many of the problems as possible for now and have commited the DITA source and build scripts for the 5 plugins that Kate attached. Kate reviewed the generated HTML and corrected a few DITA markup errors. The initial contributions have been released as v200604111302.

There are a few outstanding problems:

Integration with releng Not Done Yet

The first stage is to have both the DITA source and the generated HTML and XML in CVS. I need to iron out the remaining problems before integrating the DITA builds into the releng builder.

When you edit the DITA source, run the build.xml Ant script to regenerate the HTML and XML.

Generated plugin.xml is Bad

The scripts generate bad plugin.xml files. I have therefore preserved the good copies as myplugin.xml. Our build script copies myplugin.xml over the generated plugin.xml, so make any edits to myplug.xml.

maplist Builds Not Supported

The scripts generate code from a *.ditamap file as input. However, the IBM contribution uses *.maplist files which list one or more *.ditamap files. Two plugins have two *.ditamap. To workaround this, please ensure that there is a "master" *.ditamap that pulls in all the *.dita files. We'll try to upgrade the scripts to support *.maplist files as input.

CSS Doesn't Match Eclipse Style

The *.css files that come with DITA-OT use a different style than Eclipse. They have been copied into the org.eclipse.wst.doc.user plugin. These *.css files, e.g. commonltr.css must be edited to give the correct style for Eclipse Help.

To fix this problem, copy the contents of common.css to the bottom of commonltr.css.

Sporatic "Access denied" Build Failure

I am hitting sporatic build failures while building modified DITA source files. I have reported this problem to the DITA-OT dev list. The problems occurred while I was connected to my LAN with an Ethernet cable but dissappeared when I was wireless!!!!!

Here's a snippet from my console in case anyone else sees the same behavior:


BUILD FAILED D:\workspaces\WTP-Dev\org.eclipse.jst.ws.doc.user\build.xml:45: The following error occurred while executing this line: C:\DITA-OT1.2.1\conductor.xml:83: The following error occurred while executing this line: C:\DITA-OT1.2.1\pretargets.xml:147: Failed to copy D:\workspaces\WTP-Dev\org.eclipse.jst.ws.doc.user\temp\org.eclipse.jst.ws.doc.user\concepts\csoap.dita.pull to D:\workspaces\WTP-Dev\org.eclipse.jst.ws.doc.user\temp\org.eclipse.jst.ws.doc.user\concepts\csoap.dita due to D:\workspaces\WTP-Dev\org.eclipse.jst.ws.doc.user\temp\org.eclipse.jst.ws.doc.user\concepts\csoap.dita (Access is denied)

I edited another file, i.e. not csoap.dita.

Other DITA solutions on Eclipse

While DITA is becoming more popular more and projects and solutions (both open source and commercial) are appearing on Eclipse platform supporting DITA. Herea re some examples:

  • DITA Open Platform - GPL project which goal is to provide an enterprise platform for the edition, management and processing of DITA documents.
  • DITAworks - eclipse based documentation infrastructure designed around DITA that enables modeling (DITA specialization), authoring, management and processing of DITA content. Easily integratable into any Eclipse project as documentation nature.
Retrieved from "https://wiki.eclipse.org/index.php?title=DocumentationGuidelines/Publishing&oldid=187464"

This page was last modified 14:06, 28 January 2010 by Eclipsepedia anonymous user Unnamed Poltroon.

Back to the top