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:

1. README

• • Contains statement of purpose of program, information about software history, links to web site for more information.

1. INSTALL

• • Information describing how to install the distribution.

1. COPYING

• • This contains a license file summary

1. AUTHORS

• • Contributor edited list of authors and their annotations on their contributions

1. NEWS -- List of Changes in current release
2. LICENSE
3. ChangeHistory.txt --
4. Installation Guide.pdf
5. Tutorial.pdf
6. User Guide.pdf
7. API Definitions.pdf (interface control document)
8. File Format Definitions.pdf
9. Code docstrings or javadocs.pdf
10. 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}

See Also

• SCEC Software