Difference between revisions of "Software Documentation"
| Line 40: | Line 40: | ||
* Optional troubleshooting 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 | + | 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 [http://www.htmldoc.org/ HTMLDOC project page]. | ||
| + | |||
| + | |||
| + | Here is a sample conversion script taken from the CVM-H distribution: | ||
| + | |||
| + | <pre> | ||
| + | #!/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} | ||
| + | </pre> | ||
== See Also == | == See Also == | ||
*[[SCEC Software]] | *[[SCEC Software]] | ||
Revision as of 03:24, 19 February 2011
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.
Contents
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.
Types of Documentation
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}
