OpenSolaris

Documentation Tools

 This page is a summary of the tools available for the documentation community. Post new suggestions or comments on this forum: thread

Requirements

• Use free documentation tools.
• Can be updated by either vi or emacs.
• Have standard templates for documentation.

Text Editing and Processing

• Asciidoc: http://www.methods.co.nz/asciidoc/
   ASCIIdoc is an extensive Python script that takes simple text files and converts them into other formats. By default, it will create an HTML file. Formatting rules for the text file are fairly straight-forward. The Quick-Start Guide is here.

XML Editing Tools and Information

Overview

Books in the Docs Consolidation are formatted as SolBook XML. SolBook is a fully-conforming subset of the DocBook document schema used to describe the content of technical books. Use the Download icon in the upper right of this page to find the Documentation Consolidation source files. Any modifications or additions to these books should also be compliant with the SolBook XML standard.

 Any XML authoring tool which is capable of validating against the SolBook XML standard may be used for authoring.

XMLmind Editor

There is an add-on for the XMLmind XML editor which allows SolBook XML documents to be easily created and edited. More information on how to obtain and install this can be found here.

HTML Transformations

Documents in an XML format are great for editing, but for viewing it is best to convert the documents to HTML. You can send your new or updated files to the mailing list and we'll generate HTML with OpenSolaris branding for you, if you prefer. There are also publicly available XSLT stylesheets for converting SolBook XML documents into HTML (and also into PDF and other formats).

To Process the SolBook XML into HTML Using the DocBook XSLT Stylesheets

1. Download the latest XSLT stylesheets for converting DocBook-compliant XML documents into HTML (and also into PDF and other formats). Detailed instructions for use are here: http://www.sagehill.net/docbookxsl//.
2. Unpack the XSLT files and note down the directory where ..html/docbook.xsl is located:

 gzip -d docbook-xsl-1.70.0.tar.gz

 tar xvf docbook-xsl-1.70.0.tar

 The files are expanded into directories.

1. Process the XML into HTML by running the following command:

% xsltproc ~--nonet ~--xinclude -o mysolbookfile.html //docbook///html/docbook.xsl mysolbookfile.xml

Note: Replace the docbook- directory in the above command with the one noted in the previous step.
 The mysolbookfile.html file appears in the current directory.

 A sample style sheet to format the resulting HTML documentation is available for your use.

To Process the SolBook XML Files Into HTML Using the SolBook XSLT Stylesheets

XSLT stylesheets are now available which can transform SolBook 3.5 XML documents into 2 styles of HTML. In addition, they can also be used to convert SolBook 3.5 XML into 3 versions of DocBook XML (v. 4.0, 4.4, and 5.0b).

The easiest way to use these stylesheets is to download and use the SolBookTrans Java tool (see Related Links). It is a very small simple tool for running transformations. It requires Java 1.6 to run. It can be run from the command line or from a simple GUI. Just download the zip file, open it anywhere on your system, and view the README within the zip root for instructions on how to use it.

An upcoming NetBeans plugin for SolBook will also include these same stylesheets. This plugin should be available later in July 2008.

Related Links

• SolbookTrans zip file
• SolBookTrans source

 A variety of other tools are available for performing these transformations, but note that the DocBook XSLT stylesheets are very large and complex and will not work with all authoring tools.

Validation Using the CLI

 Some guidelines for performing validations using the CLI and some suggested alternate tools are provided here.

The process of making sure that a given XML document is compliant with the DTD standard is called validation. Validation is done by using automated tools to compare the contents of the XML document with another file which encodes the structure.

 The way most XML tools work is that you open the document you want to validate in the tool, and then use the Validate function of the tool. The validate function will typically identify the errors which made the document invalid.

The xmllint tool (which should be included in OpenSolaris-based OS distributions in /usr/bin) can also be used for validation:

xmllint ~--valid ~--noout mysolbookfile.xml

 Instructions for using the DocBook stylesheets are here: http://www.sagehill.net/docbookxsl/.

PDF Tranformations

 For information about Docbook and apache FOP, refer to the blog of Ben Rockwood:

http://cuddletech.com/blog/pivot/entry.php?id=509 General information about DocBook XML can be obtained from the following links:

• High level overview, DTDs, and schemas: http://docbook.org/
• XSLT stylesheets, tools: http://docbook.sourceforge.net/
• Publishing guidelines: http://sagehill.net/docbookxsl/index.html

• DocBook XSL stylesheets http://sourceforge.net/project/showfiles.php?group_id=21935#files
• FOP for PDF generation http://xmlgraphics.apache.org/fop/download.html#binary

XML Authoring Tools

There are many XML tools available for authoring, validating, and applying stylesheets to XML documents. The following list is a short list of those which meet the following minimum criteria:

• Must validate the XML document against a DTD or schema
• Must automatically complete tags
• Multi-platform capable (typically Java), if you are not on Windows

Some other lists are available here:

• http://www.xml.com/pub/rg/XML_Editors
• http://www.google.com/search?hl=en&q=XML+editors&btnG=Google+Search.
• http://ahds.ac.uk/creating/information-papers/xml-editors