oXygen Cookbook¶
Setup¶
Environment Variable¶
OXYGEN_HOME=C:\Program Files\Oxygen XML Editor 17
Path it¶
;OXYGEN_HOME
Add Ant_Contrib¶
Add the Ant_Contrib task library to your system (http://ant-contrib.sourceforge.net/tasks/). You need to do this so oXygen will work properly.
oXygen’s Ant configuration details: C:opteclipsepluginscom.oxygenxml.editor_16.1.0.v2014102117frameworksantant.frameworkant
Understanding the Build Chain¶
When you click the “Build” button, oXygen (or more precisely, the the oXygen plugin for Eclipse) launches the Java runtime environment (java.exe), and passes it a ton of arguments (these can also be passed manually from the command line).
Build Log¶
When you build the docs, you’ll see a verbose version of the build log displayed in the “Text” window. Copy it (Ctrl+a, Ctrl+c) to the clipboard, and then paste it into your text editor (EditPad Pro). Save this as a text file, and view it as a “Python Script” (because the color coding makes it easier to discern its parts).
This file contains two functional parts:
Build Command¶
The first part (labelled “Executing:”) is the Build Command, and oXygen executes it to launch the build process (I think you could run a new build just by pasting this into a command prompt & pressing Enter).
With all of its flags, arguments, and properties (about a paragraph’s worth), this command is huge! Since it appears on one line, you can only see about 2% of it. To see it in its entirely, turn on “Word Wrap.”
The Build Command is easier to study if you copy it into a new file in your text editor. I found it helpful to turn on Auto Indent, and then break the command line up (by introducing paragraph breaks) so that similar parts line up. I found it helpful to enter a quotation mark into the search field because EditPad Pro hightlights all of the quotes, so all you can easily match them up, and then break the line after each end quote.
Building Stage Log¶
Besides setting Xerces as the XML parser, and passing it a configuration file, 2. Launches Ant, and passes it the Ant buildfile (build.xml) to processes; which takes the ditamap as its prime argument.
To generate a particular “flavor” of the docs, Ant processes a sequence of targets that are specific to that flavor (e.g., webhelp, pdf, etc.). Since every doc type is a specialized form of a more rudimentary doc type, execution sequences always starts with targets for general tasks, and they always end with the most specialized target for that doc type.
Case in point, the DITA Map XHTML docs are further processed to produce the Webhelp docs.
oXygen uses Ant to guide the build process, and Ant applies particular XSL transformations inside Targets.
TeleSign AuthID User’s Guide¶
The paths to the generated docs.
Desktop Version¶
Local¶
C:\Users\Chris\src\python_rest_api\doc\user\v1\build\mobile\WebHelp\index.html file:///%USERPROFILE%/src/python_rest_api/doc/user/v1/build/mobile/WebHelp/index.html
On Gullinx
Mobile Version¶
Local
C:\Users\Chris\src\python_rest_api\doc\user\v1\build\mobile\WebHelp_Mobile\index.html file:///%USERPROFILE%/src/python_rest_api/doc/user/v1/build/mobile/WebHelp_Mobile/index.html
On Gullinx
How to¶
Turn a Dreamweaver Web Page into DITA-based Web Help¶
The documentation for the TeleSign AutoAuth SDK was all in one long web page, and it had reached the point where had become unwieldy; the content wasn’t easy to discover. I needed to break it up into several topics, and arrange them in a logical hierarchy. I was currently working in Dreamweaver, and was considering creating a new document based on a template with a TOC on the left. I remebered that I once created a prototype web site that was like that, and I hunted through my hard drive, looking for it, with the intention of copying the look and feel. I ended up stumbling on anoter doc set that fit the bill; that I created using oXygen XML Editor. I had forgotten about using oXygenXML Editor, and it hadn’t occured to me that this would actually be really good approach to use for the TeleSign AutoAuth SDK docs.
Here what I did to transform the content into a DITA project.
The first thing to remember is you’re actually authoring this content in AutoAuth SDK repo (android_mobile_verification). You’re authoring it in the telesign_doc repo. And this (content authoring) will be unusual for that repo.
I think you’ll have to experiment, because this is getting too complicated to be able to predict what you need to do.
Note: Open the oXytgen XML perspective. To ensure that you get all the available DITA Map Transforms. Otherwise, you won’t see all of the tools, windows, transforms, that come with the oXygen XML Editor Eclipse plugin.
Create a ditamap¶
In the MobileVerification project (the android_mobile_verification repo, feature/api_doc), add a new folder called “docs”.
With the project folder selected, click File > New, and select “oXygen XML Editor” > “New from Templates”. Click Next.
Select Framework templates > DITA Map > map > Map. Click Next.
Set a value for the parent folder: MobileVerification/docs
- File: AutoAuthSDK.ditamap
- Check “Open file for editing when done”.
Click Finish.
Add a Topic¶
I think your doc set falls into the software documentation domain. See: 3.2 Technical Content Elements (http://docs.oasis-open.org/dita/v1.2/os/spec/langRef-technicalContent.html).
With the project folder selected, click File > New, and select “oXygen XML Editor” > “New from Templates”. Click Next.
Select Framework templates > DITA > topic > Concept. Click Next.
Set a value for the parent folder: MobileVerification/docs
- File: theAutoAuthSDK.dita
- Check “Open file for editing when done”.
Click Finish.
Add content to the topic¶
Add the TeleSign Logo to the Title Area¶
For more information on this procedure, see: http://www.oxygenxml.com/doc/ug-editorEclipse/#topics/webhelp-customization-add-image-to-title.html
Copy the file: “C:UsersChrissrcpython_rest_apidocuserv1source_statictelesign-logo.png”
to
C:opteclipsepluginscom.oxygenxml.editor_16.1.0.v2014102117frameworksditaDITA-OTpluginscom.oxygenxml.webhelpoxygen-webhelpresourcesimg
Build the Docs¶
- Open the *.ditamap file. You have to have this file open so the oXygen XML Editor tools icons appear in the toolbar.
- Click “Apply Transformation Scenarios” icon in the tool bar.
Note: you can “freeze” your build configuration settings into an Ant script (e.g., build.xml).
Insert an Image¶
You insert a reference to it - by using the “Insert Reference to Image” button in Author mode.
<image href=”file:///%USERPROFILE%/src/python_rest_api/doc/user/v1/source/mobile-content/static/images/IMG_0580.PNG“/> OS Detection ============
You don’t need to use the BrowserDetect script.
You can write your own javascript code that runs the statement: navigator.platform;
Try it out
Type this into your web browser address field: javascript:alert(navigator.platform)
How to Use It
You could create two directories beneath the _static/images directory. One for iPhone images, and one for Android images. In this way, all images can keep the same names - only one word in their path names will vary. You could make it a variable called “platform”.
Concepts¶
Documentation Framework¶
An XML schema for symantically structured authoring, that supports single-sourcing of content. The content then becomes the raw material that can be “extracted” (via XSLT) based on conditional logic, into a variety of presentation formats (e.g., PDF, XHTML, Webhelp), with custom rendering with the application of style sheets (CSS).
Examples are DITA, Docbook, Markdown, reStructuredText.
I chose to go with DITA (because it supports such a wide variety of transoformation scenarios).
DITA¶
The Darwin Information Type Architecture
DOST¶
I don’t know where the name DOST came from, but this is the DITA-OT Eclipse Plugin. It’s also called the DITA-OT runtime, and its required for invoking Ant from Java code. It’s packaged as an executable jar file:
dost.jar
If you start the Java environment with the -jar switch, and the name of the jar file (and no other parameters), you can view a list of the parameters that you can supply to dost.jar.
E.g.,
C:\\Users\\Chris>java.exe -jar "C:\\Program Files\\eclipse\\plugins\\com.oxygenxml.editor_15.0.0.v2013071613\\frameworks\\dita\\DITA-OT\\lib\\dost.jar"
java -jar lib/dost.jar [mandatory parameters] [options]¶
| Mandatory Parameter | Description |
|---|---|
| /i: | Specifies path and name of the input file. |
| /transtype: | Specifies the transformation type. |
| Options | Description |
|---|---|
| -help, -h | print this message |
| -version | print the version information and exit |
| /basedir: | specify the working directory |
| /ditadir: | specify the toolkit’s home directory. Default is “temp” |
| /outdir: | specify the output directory |
| /tempdir: | pecify the temporary directory |
| /logdir: | specify the log directory |
| /ditaext: | specify the file extension name to be used in the temp directory. Default is ”.xml” |
| /filter: | specify the name of the file that contains the filter/flaggin/revision information |
| /draft: | specify whether to output draft info. Valid values are “no” and “yes”. Default is “no” (hide them). |
| /artlbl: | specify whether to output artwork filenames. Valid values are “no” and “yes” |
| /ftr: | specify the file to be placed in the BODY running-footing area |
| /hdr: | specify the file to be placed in the BODY running-heading area |
| /hdf: | specify the file to be placed in the HEAD area |
| /csspath: | specify the path for css reference |
| /css: | specify user css file |
| /cssroot: | specify the root directory for user specified css file |
| /copycss: | specify whether to copy user specified css files. Valid values are “no” and “yes” |
| /indexshow: | specify whether each index entry should display within the body of the text itself. Valid values are “no” and “yes” |
| /outext: | specify the output file extension for generated xhtml files. Default is ”.html” |
| /xsl: | specify the xsl file used to replace the default xsl file |
| /xslpdf: | specify the xsl file used to replace the default xsl file when transforming pdf |
| /cleantemp: | specify whether to clean the temp directory before each build. Valid values are “no”and “yes”. Default is “yes” |
| /foimgext: | specify the extension of image file in legacy pdf transformation. Default is ”.jpg” |
| /fooutputrellinks | For legacy PDF transform: determine if links are included in the PDF. Values are “no” and “yes”. Default is “no”. |
| /foincluderellinks | For default PDF transform: determine which links are included in the PDF. Values are”none”, “all”, and “nofamily”. Default is “none”. |
| /odtincluderellinks | For default ODT transform: determine which links are included in the ODT. Values are”none”, “all”, and “nofamily”. Default is “none”. |
| /retaintopicfo | specify that topic.fo file should be preserved in the output directory. Specify any value, such as “yes”, to preserve the file. |
| /javahelptoc: | specify the root file name of the output javahelp toc file in javahelp transformation. Default is the name of the input ditamap file |
| /javahelpmap: | specify the root file name of the output javahelp map file in javahelp transformation. Default is the name of the input ditamap file |
| /eclipsehelptoc: | specify the root file name of the output eclipsehelp toc file in eclipsehelp transformation. Default is the name of the input ditamap file |
| /eclipsecontenttoc: | specify the root file name of the output Eclipse content provider toc file in eclipsecontent transformation. Default is the name of the input ditamap file |
| /xhtmltoc: | specify the root file name of the output xhtml toc file in xhtml transformation |
| /xhtmlclass: | specify whether DITA element names and ancestry are included in XHTML class attributes. Only “yes” and “no” are valid values. The default is yes. |
| /usetasklabels: | specify whether DITA Task sections should get headings. Only “YES” and “NO” are valid values. The default is NO. |
| /validate: | specify whether the ditamap/dita/xml files to be validated |
| /outercontrol: | specify how to respond to the overflowing dita/topic files. Only “fail”, “warn” and “quiet” are valid values. The default is warn. |
| /generateouter: | specify how to deal with the overflowing dita/topic files. Only “1”, “2” and “3” arevalid values. The default is 1.k /onlytopicinmap: specify whether make dita processor only resolve dita/topic files which are referenced by primary ditamap files Only “true” and “false” are valid values. The default is false. |
| /debug: | specify whether extra debug information should be included in the log. Only “yes” and “no” are valid values. The default is no. |
| /grammarcache: | specify whether grammar pool caching is used when parsing dita files. Only “yes” and”no” are valid values. The default is yes. |
| /odtimgembed: | specify whether embedding images as binary data in odt transform. Only “yes” and “no”are valid values. The default is yes. |
Apache Ant¶
A Java program, similar to GNU Make. It processes Ant Projects, which are packaged as buildfiles.
Buildfile¶
A Buildfile is an XML file that contains an Ant Project. You use an Ant Project to coordinate the building of code and doc projects. This approach provides the flexibility needed for automated processing of custom configurations.
Projects contain groups of processing instructions called Targets. The processing instructions a Target contains correspond to a unique processing scenario.
A Target contains a group of Task Elements (Tasks) that are executed in sequence.
Each Task Element can have a unique ID attribute, which can be used to reference that Task, from any other Task.
oXygen’s DITA Buildfile¶
This is part of the oXygen XML Eclipse plugin installation:
C:\Program Files\eclipse\plugins\com.oxygenxml.editor_15.0.0.v2013071613\frameworks\dita\DITA-OT\build.xml
When you use oXygen to build documentation in Eclipse, this is the buildfile that it feeds to Ant.
This buildfile imports several other buildfiles into it; one for each transformation type (e.g., PDF, WebHelp, etc.).
It imports the buildfile that you use for the AuthID docs:
C:\Program Files\eclipse\plugins\com.oxygenxml.editor_15.0.0.v2013071613\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\build_dita.xml
oXygen Custom Editor Variables¶
${ProductName1}=AuthID ${FeatureName1}=Push Verification ${FeatureName2}=Soft Token ${CompanyName}=TeleSign
Troubleshooting¶
The oXygen folks spaced on the fact that when used in Eclipse, oXygen should defer to the system’s Ant installation (and not install their own verson).
oXygen’s Ant configuration details: C:opteclipsepluginscom.oxygenxml.editor_16.1.0.v2014102117frameworksantant.frameworkant
Eclipse’s Ant configuration details: C:opteclipsepluginsorg.apache.ant_1.9.2.v201404171502libant.jar
You System’s Ant configuration details: C:UsersChris.antlib
Notes¶
How can you add the doc build timestamp to the footer of each page if you can’t use Javascript in the footer of the mobile version of the docs?
If you think of the ditamap as the Class for instantiating doc builds, and if you think of the build timestamp as a property of the doc build, then this task is straightforward:
- Add a new doc property to the docset class (ditamap).
- Initialize it with a value upon instantiation (Ant > buildfile).
- Write that doc prop value into the output (XSLT Tranform > WebHelp XHTML).
- Add a <topicmeta> element to your ditamap file. It contains a <critdates> element, which in-turn contains the <revised> element. I.e.,
<topicmeta>
<critdates>
<revised modified="@DATE_OF_BUILD@"/>
</critdates>
</topicmeta>
- Create a new empty build.xml file, and place it in your project’s root directory ().
In the buildfile that’s part of the oXygen installation
“C:\Program Files\eclipse\plugins\com.oxygenxml.editor_15.0.0.v2013071613\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\build.xml”
or
“C:Program FilesOxygen XML Editor 17frameworksditaDITA-OTbuild.xml”
, add a new task to the Initialization target, for resolving the build time-stamp value, and populating the @DATE_OF_BUILD@ token with that value. Try using the Tstamp task for this (http://ant.apache.org/manual/Tasks/tstamp.html).
<buildnumber file="docbuild.number"/> <!-- Gullinx Increment the doc build number -->
<tstamp> <!-- Gullinx Initialize the doc build timestamp -->
<format property="DATE_OF_BUILD" pattern="yy/MM/dd hh:mm aa"/>
</tstamp>
- Create an XML transform to include the build date in the footer of each HTML page.
Implement the build number mechanism as well.
<buildnumber file="docbuild.number"/>
