# [LON-CAPA-cvs] cvs: loncom /html/adm/help/tex Authoring_DataResponse.tex Authoring_ExternalResponse.tex Authoring_Foil_Structure_Tags.tex Authoring_Hint_Tags.tex Authoring_ImageResponse.tex Authoring_Input_Tags.tex Authoring_Internal_Tags.tex Authoring_NumericalResponse.tex Authoring_OptionResponse.tex Authoring_Output_Tags.tex Authoring_RadiobuttonResponse.tex Authoring_Response_Attributes.tex Authoring_Response_Tag_Intro.tex Authoring_Responseparam_Parameter.tex Authoring_Scripting_Tags.tex Authoring_Structure_Tags.tex Authoring_XML_Intro.tex Authoring_XML_Intro.tex~ Script_Functions.tex Script_Variables.tex

bowersj2 lon-capa-cvs@mail.lon-capa.org
Tue, 10 Jun 2003 19:29:26 -0000

This is a MIME encoded message

--bowersj21055273366
Content-Type: text/plain

bowersj2		Tue Jun 10 15:29:26 2003 EDT

Authoring_ExternalResponse.tex
Authoring_Foil_Structure_Tags.tex
Authoring_Hint_Tags.tex
Authoring_ImageResponse.tex
Authoring_Input_Tags.tex
Authoring_Internal_Tags.tex
Authoring_NumericalResponse.tex
Authoring_OptionResponse.tex
Authoring_Output_Tags.tex
Authoring_Response_Attributes.tex
Authoring_Response_Tag_Intro.tex
Authoring_Responseparam_Parameter.tex
Authoring_Scripting_Tags.tex
Authoring_Structure_Tags.tex
Authoring_XML_Intro.tex
Authoring_XML_Intro.tex~
Script_Functions.tex Script_Variables.tex
Log:
homework5.html chunked up with authoring information

--bowersj21055273366
Content-Type: text/plain
Content-Disposition: attachment; filename="bowersj2-20030610152926.txt"

\label{Authoring_DataResponse}

\textbf{dataresponse} is an advanced type of response tag that implements
a simple data storage, and needs an input tag like textline to work
correctly. Possible attributes are:

\begin{itemize}
\item \textbf{name}\index{name}: An internal name for the value, it will
have the part id and response id added to it.
\item \textbf{type}\index{type}: type of data stored in this response field,
should be one of the types supported by parameter.html
\item \textbf{display}\index{display}: a string that will be used to describe
the field when interfacing with humans
\end{itemize}

\label{Authoring_ExternalResponse}

\textbf{externalresponse} is an advanced type of response tag that
implements the ability to have an external program grade a response.
It expects either a \textbf{textline} or \textbf{textfield} inside
the tag. Possible attributes are:

\begin{itemize}
\item \textbf{url}\index{url}: the url to submit the answer form to. Does
not need to be a LON-CAPA machine.
\item \textbf{answer}\index{answer}: a string or scalar variable that can
encode something that should encode the correct answer. In some cases
this may be nothing.
\item \textbf{form}\index{form}: a hash variable name that will be submitted
to the remote site as a HTTP form.
\end{itemize}
The response of the remote server needs to be in XML as follows:

\begin{itemize}
must surround the response.
\item \textbf{awardetail}\index{awardetail}: required. The delimited text
inside must be one of the detailed results that appears in the data
storage documentation. CVS:loncapa/doc/homework/datastorage, look
for \textbf{resource.partid.responseid.awarddetail}.
\item \textbf{message}\index{message}: optional message to have shown to
the student
\end{itemize}
<awardetail>INCORRECT</awardetail>
<message>
A message to be shown to the students
</message>
\end{verbatim}

\label{Authoring_Foil_Structure_Tags}

All tags that implement a foil structure have an optional arg of \emph{max}
that controls the maximum number of total foils to show.

\begin{itemize}
\item \textbf{foilgroup}\index{foilgroup}: required. Must surround all
foil definitions.
\item \textbf{foil}\index{foil}: required. The foil is defined by what
is delimited by the \textbf{foil} tag.
\item \textbf{conceptgroup}\index{conceptgroup}: optional. Surrounds a
collection of \textbf{foil}. When a problem is displayed, only one
of the contained \textbf{foil} is selected for display. It has one
required attribute \textbf{concept}.
\end{itemize}

\label{Authoring_Hint_Tags}

All of these tags must appear inside a \textbf{}response tag.

\begin{itemize}
\item \textbf{hintgroup}\index{hintgroup}: Tag that surrounds all of a
hint.
\item \textbf{hintpart}\index{hintpart}: required. Tag to implement conditional
hints. It has a required argument \textbf{on}. When a hint tag named
the same as the \textbf{on} attribute evaluates to be correct, the
\textbf{hintpart} will show. If no other \textbf{hintpart} are to
show then all hintparts with an \textbf{on} value set to {}\textbf{default}''
will show
\item \textbf{numericalhint}\index{numericalhint}: Has all the arguments
that \textbf{numericalresponse} does, and the required attribute \textbf{name}
which should be set to the value of which \textbf{hintpart} will be
shown.
\item \textbf{stringhint}\index{stringhint}: Has all the arguments that
\textbf{stringresponse} does, and the required attribute \textbf{name}
which should be set to the value of which hintpart will be shown.
\item \textbf{formulahint}\index{formulahint}: Has all the arguments that
formularesponse does, and the required attribute \textbf{name} which
should be set to the value of which hintpart will be shown.
\item \textbf{optionhint}\index{optionhint}: The required attribute \textbf{name}
should be set to the value of which \textbf{hintpart} will be shown.
\textbf{name} should be set to the value of which \textbf{hintpart}
will be shown, and the attribute \textbf{answer} should be a two element
list, first the type (\textbf{foil} or \textbf{concept}) and then
either the foil's name or the concept's string.
\end{itemize}

\label{Authoring_ImageResponse}

\textbf{imageresponse} implements a image-click answer. \textbf{imageresponse}
tags should contain a \textbf{foilgroup} tag, containing \textbf{foil}
tags, where each \textbf{foil} tag can contain:

\begin{itemize}
\item \textbf{image}\index{image}: required. The delimited text should
correspond to a published image resource. Example: \texttt{<image>/res/adm/includes/templates/man1.jpg</image>}.
Should only appear once per foil.
\item \textbf{rectangle}\index{rectangle}: required. The delimited text
specifies a rectangular area that is correct, specified as \texttt{(x1,y1)-(x2,y2)},
where x1, x2, y1, and y2 are number corresponding to the x and y coordinates
of two corners that define a rectangle which specifies where the right
answer for this foil is located on the image. For example, \texttt{(0,0)-(100,200)}
will specify that a rectangle 100 pixels wide and 200 pixels tall,
situated in the upper left of the image, is correct. At least one
rectangle is required; multiple rectangles may be specified.
\item \textbf{text}\index{text}: required. The delimited text is printed
before the image is shown on the screen. This text is typically used
to describe to the student what they are expected to click on.
\end{itemize}

\label{Authoring_Input_Tags}

This group of tags implement a mechanism for getting data for students,
they will usually be used by a response tag.

\begin{itemize}
\item \textbf{textfield}\index{textfield}: Creates a large text input box.
If data appears between the start and end tags, the data will appear
in the textfield if the student has not yet made a submission. Additionally,
it takes two attributes \textbf{rows} and \textbf{cols} which control
the height and width of the text area respectively. It defaults to
10 rows and 80 columns.
\item \textbf{\label{textline}textline}\index{textline}: Creates a single
line input element. It accepts one attribute \textbf{size} which controls
the width of the textline, defaulting to 20.
\end{itemize}

\label{Authoring_Internal_Tags}

\begin{itemize}
\item \textbf{labelgroup}\index{labelgroup}: One required, multiple allowed.
Declares a group of locations and labels associated with them. Possible
attributes are:

\begin{itemize}
\item \textbf{name}\index{name}: This is the name of the group. A hash
with this name will be generated holding the mappings for later use
in the problem. For each location a value will be set for which label
is there, (EX. \$hash\{'1'\}=''TEXT-2''). For locations with values the hash will contain 2 items, a location to value mapping (\$hash\{'value\_1'\}=10),
and a label to value mapping (\$hash\{'labelvalue\_2'\}=10). For all image style of labels there will also be a label description to label URL mapping (\$hash\{'image\_2'\}=IMG-URL). Also the entry \textbf{numlocations}
will be set to the total number of locations that exist. (Note that
locations and labels start counting from 1.)
\item \textbf{type}\index{type}: the type of labels in this group, either
'\textbf{image}' or '\textbf{text}'
\item \textbf{location}\index{location}: declares a location on the image
that a label should appear at. Possible attributes are:

\begin{itemize}
\item \textbf{x}\index{x}: The x value of the location in pixels.
\item \textbf{y}\index{y}: The y value of the location in pixels.
\item \textbf{value}\index{value}: An optional scalar value to associate
at this location.
\item \textbf{label}\index{label}: Declaration of a label. If this is a
\textbf{text} type label, the internal text should be the text of
the label (HTML is not currently supported); if this is an \textbf{image}
type of label, the internal text must be a LON-CAPA resource specification,
and the description filed must be set. Possible attributes are:

\begin{itemize}
\item \textbf{description}\index{description}: Required field for image
labels. It will be used when setting values in the hash.
\end{itemize}
\end{itemize}
\end{itemize}
\end{itemize}

\label{Authoring_NumericalResponse}

\textbf{stringresponse} implements a string answer. An internal \textbf{textline}
tag (see \textbf{\ref{textline}}) is necessary for the student's
response to go in. It can check the string for either case or order.
Possible attributes are:

\begin{itemize}
either a perl list or scalar.
\item \textbf{type}\index{type}: optional. Specifies how the string is
checked (like the CAPA styles). Possible values are:

\begin{itemize}
\item \textbf{cs}\index{cs}: \textbf{c}ase \textbf{s}ensitive, order important.
\item \textbf{ci}\index{ci}: \textbf{c}ase \textbf{i}nsensitive, order
important.
\item \textbf{mc}\index{mc}: case insensitive, order unimportant. The mnemonic
for this option is {}\textbf{m}ultiple \textbf{c}hoice'', which
is how it was used in CAPA: To allow the user to specify choices from
a multiple choices problem, as in {}adce'', meaning parts a, d,
c, and e are true. Order didn't matter in such a problem. In LON-CAPA,
using \textbf{optionresponse} with True and False foils would be preferable,
but this will remain supported for easier CAPA-to-LON-CAPA conversion.
\end{itemize}
\end{itemize}

\label{Authoring_OptionResponse}

\textbf{optionresponse} implements a {}select from these choices''
style question, the choices are specified by the instructor, it uses
the foil structure tags as described in \ref{Foil structure tags},

\begin{itemize}
\item \textbf{foilgroup}: required to have an \emph{options} attribute which
should be a perl list of possible options for the student
\end{itemize}

\label{Authoring_Output_Tags}

This group of tags generate useful output.

\begin{itemize}
\item \textbf{standalone}\index{standalone}: Everything in between the
start and end tag is shown only on the web, and only if the resource
is not part of a course.
\item \textbf{displayduedate}\index{displayduedate}: This will insert the
current duedate if one is set into the document. It is generated to
be inside a table of 1x1 elements.
\item \textbf{displaytitle}\index{displaytitle}: This will insert the title
of the problem from the metadata of the problem. Only the first \textbf{displaytitle}
in a problem will show the title; this allows clean usage of \textbf{displaytitle}
in stylesheets.
\item \textbf{window}\index{window}: The text in between is put in a popup
javascript window.
\item \textbf{m}\index{m}: The inside text is \LaTeX{}, and is converted
to HTML (or MathML) on the fly. If the attribute \textbf{eval} is
set to {}\textbf{on}'' the intervening text will have a perl variable
expansion done to it before being converted.
\item \textbf{randomlabel}\index{randomlabel}: Shows a specified image
with images or text labels randomly assigned to a set of specific
locations. Those locations may also have values assigned to them.
There is a hash generated containing the mapping of labels to locations,
labels to values, and locations to values. Example: \begin{verbatim}

<randomlabel bgimg="URL" width="12" height="45" texwidth="50">
<labelgroup name="GroupOne" type="image">
<location x="123" y="456" value="10" />
<location x="321" y="654" value="20" />
<location x="213" y="546" value="13" />
<label description="TEXT-1">IMG-URL</label>
<label description="TEXT-2">IMG-URL</label>
<label description="TEXT-3">IMG-URL</label>
</labelgroup>
<labelgroup name="GroupTwo" type="text">
<location x="12" y="45" />
<location x="32" y="65" />
<location x="21" y="54" />
<label>TEXT-1</label>
<label>TEXT-2</label>
<label>TEXT-3</label>
</labelgroup>
</randomlabel>

\end{verbatim} Possible attributes are:

\begin{itemize}
\item \textbf{bgimg}\index{bgimg}: Either a fully qualified URL for an
external image, or a loncapa resource. It supports relative references
(../images/apicture.gif). The image must either be a GIF or JPEG.
\item \textbf{width}\index{width}: The width of the image in pixels.
\item \textbf{height}\index{height}: The height of the image in pixels.
\item \textbf{texwidth}\index{texwidth}: the width of the image in millimeters.
\end{itemize}
\end{itemize}

\textbf{radiobuttonresponse} implements a true/false question with
1 correct answer. It uses the foil structure tags as described in
\ref{Foil structure tags}, but the \emph{value} of a foil can only
be \textbf{true}, \textbf{false}, or \textbf{unused}.

\label{Authoring_Response_Attributes}

These response tag attributes are used by all response tags:

\begin{itemize}
\item \textbf{id}\index{id}: If this isn't set it will be set during the
publication step. It is used to assign parameters names in a way that
can be tracked if an instructor modifies things by hand.
\item \textbf{name}\index{name}: optional. If set, it will be used by the
resource assembly tool when one is modifying parameters.
\end{itemize}

\label{Authoring_Response_Tag_Intro}

\emph{Response tags} are the tags used by LON-CAPA to indicate what
a student should enter into the system, such as a string answer, clicking
on a picture, typing in a formula, etc. As such they are the core
tags of homework problems; a homework problem without at least one
response tag is not really a homework problem.

Simple examples of the more complicated tags are available as templates
to choose from when creating a new problem in your Construction Space.

\label{Authoring_Responseparam_Parameter}

If \textbf{responseparam} appears it should be inside of a response
tag. It defines an externally adjustable parameter for this question,
which the question can use to allow other users to customize the problem
for use in their courses without changing the source code of the problem.
Possible attributes are:

\begin{itemize}
\item \textbf{default}\index{default}: required. Specifies a default value
for the parameter.
\item \textbf{name}\index{name}: required, specifies an internal name for
the parameter
\item \textbf{type}\index{type}: required specifies the type of parameter,
one of \textbf{tolerance}, \textbf{int}, \textbf{float}, \textbf{string},
or \textbf{date}.
\item \textbf{description}\index{description}: a string describing the
parameter, this is what is used to talk about a parameter outside
of a problem
\end{itemize}
\textbf{parameter} is exactly the same as \textbf{responseparam},
but should appear outside of a response tag.

\label{Authoring_Scripting_Tags}

\begin{itemize}
\item \textbf{display}\index{display}: The intervening perl script is evaluated
in the safe space and the return value of the script replaces the
entire tag.
\item \textbf{import}\index{import}: Causes the parse to read in the file
named in the body of the tag and parse it as if the entire text of
the file had existed at location of the tag.
\item \textbf{parserlib}\index{parserlib}: the enclosed filename contains
definitions for new tags.
\item \textbf{script}\index{script}: If the attribute \textbf{type} is
set to {}loncapa/perl'' the enclosed data is a perl script which
is evaluated inside the perl Safe space. The return value of the script
is ignored.
\item \textbf{scriptlib}\index{scriptlib}: The enclosed filename contains
perl code to run in the safe space.
\item \textbf{block}\index{block}: Has a required argument \textbf{condition}
that is evaluated. If the condition is true everything inside the
tag is evaluated, otherwise everything inside the block tag is skipped.
\item \textbf{notsolved}\index{notsolved}: Everything inside the tag is
skipped if the problem is {}solved''.
the tag is skipped if the problem is before the answer date.
\item \textbf{preduedate}\index{preduedate}: Everything inside the tag
is skipped if the problem is after the due date
\item \textbf{randomlist}\index{randomlist}: The enclosed tags are parsed
in a stable random order. The optional attribute \textbf{show} restricts
the number of tags inside that are actually parsed to no more than
\textbf{show}.
\item \textbf{solved}\index{solved}: Everything inside the tag is skipped
if the problem is {}not solved''.
\item \textbf{while}\index{while}: Implements a while loop. The required
attribute \textbf{condition} is a perl scriptlet that when evaluated
results in a true or false value. On true the entirety of the text
between the whiles is parsed. The condition is tested again, etc.
If false it goes to the next tag.
\end{itemize}

\label{Authoring_Structure_Tags}

These tags give the problem a structure and take care of the recording
of data and giving the student messages.

\begin{itemize}
\item \textbf{problem}\index{problem}: Must be the first tag in the file,
this tag sets up the header of the webpage and generates the submit
buttons, it also handles due dates properly.
\item \textbf{part}\index{part}: Must be below \textbf{problem} if it is
going to be used. It does many of the same tasks as \textbf{problem},
but allows multiple separate problems to exist in a single file.
\item \textbf{startouttext\index{startouttext}} and \textbf{endouttext}\index{endouttext}:
These tags are somewhat special. They must have no internal text and
occur in pairs. Their use is to mark up the problem so the web editor
knows what sections should be edited in a plain text block on the
web.
\item \textbf{comment}\index{comment}: Allows one to comment out sections
of code in a balanced manner, or to provide a comment description
of how a problem works. Only shows up for the edit target, stripped
out for all other targets.
\end{itemize}

\label{Authoring_XML_Intro}

It is assumed that the reader is already familiar with the basic terminology
of XML. If not, I recommend reading http://www.w3schools.com/xml/xml\_syntax.asp
to acquire a basic understanding of how to read and write XML.

LON-CAPA uses a very simple subset of XML and there is a lot you do
\emph{not} need to know, including but not limited to: CDATA, DTDs,
namespaces, and stylesheets. If you search for XML resources on the
Internet yourself, you do not need to read about those things to learn
about how LON-CAPA uses XML for problems.

It is assumed that the reader is already familiar with the basic terminology
of XML. If not, I recommend reading http://www.w3schools.com/xml/xml\_syntax.asp
to acquire a basic understanding of how to read and write XML.

LON-CAPA uses a very simple subset of XML and there is a lot you do
\emph{not} need to know, including but not limited to: CDATA, DTDs,
namespaces, and stylesheets. If you search for XML resources on the
Internet yourself, you do not need to read about those things to learn
about how LON-CAPA uses XML for problems.

\label{Script_Functions}

A list of functions that have been written that are available in the
Safe space scripting environment inside a problem.

\begin{itemize}
\item sin(x), cos(x), tan(x)
\item asin(x), acos(x), atan(x), atan2(y,x)
\item log(x), log10(x)
\item exp(), pow(x,y), sqrt(x)
\item abs(x), sgn(x)
\item erf(x), erfc(x)
\item ceil(x), floor(x)
\item min(...), max(...)
\item factorial(n)
\item N\%M (modulo function)
\item sinh(x), cosh(x), tanh(x)
\item asinh(x), acosh(x), atanh(x)
\item roundto(x,n)
\item web({}a'',''b'',''c'') or web(a,b,c)
\item html({}a'') or html(a)
\item j0(x), j1(x), jn(n,x), jv(y,x)
\item y0(x), y1(x), yn(n,x), yv(y,x)
\item random
\item choose
\item tex({}a'',''b'') or tex(a,b)
\item var\_in\_tex(a)
\item to\_string(x), to\_string(x,y)
\item class(), section()
\item name(), student\_number()
\item open\_date(), due\_date(), answer\_date()
\item sub\_string()
\item array\_moments(array)
\item format(x,y),prettyprint(x,y)
\item map(...)
\item caparesponse\_check
\item caparesponse\_check\_list
\end{itemize}

We also support these functions from Math::Cephes \begin{verbatim}

bdtr:  Binomial distribution
bdtrc:  Complemented binomial distribution
bdtri:  Inverse binomial distribution
btdtr:  Beta distribution
chdtr:  Chi-square distribution
chdtrc:  Complemented Chi-square distribution
chdtri:  Inverse of complemented Chi-square distribution
fdtr:  F distribution
fdtrc:  Complemented F distribution
fdtri:  Inverse of complemented F distribution
gdtr:  Gamma distribution function
gdtrc:  Complemented gamma distribution function
nbdtr:  Negative binomial distribution
nbdtrc:  Complemented negative binomial distribution
nbdtri:  Functional inverse of negative binomial distribution
ndtr:  Normal distribution function
ndtri:  Inverse of Normal distribution function
pdtr:  Poisson distribution
pdtrc:  Complemented poisson distribution
pdtri:  Inverse Poisson distribution
stdtr:  Student's t distribution
stdtri:  Functional inverse of Student's t distribution

\label{Script_Variables}

\begin{itemize}
\item \$external::target - set to the current target the xml parser is parsing for \item \$external::part - set to the \emph{id} of the current problem $<$part$>$;
zero if there are no $<$part$>$
\item \$external::gradestatus - set to the value of the current resource.partid.solved value \item \$external::datestatus - set to the current status of the clock either
\item \$external::randomseed - set to the number that was used to seed the random number generator \item \$pi - set to PI
\item \$rad2deg - converts radians to degrees \item \$deg2rad - converts degrees to radians