SBML.org — the global portal for all things SBML

Page Template

Contents

Template version 1.1 (16 December 2008).

This is the recommended outline to follow for wiki pages describing a community-contributed utility program or script. The green-colored comment text is informational only and not meant to be left in the final text of a page.

Case #1: code presented verbatim on the page

This is the case where you have a short script or program and don't provide it as a file, instead simply presenting the literal text of the script or program on the web page. The script validateSBML.py is an example. To use this outline, first read the rest of this section for guidance, then (1) copy the text in the following box, (2) paste it into a new wiki page, and (3) fill in the content of the page. Please refer to our wiki help page for information about the wiki syntax and features of sbml.org.

{{ProgramPageBox
| name = 
| language =
| summary = 
| authors = 
| version = 
| needs = 
| location = page
}} 
== Description ==

== Code ==

<pre>
... your code here ...
</pre>

== Usage ==

== Known problems/issues ==

== Licensing terms and distribution ==


The following is an explanation of the content that should go into each part of the page. The first component is the ProgramPageBox, which is a macro template that takes text and formats it in a certain way on the finished page. It has several variables that need to be given values. The meanings are as follows:

{{ProgramPageBox
| name = Name
| language = Scripting or programming language
| summary = Very brief summary of what it does
| authors = Author names and email addresses
| version = Version number (date in parentheses)
| needs = Libraries or packages that this depends on (e.g., libSBML version x, MATLAB version x)
| location = page
}}

The meanings of the variables in ProgramPageBox are hopefully explained clearly enough above. One clarification worth making here is that location = page is the literal text that should be written for this case. (The location variable is given a different value in the second case described below.)

Next, the == Description == section of the page provides a place to write a longer and more detailed explanation of what the program or script does.

In the == Code == section, please put the text of your program. Wrap the program text inside <pre> and </pre> tags.

In the == Usage == section, please provide clear step-by-step instructions and examples for running the software. It's useful to provide exact command line text, screen captures, or other explicit information.

In the == Known problems/issues == section, you may list anything that a user might want to know about the limitations of the software.

Finally, in the == Licensing terms and distribution == section, please describe the distribution license under which the software is being released and any conditions or notes concerning the distribution of the software.

Case #2: code stored in files for downloading

This is the case where you provide one or more files to download. To use this outline, first read the rest of this section for guidance, then (1) copy the text in the following box, (2) paste it into a new wiki page, and (3) fill in the content of the page. Please refer to our wiki help page for information about the wiki syntax and features of sbml.org.

{{ProgramPageBox
| name = 
| language =
| summary = 
| authors = 
| version = 
| needs = 
| location = 
}} 
== Description ==

== Installation instructions ==

== Usage ==

== Known problems/issues ==

== Licensing terms and distribution ==


The following is an explanation of the content that should go into each part of the page. The first component is the ProgramPageBox, which is a macro template that takes text and formats it in a certain way on the finished page. It has several variables that need to be given values. The meanings are as follows:

{{ProgramPageBox
| name = Name
| language = Scripting or programming language
| summary = Very brief summary of what it does
| authors = Author names and email addresses
| version = Version number (date in parentheses)
| needs = Libraries or packages that this depends on (e.g., libSBML version x, MATLAB version x)
| location = Either the word "svn", or a wiki-style link of the form [URL title] to where the code may be found
}}

In this case, the location variable interacts with the name variable in the following way:

  • If the value of location is the string "svn", it means that the program can be found in the Subversion repository for SBML on SourceForge.net. It's expected that the name is both the name of the program and the literal name of the SVN subdirectory in which the program is located. The ProgramPageBox uses this name to format links to the SVN directory in the finished page. (Note that if the directory name and program name do not match, the links will not work properly.)
  • If the value of location is neither the string "svn" nor the string "page" (see the section above), it's assumed to be a link to where the code for the program can be found. This can be anything you wish to use (another website, a private code repository, whatever). The ProgramPageBox will put this link in the finished description. Make sure to use wiki-style links (meaning, use [URL title]), because raw URLs are left as-is and the resulting formatting is very ugly.

The rest of the variables in ProgramPageBox are hopefully explained well enough above.

Next, the == Description == section of the page provides a place to write a longer and more detailed explanation of what the program or script does.

In the == Installation instructions == section, please describe step-by-step how someone should install your script/program and get it running.

In the == Usage == section, please provide clear step-by-step instructions and examples for running the software. It's useful to provide exact command line text, screen captures, or other explicit information.

In the == Known problems/issues == section, you may list anything that a user might want to know about the limitations of the software.

Finally, in the == Licensing terms and distribution == section, please describe the distribution license under which the software is being released and any conditions or notes concerning the distribution of the software.

Complete example of using the templates

To illustrate and clarify how the two outlines above should be used and where your actual text should go on the page, the following shows the complete content of an example page using this template:

{{ProgramPageBox
| name = echoSBML.py
| language = Python
| summary = Simple program that writes out the SBML file given to it as input.
| authors = Mike Hucka (mhucka AT caltech.edu)
| version = 1.0 (16 Dec. '08)
| needs = [[Software/libSBML | libSBML]] version 3
| location = svn
}}
== Description ==
 
This is a simple demonstration program that takes two arguments.  The first 
argument is a path to a file presumed to be in SBML format, and the second 
is a path to a destination file.  This program reads the input file using libSBML 
and writes it to the destination file.  As a consequence of the fact that it uses 
libSBML, the resulting text is also reformatted and pretty-printed.

== Installation instructions == 
 
# Install [[Software/libSBML | libSBML]] if you have not already done so.
# Find a location in your file system where you want to copy the files.
# Copy the SVN link (see box at right) and use it in your SVN client to 
check out a copy of the files.
# Change your working directory (in your shell or whatever you're doing) to 
the <tt>echoSBML</tt> directory that you checked out from SVN.
# Make sure to set up your environment variables (e.g., <tt>PYTHONPATH</tt>) 
as needed for your installation of Python. See 
the [http://sbml.org/Software/libSBML/docs/python-api/ libSBML documentation] 
for more information.

== Usage == 
 
<pre>
echoSBML.py  /path/to/input/file/name.xml  /path/to/output/file.xml
</pre>

== Known problems/issues ==

None.

== Licensing terms and distribution ==

This software is released under the terms of the [http://sbml.org/software/COPYING.html LGPL].

You can visit the echoSBML.py page to see the finished result.

Retrieved from "http://sbml.org/Community/Programs/Page_Template"

This page was last modified 15:48, 23 March 2009.



Please use our issue tracking system for any questions or suggestions about this website. This page was last modified 15:48, 23 March 2009.