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 Documents How-to

Guide to writing documents using ISIS Documentation XML

Home

Overview

ISIS has three kinds of documentation: Application, Object, and General Documents. Application and Object documentation are part of the programming and development structure and are discussed in those portions of the ISIS documentation. General Documents are not associated directly with Applications or Objects. Such documents include user guides, procedural instructions, administration references, and this very document you are reading now. This guide describes the formats Documents may be in, what types of Documents may be added, and how to write the ISIS Documentation XML metadata file that is used to automatically add a Document to the ISIS system.

ISIS documentation is part of the source code distribution, resides in an organized structure, and in part is automatically generated from text files written in the ISIS XML languages. A copy of the documentation is published to the ISIS web site, therefore the ISIS web site and the ISIS documentation are identical. In this document, the term "web site" will refer to the complete ISIS documentation.

Questions & Answers

What do I need to know?

You should have a general understanding of what XML is - this document explains how to write an XML file for adding a Document to ISIS. If you plan to add a web page to ISIS, you should be able to write basic HTML. 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 a Document?

A Document is a file, or a set of files, that supply information related to ISIS. Documents that are most common are guides and reference manuals. Documents are automatically linked into the upper levels of the ISIS website based on the audience and category supplied in the metadata file. Documents may be written by the ISIS team members and housed in the documentation or may be external resources on other web sites.

What is the Document metadata file?

The Document metadata file is an XML file that describes a Document, and may even contain the HTML formatted content of the Document itself. In the latter case, the Document metadata will be automatically transformed to an HTML file during the building of the ISIS documentation. The metadata file also contains bibliographic information, history tracking, file information, and the target audience and category the Document will be linked under on the ISIS web site.

Where do I find the Document XML specification?

A handy reference to the Document 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 Documents go in the ISIS structure?

Documents live in $ISISROOT/../isis/src/docsys/documents/. Each Document (its metadata and files) should be in its own directory, and subcomponents should reside in a directory named assets. The XML metadata file should be named the same as the directory with a .xml extension. For example, this Document:

Writing the Document XML metadata file

Anatomy

Each document must start with the XML document prolog: 

  <?xml version="1.0" encoding="UTF-8"?>
followed by the start root element: 
  <documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://isis.astrogeology.usgs.gov/Schemas/Documentation/documentation.xsd">
The rest of the document is made up of the metadata content, and ended with the closing tag of the root element: 
  </documentation>

The following chart illustrates the layout of the Document XML language used to write the metadata file. Click the image to view the full sized chart (opens in a new window).

[Document XML Diagram]

The language and its usage will be described in the sections that follow, in order of increasing complexity.

History

[History Element - Document XML Diagram]

The purpose of the history element is to record changes to a Document. This element is not mandatory because a Document may be a resource on another website and not maintained by the ISIS team. However, if you are creating a new Document or editing an existing Document, this element is mandatory by policy!

The history element contains one or more change elements. The change element has two attributes, name and date and should contain a free text comment describing the change to the document.

Example

  <change name="Deborah Lee Soltesz" date="2003-01-29">Created</change>

Bibliography

[Bibliography Element - Document XML Diagram]

The purpose of the bibliography element is to document bibliographic information about the document: author, publisher, etc. The bibliography element contains the following elements:

All elements are mandatory except for publisher (which should be used when the publisher is not the Astrogeology Research Program). All elements may contain free text except the date and may appear in any order. The bibliography information is used to create links in the ISIS web pages and generate title and header information if the Document metadata is to be transformed to an HTML file.

Example

  <bibliography>
    <title>ISIS Documents How-to</title>
    <brief>Guide to writing documents using ISIS Documentation XML</brief>
    <description>Guide to adding documents to the ISIS
    documentation tree. All documents added to the official ISIS
    documentation will be automatically linked on the ISIS web
    pages and distributed with ISIS. This guide describes the formats
    documents may be in, what types of documents may be added, and
    how to write the ISIS Documentation XML metadata file that is
    used automatically add a document to the ISIS system.</description>
    <author>Deborah Lee Soltesz</author>
    <date>2003-01-29</date>
  </bibliography>

Category

[Category Element - Document XML Diagram]

The purpose of the category element is to specify how the Document will be categorized on the web site. The category element contains one or more categoryItem elements. The categoryItem element can be one of several preset categories:

Refer to the Documentation XML specification for an up-to-date list of categories.

Example

  <category>
    <categoryItem>xml</categoryItem>
    <categoryItem>technicalinfo</categoryItem>
    <categoryItem>guide</categoryItem>
  </category>

Audience

[Audience Element - Document XML Diagram]

The purpose of the audience element is to specify (in combination with category) how the Document will be categorized on the web site. The audience element contains one or more target elements. The target element can be one of several preset audiences:

Refer to the Documentation XML specification for an up-to-date list of audiences.

Example

  <audience>
    <target>developer</target>
  </audience>

Files

[History Element - Document XML Diagram]

The purpose of the files element is to specify the information about the file or files in this Document. This information is used to create links in the ISIS web pages and even transform the metadata file into new HTML documents.

The files element contains one or more file elements. There is one file element for each file in the Document. Another application of this is that you want to present one document in multiple file formats (e.g. PDF, Excel, and Access) - each format would be documented in its own file element. The file element has the following attributes:

The file element contains the following elements:

Examples

The following examples are Document XML metadata files.

Coming Soon

Document History

Deborah Lee Soltesz2003-01-29Created
Deborah Lee Soltesz2003-03-04Revisions based on review by Stuart Sides
Deborah Lee Soltesz2003-04-01Added explanations for new items category:tutorial and audience:intermediate
Kristin Berry2019-11-14Updated to change path to ISIS documentation source after update to cmake build system and remove reference to documentation being distributed with an ISIS build, as this is no longer the case.