ISIS Documentation
ISIS Application Examples How-toGuide to writing the examples section of ISIS Application XML | Home |
ISIS Application XML files are used for a variety of purposes: a guide for users, documentation for programmers, context-sensitive help, and generating the application window when a user runs the program in graphical mode to name a few. This guide focuses on the specific task of adding examples to an application's XML file, which become part of the users' Software Manual.
All sample code below is from the crop application unless noted otherwise.
You should have a general understanding of what XML is - this document explains how to add to an XML file in order to add an example to the software documentation. You may want to be able to write basic HTML in order to enhance the formatting of certain sections. You should know some basic image processing, such as how to create a JPEG, how to resize an image and sharpen it, and so forth -- the image processing tasks required can be performed in ISIS, Adobe Photoshop, or a number of other popular image processing software packages. It also helps if you are familiar with the ISIS web site and how it is organized from a visitor's standpoint. There are many good tutorials on the web for learning XML and HTML, such as W3Schools.com.
In a nutshell: it's a computer program, or software. For example, in ISIS algebra, sharpen, and compare are all applications.
Each application has a file describing it - what parameters it takes, what values are valid for those parameters, who wrote the software, descriptions of what the software does, etc. The file is used to generate web page documentation and provide information to the application when it runs. The file is written in the Application XML language, which specifies how the information about an application is stored in the file.
A handy reference to the Application XML language is available as part of the ISIS documentation.
An element that is "mandatory by policy" means it must be used in certain situations according to the policies of the ISIS Programming Team, USGS, DOI, Section 508, or common sense. For instance, specifying file size for non-text files is a USGS policy and is standard practice in web development - when a link to a non-text file is created on the ISIS website, the link will include the file size information so visitors will know how big the file they're getting ready to download is. Not only does the USGS say we have to give this information, but it's also a very polite practice, and visitors love polite web developers.
Base Application XML files and source code all live in $ISISROOT/src/base/apps/. Mission-specific Application XML files and source code live in $ISISROOT/src/{mission}/apps/. Each application has its own directory with the same name as the application where the application's XML and source code are kept. Documentation subcomponents (such as example images) reside in a directory named assets under the application directory. An Application XML file is named the same as the application name with a .xml extension. For example, ratio:
When the ISIS system is built, the ISIS Software Manual is generated from the Application XML files. Each application has its own web page in the manual, and the examples are part of the page for their respective applications.
The image to the left illustrates how the example for the crop application was transformed into a web page. Click the image to open a larger version of the screen shot in a new window (445x800, 115 KB).
Each application has a make target to automatically generate a web page from the application's XML file. Run the following command, filling in the application name for application: make application.html and open the application.html in your favorite web browser using the File - Open menu. For example, to preview the web page for crop, run make crop.html and open crop.html in your browser.
It's HTML code that is written to follow XML's rules. For example, all tags have a beginning and ending tag, empty tags (such as img and br) must have a slash before the ending angle bracket, all attributes must be in quotes, etc. See W3C XHTML 1.0, Section 4: Differences with HTML 4 for more about writing XML-Compliant HTML.
Remember, if you use HTML, you'll be formatting only a small part of the document, the headers, page title, body tags, and so forth are all ready handled for you. Avoid using structural elements, such as headings, horizontal rules, etc. Keep it simple - bold, italics, lists, code, pre, tt, and tables should be all most folks need. You may use span with the style attribute defined in place of text formatting (such as bold and italics) if you are comfortable with using CSS style language.
Each document must start with the XML document prolog:
<?xml version="1.0" encoding="UTF-8"?>
followed by the start root element:
<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://isis.astrogeology.usgs.gov/Schemas/Application/application.xsd">
The rest of the document is made up of the content, and ended with the closing tag of the root element:
</application>
The following chart illustrates the basic layout of the Application XML language used to write the application file. The examples section is highlighted in the chart. Other sections of the Application XML file are discussed in separate documents.
Each application XML file has one examples section, which may contain any number of example sections - one per example. The maximum recommended number of examples is three. Your examples should present a wide range of capabilities of the application.
The following chart (below, left) illustrates the basic structure of the examples section of the Application XML language. Click the thumbnail image to the right of the chart to view a comprehensive diagram of the examples section.
Unless noted otherwise, all elements are mandatory by policy! If an element can be used and is applicable, it must be present. The examples section language and its usage will be described in detail in the sections that follow.
The image element is described here first because it is a special element used throughout the examples section of the Application XML language. The image element is used to describe an image you wish to use to illustrate your example. It is part of the guiInterface, inputImages, and outputImages elements described later in this document.
image contains the following elements and attributes.
All attributes are mandatory.
All attributes are mandatory except for parameterName.
In the directory where your XML file resides, create an assets directory. In the assets directory, create an images and a thumbs directory. Store your images in the assets/images directory, and your thumbnails in the assets/thumbs directory.
Images should fit comfortably on a monitor set to 1920x1080 resolution. Thumbnails are used as clickable icons that represent the larger image. Thumbnails should be small enough to load on a web page quickly and take up minimal space on a web page, yet be large enough to give your audience a sense of what they will see if they choose to view the full sized image.
JPEG, PNG, or GIF. JPEG may be the easiest because ISIS has a file exporter (isis2std).
<image src="assets/images/peaks.1.jpg" width="500" height="500">
<brief>Input image for crop</brief>
<description>
This is the input image for the 200x300 example of crop.
The area to be "cropped" is shown in red.
</description>
<thumbnail caption=" Input image" src="assets/thumbs/peaks.1.jpg" width="200" height="200"/>
<parameterName>FROM</parameterName>
</image>
The brief element should contain a very brief (one sentence) synopsis or description of the example. This element may contain only text.
<brief>
200x300 sub-area
</brief>
The description element should contain a long description of the example, including any tips or instructions the user should be aware of. This element may contain XML-compliant HTML formatting.
<description>
Extracting a 200x300 sub-area
</description>
The purpose of the terminalInterface element is to show the user the command used on the terminal interface command line to execute the example. The terminalInterface element contains two elements:
<terminalInterface>
<commandLine>
crop f=peaks.cub t=crop.cub samp=100 line=200 band=1 nsamp=200 nline=300 nbands=1
</commandLine>
<description>
In this example crop will extract a 200x300 sub-area that starts at sample 100 and line 200
</description>
</terminalInterface>
The purpose of the guiInterfaces element is to provide one or more screen shots of the application windows. guiInterfaces may contain one or more guiInterface elements. Each guiInterface element contains one image element.
The image element is a special element that may be used in several places. See the image element description for more information.
<guiInterfaces>
<guiInterface>
<image width="472" height="388" src="assets/images/cropgui.jpg">
<brief>Example Gui</brief>
<description>
Screen shot of GUI with parameters filled in to
perform a 200 pixel by 300 pixel crop of the input image.
</description>
<thumbnail width="200" height="165" caption="Crop Gui" src="assets/thumbs/cropgui.jpg" />
</image>
</guiInterface>
</guiInterfaces>
The purpose of the dataFiles element is to show the non-image sample files generated by or input to the application. dataFiles may contain one or more dataFile elements, one per file. dataFile has the following elements and attributes:
<dataFiles>
<dataFile path="assets/percent.txt">
<brief>Output file for percent</brief>
<description>
Output text file shown in editor giving results of the percent application.
</description>
<parameterName>TO</parameterName>
</dataFile>
</dataFiles>
The purpose of the inputImages element is to show the sample images used as input to the application for this example. inputImages may contain one or more image elements. The image element is a special element that may be used in several places. See the image element description for more information.
<inputImages>
<image src="assets/images/peaks.1.jpg" width="500" height="500">
<brief>Input image for crop</brief>
<description>
This is the input image for the 200x300 example of crop.
The area to be "cropped" is shown in red.
</description>
<thumbnail caption=" Input image" src="assets/thumbs/peaks.1.jpg" width="200" height="200"/>
<parameterName>FROM</parameterName>
</image>
</inputImages>
The purpose of the outputImages element is to show the sample images that are generated by the application when it is run. outputImages may contain one or more image elements. The image element is a special element that may be used in several places. See the image element description for more information.
<outputImages>
<image src="assets/images/peaks.crop.jpg" width="200" height="300">
<brief>Output image for crop</brief>
<description> This is the output image for the 200x300 example of crop
</description>
<thumbnail
caption="Output image showing results of the crop application with 200 by 300 input."
src="assets/thumbs/peaks.crop.jpg" width="133" height="200"/>
<parameterName>TO</parameterName>
</image>
</outputImages>
Don't forget to add an entry in the history section of the Application XML file!
Deborah Lee Soltesz | 2003-04-22 | Created |