AurigaDoc: User Guide


Author: Khurshidali Shaikh

Company: Auriga Logic

Revision: $Revision: 1.34 $

Last Modified: $Date: 2003/11/06 10:18:41 $


AurigaDoc AurigaDoc: User Guide

Table of Contents
1. What Is AurigaDoc
2. Output Formats
3. Installation
3.1. Installation On Windows
3.2. Installation On Unix
4. Usage
4.1. Using From Command Line
4.2. Using From Java
4.3. Using From Ant Target
4.4. Using AurigaDoc Ant Task
5. AurigaDoc Documentation Conventions
6. CSS (Cascading Style Sheet) Support
7. Change History
7.1. Version 1.3
7.2. Version 1.3b
7.3. Version 1.2
7.4. Version 1.2b
7.5. Version 1.1
8. Limitations
9. Troubleshooting
10. License

1. What Is AurigaDoc
AurigaDoc is a java-xml-xsl based documentation tool for writing xml documents and converting them to other formats like HTML(single and multi-page), DHTML(frame based html with a toc tree), RTF(Microsoft Word 97 and above), PDF, Postscript, Java Help and HTML Help.

The idea is to keep a single document source(as xml) and convert it to various formats formats using XSLT.

While converting the xml to html you have the option of either creating a single html file for the entire document or multiple html files where each file contains a single section in the document with links to other sections.

Since xml is becoming a standard documents written in xml are portable to various formats.

AurigaDoc is built using open source software like

2. Output Formats
AurigaDoc supports the following output formats.

3. Installation
To install aurigadoc follow the install instructions for the platform you are using:-

3.1. Installation On Windows
3.2. Installation On Unix

3.1. Installation On Windows
To install aurigadoc on windows follow the given steps:-
  1. Untar the aurigadoc distribution to a directory.
    This will create a folder aurigadoc

  2. Set the AURIGADOC_HOME environment variable to the absolute path of the aurigadoc directory created above.

  3. Add aurigadoc/bin directory to the PATH environment variable.

  4. Open aurigadoc/bin/aurigadoc.properties in a text editor and set the aurigadoc.home property to the absolute path of the aurigadoc directory created above.
    Note: Use double slashes in the path like this
    aurigadoc.home=c:\\software\\aurigadoc


  5. If you need to compile HTML Help Files automatically, install HTML Help Workshop from Microsoft's site and set the value of chm_compiler.path to the absolute path of the HTML Help Compiler(hhc.exe).
    Note: Use double slashes in the path like this
    chm_compiler.path=c:\\Program Files\\HTML Help Workshop\\hhc.exe



3.2. Installation On Unix
To install aurigadoc on windows follow the given steps:-
  1. Untar the aurigadoc distribution to a directory.
    tar -xvzf aurigadoc.tar.gz
    This will create a folder aurigadoc

  2. Set the AURIGADOC_HOME environment variable to the absolute path of the aurigadoc directory created above.

  3. Add aurigadoc/bin directory to the PATH environment variable.

  4. Open aurigadoc/bin/aurigadoc.properties in a text editor and set the aurigadoc.home property to the absolute path of the aurigadoc directory created above.


4. Usage
AurigaDoc has been modified to provide multiple interfaces to the converter. The AurigaDoc converter can be called both from the command line as well as from a java class depending on your needs.

4.1. Using From Command Line
4.2. Using From Java
4.3. Using From Ant Target
4.4. Using AurigaDoc Ant Task

4.1. Using From Command Line
AurigaDoc converter utility can be used from the command line by executing the script aurigadoc.sh(for unix) or aurigadoc.bat(for windows) with the appropriate arguments.
Usage: aurigadoc.sh(or aurigadoc.bat) COMMAND OPTIONS PARAMETERS
COMMAND:

OPTIONS:

PARAMETERS:
-PARAM name=value: Additional parameter to be passed to the converter.
The foll parameters are supported

EXAMPLES:

4.2. Using From Java
AurigaDoc converter utility can be used from the a java class be following the steps given below:-

4.3. Using From Ant Target
AurigaDoc conversion can be invoked from an Ant target by using the following: -

<java dir="output-dir" 
	classname="com.aurigalogic.aurigadoc.cmdline.Converter" 
	fork="true">
	<classpath>
		<dirset dir="aurigadochome/bin" />
		<fileset dir="aurigadochome/lib">
			<include name="**/*.jar" />
		</fileset>
	</classpath>
	<arg line="-html -XML user-guide.xml -OUT user-guide.html" />
</java>


In the above code
output-dir is the absolute path of output directory
aurigadochome is the absolute path of AurigaDoc home directory.

4.4. Using AurigaDoc Ant Task
Starting from version 1.3b, AurigaDoc is distributed with an ant task which can be used from an ant target. The following steps should be followed to install and run the aurigadoc task.
Installation:


Task Description:
Parameters
Attribute Description Required
format The output format required. Valid values are: html, dhtml, mhtml, mht,fo, pdf, ps, awt, rtf, man, chm, jhelp. Yes
input The path of the input file. Yes
output The path of the output file/directory. Yes, unless the format is awt.
force Force conversion even if the output file(s) are upto date. No; defaults to false.


Parameters specified as nested elements:

param: aurigadoc task supports the nested param element(s) with the following attributes.
Attribute Description Required
name The parameter name. Yes
value The parameter value. Yes


Examples:
Note: The aurigadoc ant task will do the conversion only if the output files generated by a conversion are older then the source xml file or the output file(s) are deleted. The output files that are monitored include only text, xml and html and not any images/javascript files generated while building the dhtml output.

5. AurigaDoc Documentation Conventions
Documents to be converted using AurigaDoc should have the following structure:-

Any html tag can be used in the document but while converting to pdf/postscript/rtf only the following tags are supported.
  1. a
  2. img
  3. font
  4. u
  5. s
  6. b/strong
  7. i/em
  8. h1-h6
  9. br
  10. hr
  11. div
  12. p
  13. pre
  14. code
  15. blockquote
  16. address
  17. center
  18. ol
  19. ul
  20. li
  21. dl/dt/dd
  22. table
  23. tr
  24. td
  25. sub
  26. sup


6. CSS (Cascading Style Sheet) Support

Starting from version 1.3b AurigaDoc has been modified to depend heavily on css for formatting document. The appearance for all parts of the document can be controlled using css.

A css can be associated to a document by using the <stylesheet url=".." /> element inside the <document-formatting-info> element.

Even pdf/postscript output can be formatted using a css file. The css file for these outputs can be specified in the <stylesheet-fo url=".." /> element inside the <document-formatting-info> element. See the src (xml) document of this user guide for an example. Although support for css in pdf/postscript output is limited, using a css can greatly improve the look of the output document.
The css url may either be a:

- http:// url
- an absolute file system path
- or a file system path relative to the output directory.

In addition to specifying a css file, formatting for supported html elements can also be controlled by using the style attribute.

CSS stylesheet is not applied while creating the rtf due to limitations in jfor.


7. Change History
The following changes have been incorporated in the below mentioned versions:-

7.1. Version 1.3
7.2. Version 1.3b
7.3. Version 1.2
7.4. Version 1.2b
7.5. Version 1.1

7.1. Version 1.3
The following changes have been incorporated in Version 1.3:-

7.2. Version 1.3b
The following changes have been incorporated in Version 1.3b:-

7.3. Version 1.2
The following changes have been incorporated in Version 1.2:-

7.4. Version 1.2b
The following changes have been incorporated in version(1.2b):-

7.5. Version 1.1
The following changes have been incorporated in version(1.1):-

8. Limitations
The current version of AurigaDoc has the following limitations:-

9. Troubleshooting
The following things should be checked in case there is a problem running AurigaDoc.

10. License
AurigaDoc is available under the GPL License provided that the entire project/product for which AurigaDoc is used is released under an Open Source License recognized by The Open Source Initiative.

For alternative licensing, contact sales@aurigalogic.com

For more info on AurigaDoc usage, see the docs directory in the distribution or mail kshaikh@aurigalogic.com