Categories
oXygen

Concepts

Documentation Framework

A documentation framework is an XML schema for semantically 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).

I chose to go with the DITA documentation framework because it supports such a wide variety of transformation scenarios.

DITA

DITA stands for the Darwin Information Type Architecture.

DOST

I don’t know where the name DOST came from, but it’s 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

Apache Ant is a Java builder 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 that a Target contains corresponds 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 you can then use 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 a documentation set in Eclipse, this is the build file that oXygen feeds to Ant.

This build file imports several other build files into it; one for each transformation type (e.g., PDF, WebHelp, etc.).

It imports the build file that you use for the 3rdPartySDK 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}=3rdPartySDK
${FeatureName1}=Push Verification
${FeatureName2}=Soft Token
${CompanyName}=3rdParty

DITA Scenario

Advanced

Additional Arguments

Example

-diagnostics -logger org.apache.tools.ant.XmlLogger -logfile buildlog.xml
Categories
oXygen

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”

Categories
oXygen

Remove the “WebHelp output generated by oXygen” from the Footer of Every Page

Modify this XSL Transformation: “C:\opt\eclipse\plugins\com.oxygenxml.editor\_16.1.0.v2014102117\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\dita\dita2webhelp.xsl”

Search for the <div class=”footer”> … </div> block, and either comment it out, or change it.

Categories
Eclipse oXygen

Build the Docs

  1. Open the *.ditamap file. You must have this file open so that the oXygen XML Editor tools icons appear in the toolbar.
  2. 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).

Categories
Eclipse oXygen

How to Turn a Dreamweaver Web Page into DITA-based Web Help

The documentation for the 3rdParty 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 remembered 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 another doc set that fit the bill, that I created using oXygen XML Editor. I had forgotten about using oXygenXML Editor, and it hadn’t occurred to me that this would actually be a really good approach to use for the 3rdParty 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 3rdParty repo (android_mobile_verification). You’re authoring it in the 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 oXygen XML perspective to ensure that you get all of 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

  1. In the MobileVerification project (the android_mobile_verification repo, feature/api_doc), add a new folder called “docs”.

  2. With the project folder selected, click File > New, and select oXygen XML Editor > New from Templates. Click Next.

  3. Select Framework templates > DITA Map > map > Map. Click Next.

  4. Set a value for the parent folder: MobileVerification/docs

    1. File: 3rdPartySDK.ditamap
    2. Check Open file for editing when done.

  5. 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).

  1. With the project folder selected, click File > New, and select oXygen XML Editor > New from Templates. Click Next.

  2. Select Framework templates > DITA > topic > Concept. Click Next.

  3. Set a value for the parent folder: MobileVerification/docs

    1. File: theAutoAuthSDK.dita
    2. Check Open file for editing when done.

  4. 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:\Users\Chris\src\python_rest_api\doc\user\v1\source_statictelesign-logo.png

to

C:\opt\eclipse\plugins\com.oxygenxml.editor_16.1.0.\v2014102117\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\oxygen-webhelp\resourcesimg
Categories
oXygen

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 lined up. I found it helpful to enter a quotation mark into the search field because EditPad Pro highlights 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, launches Ant and passes it the Ant build file (build.xml) to processes; which takes the ditamap as its prime argument.

To generate a particular “flavor” of the docs (e.g., webhelp, pdf, etc.), Ant processes a sequence of targets that are specific to that flavor. Since every doc type is a specialized form of a more rudimentary doc type, execution sequences always start 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.

Categories
oXygen

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:\opt\eclipse\plugins\com.oxygenxml.editor_16.1.0.\v2014102117\frameworks\ant\ant.frameworkant
Categories
Eclipse Java

Windows Path Statement

I’ll use my path statement to demonstrate a path statement for a typical Eclipse installation.

%SystemRoot%;%SystemRoot%\system32;%SystemRoot%\System32\Wbem;%SYSTEMROOT%\System32\WindowsPowerShell\v1.0;C:\Androidsdk\platform-tools;%JDK_HOME%\bin;%JAVA_HOME%\bin;%PYTHON_HOME%;%PYTHON_HOME%\Scripts;C:\Program Files (x86)\Gitcmd;C:\Program Files (x86)\Gitbin;%MinGW_HOME%/bin;%MERGEHOME%\%ANT_HOME%\bin;X:\JGSoft\Tools\HTML Tidy and XML Tidy;C:\Program Files\InteliCLS\Client;C:\Program Files (x86)\InteliCLS\Client;C:\Program Files\Intel\Intel(R) Management Engine Components/DAL;C:\Program Files\Intel\Intel(R) Management Engine Components\IPT;C:\Program Files (x86)\Intel\Intel(R) Management Engine Components\DAL;C:\Program Files (x86)\Intel\Intel(R) Management Engine Components\IPT;C:\Program Files (x86)\Windows Kits\8.0\Windows Performance Toolkit;C:\Program Files\Microsoft SQL Server\100\Tools\Binn;C:\Program Files\Microsoft SQL Server\100\DTS\Binn;C:\Program Files (x86)\Microsoft SQL Server\100\Tools\Binn;C:\Program Files (x86)\ATI Technologies\ATI.ACECore-Static;%OXYGEN_HOME%;X:\FCIV;C:\Program Files (x86)\QuickTime\QTSystem;C:\Perl64bin;C:\Perl64\site\bin

 

Categories
Eclipse

Java Path, System, and Environment Variables

Eclipse uses path variables in build configuration scripts to create portable projects.

Environment variables are defined within a hierarchy, which defines each one’s scope of access.

  1. The operating system. These are the current user’s environment variables (UserDomain.UserName). For Example,

    USERNAME = Chris

  2. The Eclipse IDE and the Java Virtual Machine ( referred to as System Properties of the Java Platform). To maximize portability, never refer to an environment variable when the same value is available in a System Property. For example, if the operating system provides a user name, it will always be available in the system property user.name.

  3. The current Workspace in Eclipse.

  4. The current Project within the current workspace. These are the environment variables that the build configuration can access directly. For example,

    Path: /java_3rdParty

To see and create Path Variables for a particular java project:

  1. Right-click the java project in Project Explorer, and click Properties.
  2. Navigate to Resources > Linked Resources > Path Variables.

Use PROJECT_LOC as a starting point, and create

JAVADOC_LOC = ${PROJECT_LOC}\doc LIBRARIES_LOC = ${PROJECT_LOC}\libs SOURCE_LOC = ${PROJECT_LOC}\src

Note: To use these in an Ant script, you have to define and assign equivalent local variables.

Categories
Eclipse

What Eclipse Does to your Project

Eclipse adds /bin folder for compiled Java class files.

Code folding

Under the Source menu.

Collapse Code: Ctrl + -

Uncollapse Code: Ctrl + =

Collapse Code (All): Ctrl + 9

Uncollapse Code (All): Ctrl + 0

Add to dictionary

Ctrl + Shift + Right Click

Show in breadcrumb

Only available in the Java Editor.

Ctrl + Shift + B

Working set

Imagine if the Project Explorer contained a filtered view of resources in your project. I.e., a subset of it. E.g., a view that ignores the Test directory, and everything in it; but includes parts of another project within the workspace. If you could save such a view, it would essentially be a Working Set.

Path Variables

These are just like Environment Variables, but they apply to Eclipse, the Current Workspace, and the Current Project. Here are some examples.

ECLIPSE_HOME: C:\Program Files\eclipse\

WORKSPACE_LOC: A:\Documents\Eclipse\Projects\Practice

PROJECT_LOC: A:\Documents\Eclipse\Projects\Practice\TestSphinxWiz

Workspace

Your workspace is a folder that contains a subfolder called “.metadata”.

Counter to what you might expect, the workspace folder doesn’t physically contain project folders. It contains them by reference.