riegler riegler@source.lon-capa.org
Mon, 23 Aug 2010 16:16:22 -0000

This is a MIME encoded message

--riegler1282580182
Content-Type: text/plain

riegler		Mon Aug 23 16:16:22 2010 EDT

Modified files:
/doc/help	course.manual.texxml
Log:

Updating chapter 15 of cc manual.

--riegler1282580182
Content-Type: text/plain
Content-Disposition: attachment; filename="riegler-20100823161622.txt"

@@ -3,13 +3,15 @@
In the assessment-level spreadsheet, the parameters are available for
calculation in three ways.

-1. Reference the cell containing the parameter: \texttt{A7}
+\begin{enumerate}
+\item Reference the cell containing the parameter: \texttt{'A7'}

-2. Reference the parameter by name: \texttt{[parameter\_0\_weight]}
+\item Reference the parameter by name: \texttt{'[parameter\_0\_weight]'}

In each of these two cases, the value of the parameter will replace the
reference before the Perl code in the cell is executed.

-3. Use the \texttt{\&PARM()} function, this will get run as part of the perl
+\item Use the \texttt{&PARM()} function, this will get run as part of the perl
code evaluation.
+\end{enumerate}

@@ -2,9 +2,11 @@

\textbf{Cells}

-Cells may be specified by simply writing their name.  \texttt{A17} will be
-replaced with the value in row A column 17 before the Perl is evaluated.
+Cells may be specified by simply writing their name enclosed in either single quotes or double quotes.
+For instance, \texttt{'A17'} and \texttt{"A17"} will be
+replaced with the value in row $A$ column 17 before the Perl command is evaluated.

+\noindent
\textbf{Ranges}

Ranges \index{ranges, spreadsheet} specify rectangles of various shapes
@@ -13,21 +15,21 @@

\begin{itemize}

-\item \textbf{*''} - all rows, all columns
-\item \textbf{B*''} - all rows in column B
-\item \textbf{*5''} - all columns in row 5
-\item \textbf{C5''..F25''} - all cells in the rectangle between C5 and F25
+\item \texttt{'*'} - all rows, all columns
+\item \texttt{'B*'} - all rows in column B
+\item \texttt{'*5'} - all columns in row 5
+\item \texttt{'C5'..'F25'} - all cells in the rectangle between C5 and F25

\end{itemize}

-Many functions accept ranges. For example, \&SUM(d*'') will add
-up all cells in column d.
+Many functions accept ranges, see \ref{Spreadsheet_Functions}. For example, \texttt{\&SUM('d*')} will add up all cells in column $d$.

+\noindent
\textbf{Special References}

There is an additional means of referencing cells most used in the
-By using a \#'' in the place of a row number
+By using a '\#' in the place of a row number
the spreadsheet will replace the \# with the current row number.  For example
-\texttt{B\#} will be replaced with the contents of cell B7 in the row 7 and
-the contents of B8 in row 8.
+\texttt{'B\#'} will be replaced with the contents of cell $B7$ in the row 7 and
+the contents of $B8$ in row 8.
@@ -1,16 +1,17 @@

-To edit a cell in the spreadsheet, move you mouse pointer over it until you
+To edit a cell in the spreadsheet, move your mouse pointer over it until you
The current contents of the cell will be shown and can be modified.
-Pressing the Accept'' button will cause the spreadsheet to be updated with
+Pressing the \fbox{Accept} button will cause the spreadsheet to be updated with
the new formula.
You will then be working with an unsaved modified copy of a spreadsheet.
-Pressing the Discard Changes'' button will discard any changes you have
made to the contents of the cell.

+\noindent
\textbf{What goes in a cell}

The cells of the spreadsheet contain a mixture of Perl commands and LON-CAPA
@@ -3,37 +3,41 @@
If you have permission to edit a spreadsheet you will also have permission to

+\noindent

There are three default spreadsheets, one for each level.  These are called
\texttt{default\_classcalc}, \texttt{default\_studentcalc}, and
\texttt{default\_assesscalc}.
-These are the starting spreadsheets for every class.

+These are the starting spreadsheets for every class.
+\noindent

When you modify a spreadsheet you begin working with an temporary copy.
-You may save the spreadsheet using the Save as''
-button on the spreadsheet.  Fill in a name and click on the Save as'' button.
-You may also use the Save as \& Make This Sheet the Default'' button
+You may save the spreadsheet using the \fbox{Save as}
+button on the spreadsheet.  Fill in a name and click on the \fbox{Save as} button.
+You may also use the \fbox{Save as \& Make This Sheet the Default} button
to set the current spreadsheet definition as the default for this level.

+\noindent

-Using the Select Spreadsheet File'' link opens the LON-CAPA resource browser.
Only files with the extension \texttt{spreadsheet} can be selected.  The
spreadsheet definition file must be valid XML. (You must be author to create and publish a spreadsheet file \ref{Authoring_Spreadsheet}.)

+\noindent

In the student level spreadsheet every assessment in the course has a
spreadsheet definition file associated with it.
The spreadsheet definition used for each assessment
Initially this spreadsheet is Default'', meaning the current default

Changing the spreadsheet used for an assessment modifies the student level
-spreadsheet, so you must use the Save as'' button to save the current
+spreadsheet, so you must use the \textbf{Save as} button to save the current

@@ -5,6 +5,7 @@
The following sections describe the consequences
of this and answer why are the rows of the spreadsheet out of order?''.

+\noindent

Every parameter associated with an assessment has a unique row in the
@@ -15,6 +16,7 @@
of the assessments in the course, there are likely to be a large number of
parameters available.

+\noindent

@@ -24,6 +26,7 @@
Regardless of the row number, the assessment will appear in the proper place
in the course structure.

+\noindent

The rows of the course spreadsheet are assigned to students as they are
@@ -1,7 +1,8 @@

-You can create a spreadsheet XML file to import into your course.  The file must be named with the extension .spreadsheet.  Example:
-\begin{verbatim} <field col=A row=0>'Available Points:'</field>
+As an author you can create a spreadsheet XML file to import into your course.  The file must be named with the extension .spreadsheet.  Example:
+\begin{verbatim}
+<field col=A row=0>'Available Points:'</field>
<field col=B row=0>&SUM('X*')</field>
<field col=C row=0>'Awarded Points:'</field>
<field col=D row=0>&SUM('Z*')</field>
@@ -1,34 +1,37 @@

This section describes the layout of each level of spreadsheet.  See the
for a description of the types of spreadsheets and their data-flow
relationships.

+\noindent
\textbf{General Characteristics}

Each spreadsheet has 52 columns and a variable number of rows.
The columns of the spreadsheets are labeled 'A-z'.
The rows of the spreadsheets contain data appropriate to the spreadsheet as
-described below.  The section \textbf{Spreadsheet Row Numbers}
+described below.  The section Spreadsheet Row Numbers
(\ref{Spreadsheet_Row_Numbers}) describes how row numbers are assigned.

+\noindent

There are two special rows on the top of the assessment spreadsheet.
-The first is the \textbf{template row} (\ref{Spreadsheet_Template_Row}).
-The second row is the \textbf{export row} (\ref{Spreadsheet_Export_Row}).
+The first is the template row (\ref{Spreadsheet_Template_Row}).
+The second row is the export row (\ref{Spreadsheet_Export_Row}).

The main body of the assessment spreadsheet contains the parameters associated
with the assessment.  The parameter values appear in the A'' column of the
labeled B-z'', can be edited and used for computations.

on how to reference a parameter value in the spreadsheet.

+\noindent

The student spreadsheet has both a
@@ -41,6 +44,7 @@
main body of the spreadsheet, A-Z'', are the export data from the assessments
and cannot be edited.  The remaining columns, a-z'', can be edited.

+\noindent

The course spreadsheet contains the data exported from each student level
@@ -52,3 +56,4 @@
first 26 columns, A-Z'', contain the student data and cannot be edited.
The remaining 26 columns a-z'', can be edited.
+
@@ -7,5 +7,5 @@
If a cell in the spreadsheet already has a value, that value will be preserved.

Using the \#'' notation to specify rows is recommended.  See
@@ -1,7 +1,7 @@

The export row determines what information is passed to the next higher
The first 26 columns of the row, labeled A-Z'', are
exported.  The remaining 26 columns, labeled a-z'',
@@ -1,15 +1,18 @@
-The course spreadsheet has three levels.

+The course spreadsheet has three levels.
The top-level is the "course level" sheet, which is not accessible to
students. It lists the export rows of all "student level" sheets (the
-sheet that students get to see when they press "GRDS"). These in turn
-import the export rows of all assessment level sheets.
+sheet that students get to see when they press
+\includegraphics[width=0.03\paperwidth]{feedback}
+\textbf{View current problem status and grading information}
+These in turn import the export rows of all assessment level sheets.

The figure shows the spreadsheet hierarchy.

\begin{figure}
\end{center}
-\end{figure}
\ No newline at end of file
+\end{figure}
@@ -12,3 +12,8 @@
For help creating and editing spreadsheets, see
+
+To access the spreadsheet functionality select
+\includegraphics[width=0.03\paperwidth]{sprs}
@@ -14,18 +14,16 @@

For example, for the above assessment with three parts,

-\texttt{\&EXPANDSUM(}\texttt{\textbf{PART}}\texttt{;parameter\_}\texttt{\textbf{PART}}\texttt{\_weight{*}stores\_}\texttt{\textbf{PART}}\texttt{\_awarded)}
-
+\texttt{\&EXPANDSUM(}\texttt{\textbf{PART}}\texttt{;parameter\_}\texttt{\textbf{PART}}\texttt{\_weight{*}stores\_}\texttt{\textbf{PART}}\texttt{\_awarded)}\\
would become
-
\texttt{parameter\_0\_weight{*}stores\_0\_awarded +}~\\
\texttt{parameter\_11\_weight{*}stores\_11\_awarded +}~\\
\texttt{parameter\_12\_weight{*}stores\_12\_awarded +}~\\
\texttt{parameter\_13\_weight{*}stores\_13\_awarded +}~\\
-
where \textbf{bolded text} is used to highlight what the
\texttt{\&EXPANDSUM} function is doing.

+\noindent
\textbf{What 'tries' means}

In multi-part questions, the exported value for "tries"\index{tries} is now
@@ -4,14 +4,16 @@

To take the sum of column M'', for example, use \texttt{\&SUM(M*'')}\index{SUM}

+\noindent
+
When you have a list of numbers in a cell, how it is displayed depends
on how you separate the numbers and how Perl interprets the results.

-\textbf{35 45 12} will not generate any result because this is an
+\texttt{35 45 12} will not generate any result because this is an
invalid Perl statement.

-\textbf{35,45,12} will have a result of 12 because Perl has a comma
+\texttt{35,45,12} will have a result of 12 because Perl has a comma
operator similar to the comma operator\index{comma operator} in C.

The comma operator is binary and returns the value on its right. Thus
@@ -1,6 +1,6 @@
The following special functions are available in the spreadsheet.
for information on specifying cells and ranges.

\begin{itemize}
@@ -32,16 +32,16 @@
range
\index{MIN}

-\item \texttt{\&SUMMAX(n ,range)} - sum of the maximum n non-empty
+\item \texttt{\&SUMMAX(n ,range)} - sum of the maximum $n$ non-empty
cells in range
\index{SUMMAX}

-\item \texttt{\&SUMMIN(n, range)} - sum of the minimum n non-empty
+\item \texttt{\&SUMMIN(n, range)} - sum of the minimum $n$ non-empty
cells in range
\index{SUMMIN}

-Use \&EXT(system.time'') to retrieve the current time.
+Use \texttt{\&EXT('system.time')} to retrieve the current time.
\index{EXT}

\item \texttt{\&PARM(parameter)} - get the value of a specific parameter
@@ -54,25 +54,25 @@

\item \texttt{\&MAXPARM(expression)} -  get the value of a parameter that
matches the expression that is the largest in value (If one specified
-'opendata' it would return the largest opendate set on the problem.)
+'opendate' it would return the largest opendate set on the problem.)
\index{MAXPARM}

\item \texttt{\&SUMSEQ(column,sequence1,sequence2,sequence3,...)} -
sum the given column across the folders or sequences listed.

When specifying a sequence use the full title.  Instead of a sequence title
-the word all'' can be used to sum over all sequences.  Regular expressions
-can be entered as well, if prefixed by regexp:''.  See below for examples.
+the word \texttt{all} can be used to sum over all sequences.  Regular expressions
+can be entered as well, if prefixed by \texttt{regexp:}.  See below for examples.

\begin{itemize}

-\item \texttt{\&SUMSEQ(Z'',''Chapter 1'');}
+\item \texttt{\&SUMSEQ('Z','Chapter 1');}

-\item \texttt{\&SUMSEQ(Z'',''Chapter 1'',''Chapter 2'',''Chapter 3'');}
+\item \texttt{\&SUMSEQ('Z','Chapter 1','Chapter 2','Chapter 3');}

-\item \texttt{\&SUMSEQ(Z'',''all'');} - sum over all sequences.
+\item \texttt{\&SUMSEQ('Z','all');} - sum over all sequences.

-\item \texttt{\&SUMSEQ(Z'',''regexp:Large Biomolecules'');} -
+\item \texttt{\&SUMSEQ('Z','regexp:Large Biomolecules');} -
sum over all sequences which match the regular expression
/Large Biomolecules/.

@@ -1,9 +1,8 @@
-If you set a course parameter \ref{Course_Setting_Parameters},
-you can access this parameter in the spreadsheet
-\index{spreadsheet, course parameter in}. To access the
-parameter 'testparm' use

+If you set a course parameter (see \ref{Course_Setting_Parameters}),
+you can access this parameter in the
+parameter 'testparm' use
\texttt{\&EXT('course.testparm')}\index{EXT}
-
Index: doc/help/course.manual.texxml
diff -u doc/help/course.manual.texxml:1.31 doc/help/course.manual.texxml:1.32
--- doc/help/course.manual.texxml:1.31	Mon Aug 23 11:37:29 2010
+++ doc/help/course.manual.texxml	Mon Aug 23 16:16:22 2010
@@ -352,6 +352,12 @@
<subsubsection name="Template Row">
</subsubsection>
+		<subsubsection name="Row Numbers">