[Swift-commit] r2907 - trunk/docs
noreply at svn.ci.uchicago.edu
noreply at svn.ci.uchicago.edu
Thu May 7 10:08:09 CDT 2009
Author: benc
Date: 2009-05-07 10:08:09 -0500 (Thu, 07 May 2009)
New Revision: 2907
Modified:
trunk/docs/userguide.xml
Log:
Userguide editing
Modified: trunk/docs/userguide.xml
===================================================================
--- trunk/docs/userguide.xml 2009-05-07 14:49:59 UTC (rev 2906)
+++ trunk/docs/userguide.xml 2009-05-07 15:08:09 UTC (rev 2907)
@@ -27,10 +27,11 @@
</para>
<para>
SwiftScript programs are dataflow oriented - they are primarily
-concerned with processing (possibly large) data files, by invoking
-programs to do that processing. Swift handles execution of such programs
-on remote sites by choosing sites, handling the staging of input and output
-files to and from the chosen sites and remote execution of program code.
+concerned with processing (possibly large) collections of data files,
+by invoking programs to do that processing. Swift handles execution of
+such programs on remote sites by choosing sites, handling the staging
+of input and output files to and from the chosen sites and remote execution
+of program code.
</para>
</section>
<section id="language">
@@ -43,7 +44,9 @@
</para>
<para>
Data is represented in a script by strongly-typed single-assignment
-variables, using a C-like syntax.
+variables. The syntax superficially resembles C and Java. For example,
+<literal>{</literal> and <literal>}</literal> characters are used to
+enclose blocks of statements.
</para>
<para>
Types in Swift can be <firstterm>atomic</firstterm> or
@@ -76,13 +79,6 @@
</programlisting>
<para>
-Conceptually, a parallel can be drawn between Swift mapped variables
-and Java reference types. In both cases there is no syntactic distinction
-between primitive types and mapped types or reference types respectively.
-Additionally, the semantic distinction is also kept to a minimum.
-</para>
-
-<para>
Component programs of scripts are declared in an <firstterm>app
declaration</firstterm>, with the description of the command line syntax
for that program and a list of input and output data. An <literal>app</literal>
@@ -120,7 +116,7 @@
</para>
<para>
-The examples above have used the type <literal>image</literal> with out any
+The examples above have used the type <literal>image</literal> without any
definition of that type. We can declare it as a <firstterm>marker type</firstterm>
which has no structure exposed to SwiftScript:
</para>
@@ -254,7 +250,7 @@
<para>while in this fragment, execution is serialised by the variable
<literal>y</literal>, with procedure <literal>p</literal> executing
-before <literal>q</literal>:</para>
+before <literal>q</literal>.</para>
<programlisting>
y=p(x);
@@ -262,11 +258,13 @@
</programlisting>
<para>
-Arrays in SwiftScript are more generally
-<firstterm>monotonic</firstterm>; that is, knowledge about the
+Arrays in SwiftScript are more
+<firstterm>monotonic</firstterm> - a generalisation of being
+assignment. Knowledge about the
content of an array increases during execution, but cannot otherwise
-change. Each element of the array is single assignment.
-Eventually, all values for an array are known, and that array
+change. Each element of the array is itself single assignment or monotonic
+(depending on its type).
+During a run all values for an array are eventually known, and that array
is regarded as <firstterm>closed</firstterm>.
</para>
@@ -515,7 +513,7 @@
</section>
<section>
- <title>Syntax</title>
+ <title>More technical details about SwiftScript</title>
<para>The syntax of SwiftScript has a superficial resemblance to C and
Java. For example, { and } characters are used to enclose blocks of
statements.
@@ -810,8 +808,7 @@
Swift provides a number of mappers that are useful in common cases. This
section details those standard mappers. For more complex cases, it is
possible to write application-specific mappers in Java and
-use them within a SwiftScript program. For more information on writing
-an application specific mapper, see the tutorial module on mappers.
+use them within a SwiftScript program.
</para>
<section id="mapper.single_file_mapper"><title>The single file mapper</title>
@@ -1348,8 +1345,15 @@
</section>
</section>
+ <section id="commands"><title>Commands</title>
+ <para>
+The commands detailed in this section are available in the
+<filename>bin/</filename> directory of a Swift installation and can
+by run from the commandline if that directory is placed on the
+PATH.
+ </para>
<section id="swiftcommand">
- <title>The swift command</title>
+ <title>swift</title>
<para>
The <command>swift</command> command is the main command line tool
for executing SwiftScript programs.
@@ -1487,6 +1491,70 @@
</para>
</section>
</section>
+
+ <section><title>swift-log-to-cedps</title></section>
+ <section><title>swift-osg-ress-site-catalog</title>
+ <para>
+The <command>swift-osg-ress-site-catalog</command> command generates a site
+catalog based on <ulink url="http://www.opensciencegrid.org/">OSG</ulink>'s
+ReSS information system (since Swift 0.9)
+ </para>
+ <para>
+Usage: <command>swift-osg-ress-site-catalog [options]</command>
+ </para>
+ <variablelist>
+ <varlistentry><term>--help</term>
+ <listitem>
+<para>Show help message</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>--vo=[name]</term>
+ <listitem>
+<para>Set what VO to query ReSS for</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>--engage-verified</term>
+ <listitem>
+<para>Only retrieve sites verified by the Engagement VO site
+verification tests This can not be used together with <literal>--vo</literal>,
+as the query will only work for sites advertising support for the
+Engagement VO.</para>
+
+<para>This option means information will be retrieved from the
+Engagement collector instead of the top-level ReSS collector.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>--out=[filename]</term>
+ <listitem>
+<para>Write to [filename] instead of stdout</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+
+ </section>
+
+
+ <section><title>swift-plot-log</title>
+ <para>
+<command>swift-plot-log</command> generates summaries of Swift run log
+files.
+ </para>
+ <para>
+Usage: <command>swift-plot-log [logfile] [targets]</command>
+ </para>
+ <para>
+When no targets are specified, <command>swift-plog-log</command> will
+generate an HTML report for the run. When targets are specified, only
+those named targets will be generated.
+ </para>
+ </section>
+
+ </section>
<section id="appmodel"> <title>Executing <literal>app</literal> procedures</title>
<para>
This section describes how Swift executes <literal>app</literal> procedures,
@@ -1670,7 +1738,7 @@
</section>
<section><title>
-notes on how swift implements file input and output
+How Swift implements the site execution model
</title>
<para>
@@ -1741,7 +1809,7 @@
</para></listitem>
<listitem><para>
-<filename>jobs/</filename> //application workspace directories// (optionally placed here -
+<filename>jobs/</filename> - application workspace directories (optionally placed here -
see below)
</para></listitem>
</itemizedlist>
@@ -1774,7 +1842,7 @@
<para>
The Swift client side then checks for the presence of and deletes a status
-file indicating success; copies files from the site shared directory to
+file indicating success; and copies files from the site shared directory to
the appropriate client side location.
</para>
@@ -2508,7 +2576,7 @@
The generated dot file can be rendered
into a graphical form using
<ulink
- url="http://www.graphviz.org">Graphviz</ulink>,
+ url="http://www.graphviz.org/">Graphviz</ulink>,
for example with a command-line such as:
</para>
<screen>
@@ -3002,6 +3070,17 @@
<section id="profiles"><title>Profiles</title>
+ <para>
+Profiles are configuration parameters than can be specified either for
+sites or for transformation catalog entries. They influence the behaviour
+of Swift towards that site (for example, by changing the load Swift will
+place on that sites) or when running a particular procedure.
+ </para>
+ <para>
+Profile entries for a site are specified in the site catalog. Profile
+entries for specific procedures are specified in the transformation
+catalog.
+ </para>
<section id="profile.karajan"><title>Karajan namespace</title>
<para id="profile.karajan.maxsubmitrate"><literal>maxSubmitRate</literal> limits the maximum rate of job submission, in jobs per second.
For example:
@@ -3695,36 +3774,6 @@
mpirun command should be explicitly invoked.
</para>
</section>
- <section id="tips.osg"><title>Generating a sites.xml for OSG</title>
- <para>
-The Swift distribution contains a command
-<command>swift-osg-ress-site-catalog</command> that can generate a site
-catalog based on OSG's ReSS information system (since Swift 0.9)
- </para>
-
- <screen>
-Usage:
- swift-osg-ress-site-catalog [options]
-
-Options:
- --help Show this help message
-
- --vo=[name]
- Set what VO to query ReSS for
-
- --engage-verified
- Only retrieve sites verified by the Engagement VO site
- verification tests This can not be used together with --vo, as
- the query will only work for sites advertising support for the
- Engagement VO.
-
- This option means information will be retrieved from the
- Engagement collector instead of the top-level ReSS collector.
-
- --out=[filename]
- Write to [filename] instead of stdout
- </screen>
- </section>
</section>
More information about the Swift-commit
mailing list