Documentation ToolsThis page is a summary of the tools available for the documentation community. Post new suggestions or comments on this forum: thread
Requirements
Text Editing and Processing
XML Editing Tools and InformationOverviewBooks 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 EditorThere 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 TransformationsDocuments 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
To Process the SolBook XML Files Into HTML Using the SolBook XSLT StylesheetsXSLT 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 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 CLISome 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.xmlInstructions for using the DocBook stylesheets are here: http://sagehill.net/docbookxsl/index.html. PDF TranformationsFor 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:
XML Authoring ToolsThere 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:
Some other lists are available here:
|