Software Documentation

SCEC software engineering group distributes numerous scientific software codes to the research community. These software codes are accompanied by documentation to explain how to use these codes effectively.

Overview

CME Project software developers integrate complex scientific codes together into larger computational systems that we call Computational Platforms. These computational platform provide valuable research tools to the scientific community. To ensure end users can make full use of the platform's capabilities, necessary software documentation is provided with these platforms. The two key forms of documentation SCEC strives to provide are detailed 'User Guides' and web-based, project 'Wiki' pages.

We are developing a set of standard software documentation for each SCEC software release. Our goal it that each public SCEC software release has both a wiki and file-based version of these documents, and both versions identical.

Standard Software documents:

• README
  • Contains statement of purpose of program, information about software history, links to web site for more information.
  • #Example README 1, #Example README 2, #Example README 3
• INSTALL
  • Information describing how to install the distribution.
• COPYING
  • This contains a license file summary
• AUTHORS
  • Contributor edited list of authors and their annotations on their contributions
• NEWS -- List of Changes in current release
• ChangeLog.txt
  • This contains a list of each previous NEWS file
• LICENSE
  • Copy of Apache 2 USC License
• Installation Guide.pdf
  • Detailed installation guide. May include alternative installation approaches not covered in INSTALL guide
• Tutorial.pdf
  • Step-by-step guide to "first use" of software. Provides, at a minimum, a simple example that describes how to use the platform for a simple problem.
• User Guide.pdf
  • This contains the full details for using the platform. Will include reference information on methods implemented in platform.
• Advanced User Guide.pdf (Optional)
  • User guide for advanced usage of the platform. This may include non-standard installation methods, features that are included but do not appeal to most users, advanced ways to manipulate data or code.
• Interface Control Document (ICD).pdf (API Definitions).pdf
  • Defines the external interfaces for the platform.
• File Format Definitions.pdf
  • Either as part of the ICD, define each file format used in external interfaces.
• Code docstrings or javadocs.pdf
  • links to embeded software comments and docs.
• Developer Guide.pdf
  • Information on adding new models to a platform

Standard Software Links

1. User email List:
2. SVN or Git address:
3. TRAC url:
4. Software Home Page:
5. Scec software help email address

Wiki Pages

Web-based documentation, Project Wiki pages, are hosted on SCECPedia, a collaborative wiki site for SCEC's Community Modeling Environment (CME). Wiki pages on SCECPedia are constantly updated and reflect the most current information on Scientific Projects and related code that is distributed by SCEC.

Project Wiki pages include:

• Description of the project.
• List of supporting materials:
  • Data formats.
  • Software platform requirements.
• Links to code download sites.
• Links to software defect reporting and tracking website.
• List of references.

Users are encouraged to explore SCECPedia to get a broad understanding of specific scientific projects and any related projects or codes.

User Guides

Detailed, version specific software documentation in the form of a User Guide is provided with each of scientific software platforms distributed by SCEC. User guides contain information required by the end user to install and use the software with ease. An online copy of this guide is maintained on the SCECPedia site.

User guides include:

• Information on how to download the software.
• Software requirements for running the scientific code:
  • Operating System and version.
  • Required compilers
  • Required supporting software tools and packages.
• Building the scientific code.
• Testing the built code.
• Running the built code.
• Various examples to illustrates available features.
• Software support contact information.
• Optional troubleshooting information.

Software Distribution Documentation

In order to maintain consistency between the online User Guides and PDF based documents distributed with the scientific codes, SCEC developers use automated scripts to convert Wiki based documentation to PDF documents.

To convert the Wiki User Guide to a PDF document, the general steps are:

• Download the Wiki User Guide HTML page (the printable version) with "wget"
• Change the character encoding in the HTML file
• Remove the Wiki site related HTML from header and footer of web page and insert desired header and footer HTML.
• Run htmldoc to produce the PDF in "book" format. The linux distribution can be downloaded from HTMLDOC project page.

Here is a sample conversion script taken from the CVM-H distribution:

#!/bin/bash

# make_pdf.sh - Create CVM-H User Guide PDF from Wiki page

# Filesnames
URL="http://scec.usc.edu/scecwiki/index.php?title=CVM-H_User_Guide&printable=yes"
DL_DIR="./scec.usc.edu"
URL_FILE="${DL_DIR}/scecwiki/index*"
HTML_FILE="${DL_DIR}/scecwiki/index.html"
HTML_TITLE="cvmh_manual_title.html"
PDF_FILE="../cvmh_manual.pdf"
TMP_FILE="tmp.html"
TMP_FILE2="tmp2.html"

# Header/footer to replace saved html
DOC_HDR='<HTML><META content="text/html; charset=iso-8859-1" http-equiv=Content-Type><BODY>'
DOC_FTR="</BODY></HTML>"

# Retrieve HTML and associated images from wiki
rm -rf ${DL_DIR}
wget --recursive --page-requisites --accept=".jpg,.png,*CVM*" -k -np ${URL}

# Convert from UTF-8 to ISO-8859 encoding
mv ${URL_FILE} ${HTML_FILE}
iconv --from-code=UTF-8 --to-code=ISO-8859-1 ${HTML_FILE} > ${TMP_FILE}
cp ${TMP_FILE} ${HTML_FILE}

# Insert page break hints
sed -i "s/<pre>/<!-- NEED 12 --><pre>/g" ${HTML_FILE}
sed -i "s/<table/<!-- NEED 12 --><table/g" ${HTML_FILE}

# Determine start/end lines to cut out from HTML
START_LINE=`grep -n -m 1 "<a name=\"Overview\" id=\"Overview\"></a>" ${HTML_FILE} | awk -F ':' '{print $1}'`
END_LINE=`grep -n -m 1 "Saved in parser" ${HTML_FILE} | awk -F ':' '{print $1}'`

# Perform cutting
head -n ${END_LINE} ${HTML_FILE} > ${TMP_FILE}
echo "${DOC_FTR}" >> ${TMP_FILE}
echo "${DOC_HDR}" > ${TMP_FILE2}
tail -n +${START_LINE} ${TMP_FILE} >> ${TMP_FILE2}

cp ${TMP_FILE2} ${HTML_FILE}

# Generate PDF book
htmldoc --firstpage p1 --fontsize 10.0 --titlefile ${HTML_TITLE} -f ${PDF_FILE} ${HTML_FILE}

rm ${TMP_FILE}
rm ${TMP_FILE2}

Example README 1

                   ------------------------------ 
                   GNU Image Manipulation Program
                         2.8 Stable Branch
                   ------------------------------

GIMP 2.8 replaces earlier GIMP 2.x versions. It is advised that you
uninstall them before installing GIMP 2.8. If you want to keep your
older GIMP 2.x installation in parallel to GIMP 2.8, you have to
choose a separate prefix which is not in your default library search
path. Otherwise your prevoius GIMP installation will start to use the
new libraries. You have been warned.

If you think you found a bug in this version, please make sure that it
hasn't been reported earlier and that it is not just new stuff that is
still being worked on and obviously not quite finished yet.

If you want to hack on GIMP, please read the file HACKING. For
detailed installation instructions, see the file INSTALL.


1. Web Resources
================

GIMP's home page is at:

	http://www.gimp.org/

Please be sure to visit this site for information, documentation,
tutorials, news, etc.  All things GIMP-ish are available from there.

The automated plug-in registry is located at:

	http://registry.gimp.org/

There you can get the latest versions of plug-ins, using a convenient
forms-based interface.

The latest version of GIMP can be found at:

	http://www.gimp.org/downloads/


2. Mailing Lists
================

We have several mailing lists dedicated to GIMP user and development
discussion.  There is more info at

	http://www.gimp.org/mail_lists.html

Links to several archives of the mailing lists are included in that page.

Gimp-user-list is a mailing list dedicated to user problems, hints and
tips, discussion of cool effects, etc.  Gimp-developer-list is oriented
to GIMP core and plug-in developers.  Most people will only want to be
subscribed to gimp-user-list. If you want to help develop GIMP, the
gimp-developer mailing list is a good starting point.


3. IRC
======

And finally, for the real junkies, there is an IRC channel devoted to
GIMP. On GIMPNet (a private free software oriented network) there is
#gimp.  Many of the developers hang out there.  Some of the GIMPNet
servers are:

	irc.gimp.org:6667
	irc.us.gimp.org:6667
	irc.eu.gimp.org:6667


4. Customizing
==============

The look of GIMP's interface can be customized like any other GTK app
by editing the ~/.gtkrc-2.0 file or by using "themes" (ready-made
customizations).  For downloadable themes and further details, see
http://art.gnome.org/themes/gtk2 . Additionally, GIMP reads the file
~/.gimp-2.8/gtkrc so you can have settings that only apply to GIMP.

Included is a set of keybindings similar to those in Adobe Photoshop.
You can find them in the ps-menurc file.  To use them, copy this file
to ~/.gimp-2.8/menurc. You can also manually change the keybindings to
any of your choice by editing ~/.gimp-2.8/menurc.


Have fun,

  Spencer Kimball
  Peter Mattis
  Federico Mena
  Manish Singh
  Sven Neumann
  Michael Natterer
  Dave Neary
  Martin Nordholts

Example README 2

OpenQuake is an open source application that allows users to
compute seismic hazard and seismic risk of earthquakes on a global scale.

Please note: the /usr/bin/openquake script requires a celeryconfig.py
file in the PYTHONPATH.  Please make sure this is the case and that your
celeryconfig.py file works with your python-celery setup.

Feel free to copy /usr/openquake/engine/celeryconfig.py and revise it as needed.

**Running tests**

*Short-running test suite*
  These tests should complete in about 5 minutes:
  $ nosetests --with-doctest tests/

*Shorter-running test suite*
  These tests should complete in about 1 minute:
  $ nosetests --with-doctest -a '!slow' tests/

*Full test suite*
  These tests including many long-running QA tests and can take ~1 hour to run:
  $ nosetests --with-doctest

Example README 3

Example README:

   -------------------- P R O J . 4 --------------------

This is Release 4.4 of cartographic projection software.

PLEASE read the following information as well as READMEs in the src
and nad directories.

For more information on PROJ.4 maintenance please see the web page at:

  http://www.remotesensing.org/proj
                or
  http://proj.maptools.org/

   ---------------------------------------------------

Installation:
-------------

FSF's configuration procedure is used to ease installation of the
PROJ.4 system.

The default destination path prefix for installed files is /usr/local.
Results from the installation script will be placed into subdirectories
bin, include, lib, man/man1 and man/man3.  If this default path prefix
is proper, then execute:

	./configure

If another path prefix is required, then execute:

	./configure --prefix=/my/path

In either case, the directory of the prefix path must exist and be
writable by the installer.

After executing configure, execute:

	make
        make install

The install target will create, if necessary, all required sub-directories.

Windows Build
-------------

PROJ.4 can be built with Microsoft Visual C/C++ using the makefile.vc
in the PROJ directory.  First edit the PROJ\nmake.opt and modify
the INSTDIR value at the top to point to the directory where
the PROJ tree shall be installed. If you want to install into
C:\PROJ, it can remain unchanged.
Then use the makefile.vc to build the software:

eg. 
C:\> cd proj
C:\PROJ> nmake /f makefile.vc
C:\PROJ> nmake /f makefile.vc install-all

Note that you have to have the VC++ environment variables, and path
setup properly.  This may involve running the VCVARS32.BAT script out
of the Visual C++ tree.  

The makefile.vc builds proj.exe, proj.dll and proj.lib. 

It should also be possible to build using the Unix instructions
and Cygwin32, but this hasn't been tested recently. 


   ---------------------------------------------------

Distribution files and format.
------------------------------

Sources are distributed in one or more files.  The principle elements
of the system are in a compress tar file named `PROJ.4.x.tar.gz' where
"x" will indicate level.sub-level of the release.  For U.S. users
interested in NADCON datum shifting procedures, additional files
containing conversion matricies are distributed with the name
`PROJ.4.x.y.tar' where y is an uppercase letter starting with "A."
These supplementary files will contain compressed files and thus
the tar file is not compressed.

Interim reports on Rel. 4 proj are available in PostScript form as
*.ps.gz .  New and old users are strongly recommended to carefully read
these manuals.  They are supplements and NOT a replacement for the full
manual OF 90-284 (which new users should also obtain).

   ---------------------------------------------------

Principle new aspects of system:
--------------------------------

ANSI X3.159-1989 C code.  Site must have ANSI C compiler and header files.

Several method of determining radius from specified ellipsoid.

Use of initialization files through +init=file:key.  Default projection
specifications also may be defined in an ASCII file.

+inv option REMOVED and -I may be used in its place.  Use of invproj
alias of proj still functions as per Rel.3.

+ellps=list and +proj=list REMOVED.  Use respective -le and -lp.

+units= to specify cartesian coordinate system units.  To get list
use -lu.

-v added to dump final cartographic parameters employed.

Addition of computing scale factors and angular distortion added through
-S option.  Valuable for designing new projection parameter details.

-V option which verbosely lists projected point characteristics.

Programmers may use projection library with calls to pj_init,
pj_fwd, pj_inv and pj_transform.

Program nad2nad for conversion of data to and from NAD27 and NAD83
datums.

Program cs2cs for converting between coordinate systems, with optional
datum translation.

-------------------------------------------------------------

Things currently left undone:
----------------------------

proj_def.dat NOT fully in place.  Needs additional settings for
many of the projections.  Probably will not be completed until main
manual rewritten.

See Also

• SCEC Software
• CME Project
• SEISM Project
• Geoinformatics Project