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.
• 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
• Installation Guide.pdf
• Tutorial.pdf
• User Guide.pdf
• API Definitions.pdf (interface control document)
• File Format Definitions.pdf
• Code docstrings or javadocs.pdf
• Developer Guide.pdf

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

See Also

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