Home

User Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Contributor Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Quick Links

Software Manual
AstroDiscuss
GitHub
API Reference

Documentation Versions


ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Documentation


ISIS Application Examples How-to

Guide to writing the examples section of ISIS Application XML

Home

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:

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.

[Application XML Diagram]

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.

[Examples XML Diagram (collapsed)] [Examples XML Diagram (fully expanded)]

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 Element - Application Examples XML Diagram]

image contains the following elements and attributes.

Attributes

All attributes are mandatory.

Elements

All attributes are mandatory except for parameterName.

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.

What format should my images be?

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

How do I create a screen shot of an application?

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

[Brief Element - Application Examples XML Diagram]

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

[Description Element - Application Examples XML Diagram]

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

[Terminal Interface Element - Application Examples XML Diagram]

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:

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

[GUI Interfaces Element - Application Examples XML Diagram]

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

[Data Files Element - Application Examples XML Diagram]

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

Elements

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

[Input Images Element - Application Examples XML Diagram]

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

[Output Images Element - Application Examples XML Diagram]

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


Final Note

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


Document History

Deborah Lee Soltesz2003-04-22Created