Return to Author_LON-CAPA_Introduction.tex CVS log

Up to [LON-CAPA] / loncom / html / adm / help / tex

Annotation of loncom/html/adm/help/tex/Author_LON-CAPA_Introduction.tex, revision 1.16

1.2       bowersj2    1: \label{Author_LON-CAPA_Introduction}
1.1       bowersj2    2: 
1.5       raeburn     3: LON-CAPA is a web-based content management system that helps to organize and present your
                      4: course website, deliver and manage assignments, and manage student enrollment, assessment, and grading.
1.16    ! raeburn     5: Typically all author functions will be completed using a web browser (Firefox, Chrome, Safari, Opera, IE, Edge or similar).
1.5       raeburn     6: The one exception to this is where your LON-CAPA domain has been configured to support webDAV access, in which
                      7: case you may be able to carry out standard file operations (copy, move, add file etc.) using your computer's 
                      8: standard filesystem interface, after you have established access to your authoring space volume.
1.1       bowersj2    9: 
1.16    ! raeburn    10: \subsubsection*{Work spaces and workflow}
        !            11: 
        !            12: LON-CAPA has three work spaces: the ROLES menu, the course/community space where courses are developed from resources, and the authoring space where resources are composed and published. There are two user manuals for LON-CAPA, a course coordinator manual and author manual. Also, there are quick reference guides to building a course and building an exam, available at \texttt{http://help.loncapa.org} . This is the author manual used when creating resources such as problems that can later be added to your course.
        !            13: 
        !            14: LON-CAPA facilitates workflow by providing a couple of mechanisms to switch easily between course container context and authoring context without the need to visit the Roles menu to change roles:
        !            15: \begin{itemize}
        !            16: \item For resources already included in a course and which originate from an authoring space for which you have access (i.e., you are author or co-author), then an Edit link will be present in the Functions menu directly above the resource when displaying it as a Course Coordinator, and the link will take you directly to the authoring environment for that resource.
        !            17: \item If you want to create a new LON-CAPA assessment item in a course, you can do so via the Course Editor, by following the ``Standard Problem'' link in the Assessment ``mini'' tab (with the ``Main Content'' tab active).
        !            18: \end{itemize}
        !            19: 
        !            20: \subsubsection*{Before you start}
1.3       lira       21: 
1.4       lira       22: Before creating problems, you should have:
1.1       bowersj2   23: 
                     24: \begin{itemize}
1.4       lira       25: \item developed learning objectives that you want to evaluate for your course/community
                     26: \item determined the appropriate question formats and developed your problems for input into LON-CAPA. Examples for question formats are provided in this manual and also when authoring a problem.
                     27: \item developed the directory structure that you plan to use to organize your resources
1.1       bowersj2   28: \end{itemize}
1.4       lira       29: 
1.13      damieng    30: \subsubsection*{Overview of the Authoring Process}
1.4       lira       31: 
1.11      raeburn    32: Graphics, problems, and html pages are all considered \textbf{resources.} Additional resources include reusable snippets of perl, xml, cascading style sheets, etc. This manual documents the process used to create and organize the more advanced types of resources.
1.4       lira       33: 
                     34: The authoring process involves these steps:
                     35: \begin{itemize}
                     36: \item create or upload a resource. The resource can combine other uploaded resources such as graphics, code snippets, or problem sequences
                     37: \item test and revise your resource
                     38: \item publish the resource to make it available for integration into a course/community and/or sharing
                     39: \item revise your resources after publishing to improve clarity or eliminate bugs
                     40: \end{itemize}
                     41: 
1.13      damieng    42: \subsubsection*{Importance of Planning your Directory Structure}
1.4       lira       43: 
1.5       raeburn    44: Once a resource has been published, the published version can never be moved or deleted. Thus, it is important to plan your folder structure. Old resources
                     45: can be marked obsolete, and the version in your authoring space deleted,  but the published version(s) will remain in your folders in the locations in which
                     46: they were originally published.
1.4       lira       47: 
1.14      damieng    48: \subsubsection*{The LON-CAPA markup language}
1.4       lira       49: 
1.13      damieng    50: Content documents are created in the LON-CAPA markup language. Like HTML, which is the language used to create all content on the web, the LON-CAPA language is a \emph{markup language}. A markup language is simply structured with \emph{tags}: each structure in the document starts with a \emph{start tag} like \texttt{<problem>} and ends with an \emph{end tag} like \texttt{</problem>}.
                     51: Additionally, each structure (called an \emph{element}) can have \emph{attributes}, each one composed of a name and a value. For instance, \texttt{<foil value="true">} starts a true foil.
                     52: A markup language is defined essentially with a list of elements and attributes, and rules specifying which element is allowed inside which other element.
1.14      damieng    53: 
                     54: The LON-CAPA language includes most HTML elements, and adds more elements which are described in this manual. The syntax is similar to HTML, but with an additional constraint: when an element is started with a start tag, it must always be closed with an end tag (unless the empty element syntax is used, as with \texttt{<hr/>}).
1.13      damieng    55: This syntax is sometimes called ``XML'' in this manual. XML is a specific syntax for markup languages, but the LON-CAPA language is actually not using the XML syntax, which would require escaping special characters in scripts.
1.14      damieng    56: 
                     57: HTML elements are not listed in this manual, but good resources are available on the web to learn HTML. For instance:
                     58: \begin{itemize}
                     59: \item Learn web development:\\
                     60: \texttt{https://developer.mozilla.org/en-US/docs/Learn/HTML}
                     61: \item HTML element reference:\\
                     62: \texttt{https://developer.mozilla.org/en-US/docs/Web/HTML/Reference}
                     63: \end{itemize}
                     64: 
1.16    ! raeburn    65: \subsubsection*{Available editors}
1.14      damieng    66: 
1.16    ! raeburn    67: By default, the authoring environment includes five different editors, although your domain administrator may have chosen to make fewer than five available.
1.13      damieng    68: \begin{itemize}
1.16    ! raeburn    69: \item The \emph{plain text editor} is simply a text area that lets you edit the source code directly. It lacks any special feature, but can be useful for people with disabilities because it is supported by screen readers. To use it, CodeMirror must be disabled either via the \emph{Authoring Space Configuration} link/icon in Preferences, or via Settings $>$ Editing Options in the inline menu (in Authoring Context).
1.13      damieng    70: \item \emph{CodeMirror} is a text editor, and it is launched when you click on the ``EditXML'' button. It lets you edit the source code directly, but adds syntax highlighting and templates to help with editing the code.
1.16    ! raeburn    71: \item \emph{CKEditor} is a simple WYSIWYG HTML editor used in LON-CAPA to edit blocks of plain text or HTML. It is used when you click on the ``Edit'' button for a \texttt{.html} file and click on ``Rich formatting''. It can also be used within the colorful editor to edit blocks of text, also by clicking on the ``Rich formatting'' link. CKEditor is an HTML editor, with some support for LON-CAPA-specific elements such as \texttt{<m>} and \texttt{<chem>}, for which plugins have been added.
1.13      damieng    72: \item The \emph{colorful editor} is LON-CAPA's default editor, launched when you click on the ``Edit'' button for a \texttt{.problem} file. It hides the source code and displays the document with colored boxes representing the elements. It provides a list of elements that can be inserted at a particular place in the document, helps to choose correct values when several values are possible for an attribute, and generally makes sure the syntax is correct.
1.16    ! raeburn    73: \item \emph{Daxe} is based on the Daxe XML editor for the web. It adds an XML schema, Daxe configuration and user interface code for the markup language used by LON-CAPA documents. It is started with the ``Daxe'' button. Like the colorful editor, it hides the source code and provides a graphical interface which makes it easier to create documents without knowing the language. It displays elements in a way that makes it easier to edit documents with cut/copy/paste and drag \& drop features. HTML elements are often displayed exactly the way they will look outside the editor environment. Many response elements have both a ``simple'' and an ``advanced'' view, making it easy to create simple problems. A preview is available to the right, making it easy to see what the entire document will look like.
1.13      damieng    74: \end{itemize}
1.4       lira       75: 
1.16    ! raeburn    76: It is possible to edit a problem in one editor, save it, and switch to another editor to continue. Authors are encouraged to try all editors to find their favorite, but it is also possible to use an editor for certain operations and another one for other operations. Simple syntax errors can for instance be fixed easily with CodeMirror, but editing in general may be easier with one of the other editors.
1.4       lira       77: 
1.13      damieng    78: \subsubsection*{Scripts}
1.4       lira       79: 
1.9       raeburn    80: The power of LON-CAPA for problem randomization and computing randomized answers is realized through writing perl script at the top of a problem. Example scripts are included in many example problems, and most resource authors publish scripts with the problems, so many examples are available. Many special functions have been created for use in scripts. This manual includes a section on writing scripts.
1.4       lira       81: 
1.13      damieng    82: \subsubsection*{Maxima and R}
1.4       lira       83: 
                     84: Two computer algebra systems are interfaced to LON-CAPA, Maxima and R. This provides for algebra and calculus problems and responses. The R system has strong capabilities for statistics. Special script functions are provided to call Maxima and R to generate correct responses for a randomized problem, and also to check student responses.
                     85: 
1.13      damieng    86: \subsubsection*{Comments}
1.6       lira       87: 
1.13      damieng    88: Commenting your XML and scripts is important for both you and other users. Commenting within a loncapa/perl script 
1.6       lira       89: is denoted with a \#. This can be entered anwhere in a line and the remainder of the line will be ignored when
1.13      damieng    90: parsing. Comments in HTML and XML use the syntax \texttt{<!-- comment -->}.
                     91: \index{comment markers}However, it is important to know that these comments 
                     92: propagate through to the rendered web page viewed by students while the Perl comments 
1.7       lira       93: within the script are not. Hence, writing solution hints within XML comments is 
                     94: discouraged for obvious reasons.
1.13      damieng    95: Another option is to use the \texttt{<comment>} element, because its content is safely discarded when the web page is created.