ISIS Documentation

ISIS Application Examples How-to

Guide to writing the examples section of ISIS Application XML

Overview

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.

Questions & Answers

What do I need to know?

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.

What is an Application?

In a nutshell: it's a computer program, or software. For example, in ISIS algebra, sharpen, and compare are all applications.

What is Application XML?

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.

Where do I find the Application XML specification?

A handy reference to the Application XML language is available as part of the ISIS documentation.

What does "mandatory by policy" mean?

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.

Where do the Application XML files go in the ISIS structure?

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:

resides in $ISISROOT/src/base/ratio/
its XML file is $ISISROOT/src/base/ratio/ratio.xml
all the images in its examples are under the $ISISROOT/src/base/apps/ratio/assets/ directory

What happens to the examples I write?

[Screenshot - Crop Application Web Page]

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

How do I preview the examples as a web page?

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.

What is XML-Compliant HTML?

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.

Adding Examples to the Application XML metadata file

Anatomy of Application XML

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.

Above: Fully expanded diagram of examples section of the ISIS Application XML. Click to view image in a new window. (1300x1600, 45 KB)

Left: Collapsed diagram of the Examples section of ISIS Application XML.

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.

Image

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.

Attributes

All attributes are mandatory.

width: the width in pixels of the image (integer)
height: the height in pixels of the image (integer)
src: the path and file name of the image (path/filename)

Elements

All attributes are mandatory except for parameterName.

brief: a short (one sentence) description of the image
description: a long description or explanation, which may contain HTML
parameterName: the application parameter name associated with the image. parameterName is mandatory by policy when image is used in inputImages or outputImages. Do not use parameterName in guiInterfaces. For example, if this image is the result of running the crop application, the parameter name is TO.
thumbnail: A description of the thumbnail image associated with this image. thumbnail has the following attributes:
- width: the width in pixels of the thumbnail (integer)
- height: the height in pixels of the thumbnail (integer)
- src: the path and file name of the thumbnail (path/filename)
- caption: a short caption describing the thumbnail (text)

Images: Tips and Hints

Where should I put my images?

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.

What sizes should my images be?

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.

Images: no larger than 1760 pixels wide and 990 pixels tall
Thumbnails: no larger than 200 pixels wide or high, and no more than 32 KB file size

What format should my images be?

JPEG, PNG, or GIF. JPEG may be the easiest because ISIS has a file exporter (isis2std).

JPEG: 16 million colors, compress to reduce file size. Acceptable for all images.
- Isis: Quality 80 for regular images, Quality 50 for thumbnails and screen shots.
- Photoshop: Quality 10 for regular images, Quality 8 for thumbnails and screen shots.
PNG: 256 to 16 million colors. Acceptable for all images.
GIF: 256 colors. Acceptable for screen shots and greyscale images.

How do I create a screen shot of an application?

Windows: Click on the application window and hit Alt and PrtScn keys on the keyboard to copy the screen shot to your past buffer. Go to your favorite image processing software, create a new image and paste the screen shot into it.
Linux: Start the application and gimp. In gimp, open the File - Acquire - Screen Shot menu, set the delay to a few seconds, click on the application window to bring it to the front. When the mouse cursor turns to a plus sign (+), click the application window again. gimp will display the screen shot. Right-click on the screen shot and go the the File - Save menu to save the image.

Sample Code

  <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>

Brief

The brief element should contain a very brief (one sentence) synopsis or description of the example. This element may contain only text.

Sample Code

  <brief>
    200x300 sub-area
  </brief>

Description

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.

Sample Code

  <description>
    Extracting a 200x300 sub-area
  </description>

Terminal Interface

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:

commandLine: The actual command to recreate the example
description: a long description or explanation of the command line, which may contain HTML

Sample Code

  <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>

GUI Interfaces

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.

Sample Code

  <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>

Data Files

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:

Attribute

path: path and filename of the data file

Elements

brief: a short (one sentence) description of the data file
description: a long description or explanation, which may contain HTML
parameterName: the application parameter name associated with the data file. For example, if this data file is the result of running the percent application, the parameter name is TO.

Sample Code (`percent`)

  <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>

Input Images

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.

Sample Code

  <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>

Output Images

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.

Sample Code

  <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>

Examples

Sample Examples Section: The examples section from the crop.xml Application XML file
Complete Application XML File: The complete crop.xml Application XML file

Final Note

Don't forget to add an entry in the history section of the Application XML file!

Document History

Deborah Lee Soltesz

2003-04-22

Created

User Documentation

Contributor Documentation

Quick Links

Documentation Versions

ISIS 2

ISIS Application Examples How-to

Guide to writing the examples section of ISIS Application XML

Overview

Questions & Answers

What do I need to know?

What is an Application?

What is Application XML?

Where do I find the Application XML specification?

What does "mandatory by policy" mean?

Where do the Application XML files go in the ISIS structure?

What happens to the examples I write?

How do I preview the examples as a web page?

What is XML-Compliant HTML?

Adding Examples to the Application XML metadata file

Anatomy of Application XML

Image

Attributes

Elements

Images: Tips and Hints

Where should I put my images?

What sizes should my images be?

What format should my images be?

How do I create a screen shot of an application?

Sample Code

Brief

Sample Code

Description

Sample Code

Terminal Interface

Sample Code

GUI Interfaces

Sample Code

Data Files

Attribute

Elements

Sample Code (percent)

Input Images

Sample Code

Output Images

Sample Code

Examples

Final Note

Document History

Sample Code (`percent`)