Wiki code for Documentation Tools

Hide Line numbers
1: == Documentation Tools
2: 
3:  This page is a summary of the tools available for the documentation community. Post new suggestions or comments on this forum: [[thread>>http://www.opensolaris.org/jive/thread.jspa?threadID=1698&tstart=45]]
4: 
5: === Requirements
6: 
7: * Use free documentation tools.
8: * Can be updated by either vi or emacs.
9: * Have standard templates for documentation.
10: 
11: == Text Editing and Processing
12: 
13: * Asciidoc: [[http://www.methods.co.nz/asciidoc/>>http://www.methods.co.nz/asciidoc/]]
14:  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>>Community Group documentation.asciidocqsg]].
15: 
16: == XML Editing Tools and Information
17: 
18: === Overview
19: 
20: 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.
21: 
22:  Any XML authoring tool which is capable of validating against the SolBook XML standard may be used for authoring.
23: 
24: === XMLmind Editor
25: 
26: 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>>Community Group documentation.xmlmind_solbook_addon]].
27: 
28: === HTML Transformations
29: 
30: 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).
31: 
32: === To Process the SolBook XML into HTML Using the DocBook XSLT Stylesheets
33: 
34: 1. Download the latest XSLT [[stylesheets>>http://prdownloads.sourceforge.net/docbook/docbook-xsl-1.70.0.tar.gz?download]] 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//>>http://www.sagehill.net/docbookxsl//]].
35: 1. Unpack the XSLT files and note down the directory where ..html/docbook.xsl is located:
36: 
37: {{{
38:  gzip -d docbook-xsl-1.70.0.tar.gz
39: }}}
40: 
41: {{{
42:  tar xvf docbook-xsl-1.70.0.tar
43: }}}
44: 
45:  The files are expanded into directories.
46: 1. Process the XML into HTML by running the following command:
47: 
48: {{{
49: % xsltproc ~--nonet ~--xinclude -o mysolbookfile.html //docbook///html/docbook.xsl mysolbookfile.xml
50: }}}
51: 
52: **Note:** Replace the //docbook-// directory in the above command with the one noted in the previous step.
53:  The mysolbookfile.html file appears in the current directory.
54: 
55:  A [[sample style sheet>>attach:format.css.txt]] to format the resulting HTML documentation is available for your use.
56: 
57: === To Process the SolBook XML Files Into HTML Using the SolBook XSLT Stylesheets
58: 
59: 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).
60: 
61: 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.
62: 
63: An upcoming NetBeans plugin for SolBook will also include these same stylesheets. This plugin should be available later in July 2008.
64: 
65: **Related Links**
66: 
67: * [[SolbookTrans zip file>>attach:SolBookTransPkg.zip]]
68: * [[SolBookTrans source>>attach:SolBookTrans.zip]]
69: 
70: ----
71: 
72:  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.
73: 
74: === Validation Using the CLI
75: 
76:  Some guidelines for performing validations using the CLI and some suggested alternate tools are provided here.
77: 
78: 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.
79: 
80:  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.
81: 
82: The xmllint tool (which should be included in OpenSolaris-based OS distributions in /usr/bin) can also be used for validation:
83: 
84: {{{
85: 
86: xmllint ~--valid ~--noout mysolbookfile.xml
87: 
88: }}}
89: 
90:  Instructions for using the DocBook stylesheets are here: [[http://www.sagehill.net/docbookxsl/>>http://www.sagehill.net/docbookxsl/]].
91: 
92: === PDF Tranformations
93: 
94:  For information about Docbook and apache FOP, refer to the blog of Ben Rockwood:
95: 
96: [[http://cuddletech.com/blog/pivot/entry.php?id=509>>http://cuddletech.com/blog/pivot/entry.php?id=509]] General information about DocBook XML can be obtained from the following links:
97: 
98: * High level overview, DTDs, and schemas: [[http://docbook.org/>>http://docbook.org/]]
99: * XSLT stylesheets, tools: [[http://docbook.sourceforge.net/>>http://docbook.sourceforge.net/]]
100: * Publishing guidelines: [[http://sagehill.net/docbookxsl/index.html>>http://sagehill.net/docbookxsl/index.html]]
101: 
102: * DocBook XSL stylesheets [[http://sourceforge.net/project/showfiles.php?group_id=21935#files>>http://sourceforge.net/project/showfiles.php?group_id=21935#files]]
103: * FOP for PDF generation [[http://xmlgraphics.apache.org/fop/download.html#binary>>http://xmlgraphics.apache.org/fop/download.html#binary]]
104: 
105: === XML Authoring Tools
106: 
107: 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:
108: 
109: * Must validate the XML document against a DTD or schema
110: * Must automatically complete tags
111: * Multi-platform capable (typically Java), if you are not on Windows
112: 
113: Some other lists are available here:
114: 
115: * [[http://www.xml.com/pub/rg/XML_Editors>>http://www.xml.com/pub/rg/XML_Editors]]
116: * [[http://www.google.com/search?hl=en&q=XML+editors&btnG=Google+Search>>http://www.google.com/search?hl=en&q=XML%2Beditors&btnG=Google%2BSearch]].
117: * [[http://ahds.ac.uk/creating/information-papers/xml-editors>>http://ahds.ac.uk/creating/information-papers/xml-editors]]
118: 
119: 
120: 
121: {{velocity}}
122: {{html}}
123: 
124: <br/>
125: <table width="75%" border="1">
126:   <caption><b>Short List of Free or Cheap Multi-platform XML Editors</b></caption>
127:   <tr align="left" valign="top"> 
128:     <th width="12%">Tool Name</th>
129:     <th width="13%">Platform Support</th>
130:     <th width="15%">Cost</th>
131:     <th width="30%">Notable Features</th>
132:     <th width="30%">Missing Features</th>
133:   </tr>
134:   <tr align="left" valign="top"> 
135:     <td width="12%"><a href="http://www.netbeans.org" target="_blank">NetBeans</a></td>
136:     <td width="13%">All Java enabled platforms</td>
137:     <td width="15%">Free - open source</td>
138:     <td width="30%"> 
139:       <ul>
140:         <li>Primarly for code editing</li>
141:         <li>Tag-completion</li>
142:         <li>DTD validation</li>
143:         <li>simple XSLT processing</li>
144:       </ul>
145:     </td>
146:     <td width="30%"> 
147:       <ul>
148:         <li>No XInclude support</li>
149:         <li>Will not process complex (i.e. DocBook) XSLT stylesheets</li>
150:         <li>No RelaxNG validation</li>
151:         <li>Inconsistent valid tag list when authoring</li>
152:       </ul>
153:     </td>
154:   </tr>
155:   <tr align="left" valign="top"> 
156:     <td width="12%"><a href="http://www.jedit.org" target="_blank">JEdit</a></td>
157:     <td width="13%">All Java enabled platforms</td>
158:     <td width="15%">Free - open source</td>
159:     <td width="30%"> 
160:       <ul>
161:         <li>Primarly for code editing</li>
162:         <li>Tag-completion</li>
163:         <li>DTD validation</li>
164:         <li>Schema validation</li>
165:       </ul>
166:     </td>
167:     <td width="30%"> 
168:       <ul>
169:         <li>No XInclude support</li>
170:         <li>Will not process complex (i.e. DocBook) XSLT stylesheets</li>
171:         <li>No RelaxNG validation</li>
172:         <li>No valid tag list when authoring</li>
173:       </ul>
174:     </td>
175:   </tr>
176:   <tr align="left" valign="top"> 
177:     <td width="12%"> 
178:       <p><a href="http://www.openoffice.org" target="_blank">OpenOffice 8</a></p>
179:     </td>
180:     <td width="13%">Not Java, but available on all major platforms</td>
181:     <td width="15%">Free - open source</td>
182:     <td width="30%">Not an XML authoring tool, but can be used with another tool 
183:       which will convert OpenOffice documents into DocBook (<a href="#openoffice">see 
184:       below</a>)</td>
185:     <td width="30%">&nbsp;</td>
186:   </tr>
187:   <tr align="left" valign="top"> 
188:     <td width="12%"><a href="http://www.oxygenxml.com" target="_blank">oXygen</a></td>
189:     <td width="13%">All Java enabled platforms</td>
190:     <td width="15%"> 
191:       <p>Proprietary<br>
192:         - 30 day trial<br>
193:         - $180 license</p>
194:     </td>
195:     <td width="30%"> 
196:       <ul>
197:         <li>Tag-completion</li>
198:         <li>DTD validation</li>
199:         <li>Schema validation</li>
200:         <li>RelaxNG validation</li>
201:         <li>XInclude support</li>
202:         <li>Intuitive authoring views</li>
203:         <li>Valid tag list for authoring</li>
204:         <li>Built in DocBook functionality</li>
205:         <li>Complex XSLT processing</li>
206:       </ul>
207:     </td>
208:     <td width="30%"> 
209:       <ul>
210:         <li>Not free</li>
211:       </ul>
212:     </td>
213:   </tr>
214:   <tr align="left" valign="top"> 
215:     <td width="12%"><a href="http://www.tei-c.org/Software/tei-emacs/" target="_blank">emacs</a></td>
216:     <td width="13%">Not Java, but available on Windows, Linux, and Unix</td>
217:     <td width="15%">free</td>
218:     <td width="30%">(have not tested)</td>
219:     <td width="30%">(have not tested)</td>
220:   </tr>
221:   <tr align="left" valign="top"> 
222:     <td width="12%"><a href="http://www.vervet.com/xmlpro.php" target="_blank">XML 
223:       Pro v2</a></td>
224:     <td width="13%">All Java enabled platforms</td>
225:     <td width="15%">Open source, but still requires a small license fee for commerical 
226:       use </td>
227:     <td width="30%">(have not tested)</td>
228:     <td width="30%">(have not tested)</td>
229:   </tr>
230:   <tr align="left" valign="top"> 
231:     <td width="12%"><a href="http://www.editix.com" target="_blank">EditiX</a></td>
232:     <td width="13%">All Java enabled platforms</td>
233:     <td width="15%"> 
234:       <p>Proprietary<br>
235:         - 30 day trial<br>
236:         - $85 license</p>
237:     </td>
238:     <td width="30%">(have not tested)</td>
239:     <td width="30%">(have not tested)</td>
240:   </tr>
241:   <tr align="left" valign="top"> 
242:     <td width="12%"><a href="http://www.xmlobjective.com" target="_blank">XML 
243:       objective</a></td>
244:     <td width="13%">All Java enabled platforms</td>
245:     <td width="15%">Proprietary<br>
246:       - 15 day trial<br>
247:       - $40 license<br>
248:     </td>
249:     <td width="30%">(have not tested)</td>
250:     <td width="30%">(have not tested)</td>
251:   </tr>
252:   <tr align="left" valign="top"> 
253:     <td width="12%"><a href="http://www.exchangerxml.com" target="_blank">Exchanger</a></td>
254:     <td width="13%">All Java enabled platforms</td>
255:     <td width="15%">Proprietary<br>
256:       - 30 day trial<br>
257:       - $130 license</td>
258:     <td width="30%">(have not tested)</td>
259:     <td width="30%">(have not tested)</td>
260:   </tr>
261: </table>
262: {{/html}}
263: {{/velocity}}
OpenSolaris

Top Menu

Wiki code for Documentation Tools

Search

Collectives

Community Group

Project

User Group

Subsites

Community Group documentation Pages
