Message-ID: <29464857.1129030224396.JavaMail.kshaikh@tull.aurigalogic.com> From: info@aurigalogic.com Subject: Composed using AurigaDoc Mime-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_0_10769461.1129030224268" X-Mailer: AurigaDoc 1.4.0-b (20051011/1642) ------=_Part_0_10769461.1129030224268 Content-Type: text/html Content-Transfer-Encoding: 7bit AurigaDoc: User Guide
AurigaDoc: User Guide


Author : Khurshidali Shaikh <kshaikh at aurigalogic dot com>

Company : Auriga Logic

Revision : $Revision: 30 $

Last Modified : $Date: 2005-10-11 15:50:39 +0530 (Tue, 11 Oct 2005) $


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. Profiling
8. Modularity
9. Change History
9.1. Version 1.4.0-b
9.2. Version 1.3
9.3. Version 1.3b
9.4. Version 1.2
9.5. Version 1.2b
9.6. Version 1.1
10. Limitations
11. Troubleshooting
12. License
INDEX

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 up-to 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. span
  4. font
  5. u
  6. s
  7. b/strong
  8. i/em
  9. h1-h6
  10. br
  11. hr
  12. div
  13. p
  14. pre
  15. code
  16. blockquote
  17. address
  18. center
  19. ol
  20. ul
  21. li
  22. dl/dt/dd
  23. table
  24. tr
  25. td
  26. sub
  27. 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. Profiling

Many times it is required to generate a slightly different version of the same document for different audiences. Previously the only way to achieve this using AurigaDoc was to make a copy of the original document for each variation and make the necessary changes. This was a maintenance headache as common changes in one had to be manually copied into others.

Starting from version v1.4.0-b AurigaDoc supports profiling of documents. With profiling, elements(sections, paragraphs, etc) can be marked as conditional. While actual output generation one or more conditions can be specified to generate the output with elements matching those conditions.

e.g. some sections can be given a os attribute like this <section os="win".. to indicate that it is intended for only windows operating systems. While generating output a parameter can be passed to specify a value for os like this -PARAM profile.os=win
With the above parameter only elements which have a os attribute value of win will be included in the output. Other supported attributes can be specified similarly.

Even multiple values can be specified for a attribute like this <section os="win,windows"..
With the above setting the element will be selected if the value of profile.os is win or windows

AurigaDoc supports a predefined set of profiling attributes. These are similar to those supported by DocBook. Listed below are the attributes and the name of corresponding command line parameters.
Attribute Description Command Line Param
os the operating system profile.os
lang language profile.lang
arch computer architecture profile.arch
revision revision profile.revision
revisionflag revision status profile.revisionflag
role can be used for indicating a user role. profile.role
security security level like high, medium, low, etc profile.security
userlevel user level like beginner, intermediate, expert, etc profile.userlevel
vendor product vendor profile.vendor
format output format like html, mhtml, dhtml, pdf, ps, fo, jhelp, etc.
The profile.format parameter value is set implicitly depending on the output format specified.
A sample usage of this would be to have different page header, etc for pdf and html related outputs.
NONE. The parameter is implicitly passed.

Some of the situations where profiling is useful are:-


8. Modularity

Its is often desired to break up a single big documents into parts for ease of maintenance and for code/markup reuse. Also sometimes it is required to include external files(text, source code, etc) into the document without having to format/copy it in the including document.

Prior to this this was not possible with AurigaDoc. Now this can be achieved using XInclude. AurigaDoc now handles inclusion of external documents using XOM (http://www.cafeconleche.org/XOM/).

In order to use XInclude rewrite the document tag like this.
<document xmlns:xi="http://www.w3.org/2001/XInclude">

An external xml document can be included in the source xml document like this
<xi:include href="path-to-external-file" />

An external non-xml file(like text or source file) can be included like this. Note the parse="text" attribute.
<xi:include href="url-to-external-file" parse="text" />


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


9.1. Version 1.4.0-b
9.2. Version 1.3
9.3. Version 1.3b
9.4. Version 1.2
9.5. Version 1.2b
9.6. Version 1.1

9.1. Version 1.4.0-b
The following changes have been incorporated in Version 1.4.0-b:-

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

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

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

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

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

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

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

12. License
AurigaDoc is available under the GPL License recognized by The Open Source Initiative.

For alternative licensing, contact sales at aurigalogic dot com

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

INDEX
------=_Part_0_10769461.1129030224268 Content-Type: application/octet-stream Content-Transfer-Encoding: 7bit Content-ID: <11290302241531> body {background-color: white; font-family: verdana,arial,Helvetica; font-size: 12px; margin-top: 0px; margin-left: 10px; } a {text-decoration:none;color:#C00000} a:Hover {text-decoration:underline;} td {font-size : 12px; font-family : verdana,arial,Helvetica;} p {font-size : 12px; font-family : verdana,arial,Helvetica;} .navigation { font-family : verdana,arial,Helvetica; text-align:left; font-size : 10px; font-weight : bold; color: #000000; background-color: #F0F0F0; border:1px solid silver; -moz-border-radius: 12pt; padding-left:10px; margin-right:10px; height:20px; padding-top:3px; } .section-heading-1 { font-family : verdana,arial,Helvetica; text-align:left; vertical-align:bottom; font-size : 20px; font-weight : bold; color: #000000; } .section-heading-2 { font-family: verdana,arial,Helvetica; text-align:left; vertical-align:bottom; font-size: 14px; font-weight: bold; color: #000000; } .section-body-1 { font-family : verdana,arial,Helvetica; text-align:left; margin-left: 10px; } .section-body-2 { font-family: verdana,arial,Helvetica; text-align:left; margin-left: 10px; } .document-footer { font-family: verdana,arial,Helvetica; text-align:right; font-size: 8px; } .document-header { font-family: verdana,arial,Helvetica; text-align:right; font-size : 16px; font-weight: bold; color: #000000; } .document-title { font-family: verdana,arial,Helvetica; text-align: left; font-size : 22px; font-weight : bold; color: gray; } .document-attributes { font-family : verdana,arial,Helvetica; text-align: left; font-size : 12px; color: #000000; } .attribute-name { font-weight:bold; } .attribute-value { } .page-break { page-break-before:always; } .note { border: 1px; border-style: solid; padding: 1px; background-color: #F0F0F0; color: #000000; font-size : 10px; } div.note:before { content: url('bulb.png'); } .index-heading { font-size:14px; } .index-list { padding-left:15px; } .index-item { text-decoration:underline; } ul.image-bullet { list-style-image:url('bullet.gif'); } code:Hover { background-color: #E0E0E0; } .page-header { margin-top:-10pt; margin-right:-10pt; margin-left:-10pt; space-before:0pt; space-after:100pt; background-color: #E0E0E0; } li.index-item { list-style-image:url('bullet.gif'); } a[target]:after { content: url('popup.gif'); padding-left: 2px; } ------=_Part_0_10769461.1129030224268 Content-Type: image/gif Content-Transfer-Encoding: base64 Content-ID: <11290302241532> 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 zKUud8nLXvryl2QIAgA7 ------=_Part_0_10769461.1129030224268--