--- loncom/interface/loncommon.pm	2008/03/20 19:46:44	1.647
+++ loncom/interface/loncommon.pm	2008/03/23 21:40:10	1.648
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # a pile of common routines
 #
-# $Id: loncommon.pm,v 1.647 2008/03/20 19:46:44 www Exp $
+# $Id: loncommon.pm,v 1.648 2008/03/23 21:40:10 raeburn Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -84,25 +84,40 @@ my $readit;
 
 =pod
 
-=head1 Server Side incliude with retries:
+=head1 Server Side include with retries:
 
 =over 4
 
-=item * ssi_with_retries(resource, retries form)
+=item * &ssi_with_retries(resource,retries form)
 
 Performs an ssi with some number of retries.  Retries continue either
 until the result is ok or until the retry count supplied by the
 caller is exhausted.  
 
 Inputs:
+
+=over 4
+
 resource   - Identifies the resource to insert.
+
 retries    - Count of the number of retries allowed.
+
 form       - Hash that identifies the rendering options.
 
-Returns: 
+=back
+
+Returns:
+
+=over 4
+
 content    - The content of the response.  If retries were exhausted this is empty.
+
 response   - The response from the last attempt (which may or may not have been successful.
 
+=back
+
+=back
+
 =cut
 
 sub ssi_with_retries {
@@ -266,14 +281,14 @@ BEGIN {
 
 =over 4
 
-=item * browser_and_searcher_javascript ()
+=item * &browser_and_searcher_javascript()
 
 X<browsing, javascript>X<searching, javascript>Returns a string
 containing javascript with two functions, C<openbrowser> and
 C<opensearcher>. Returned string does not contain E<lt>scriptE<gt>
 tags.
 
-=item * openbrowser(formname,elementname,only,omit) [javascript]
+=item * &openbrowser(formname,elementname,only,omit) [javascript]
 
 inputs: formname, elementname, only, omit
 
@@ -286,7 +301,7 @@ with the given extension.  Can be a comm
 Specifying 'omit' will restrict the browser to NOT displaying files
 with the given extension.  Can be a comma separated list.
 
-=item * opensearcher(formname, elementname) [javascript]
+=item * &opensearcher(formname,elementname) [javascript]
 
 Inputs: formname, elementname
 
@@ -594,7 +609,7 @@ ENDSCRT
 
 =pod
 
-=item * linked_select_forms(...)
+=item * &linked_select_forms(...)
 
 linked_select_forms returns a string containing a <script></script> block
 and html for two <select> menus.  The select menus will be linked in that
@@ -759,7 +774,7 @@ END
 
 =pod
 
-=item * help_open_topic($topic, $text, $stayOnPage, $width, $height)
+=item * &help_open_topic($topic,$text,$stayOnPage,$width,$height)
 
 Returns a string corresponding to an HTML link to the given help
 $topic, where $topic corresponds to the name of a .tex file in
@@ -1069,7 +1084,7 @@ ENDTEMPLATE
 
 =pod
 
-=item * change_content_javascript():
+=item * &change_content_javascript():
 
 This and the next function allow you to create small sections of an
 otherwise static HTML page that you can update on the fly with
@@ -1124,7 +1139,7 @@ DOMBASED
 
 =pod
 
-=item * changable_area($name, $origContent):
+=item * &changable_area($name,$origContent):
 
 This provides a "changable area" that can be modified on the fly via
 the Javascript code provided in C<change_content_javascript>. $name is
@@ -1148,7 +1163,7 @@ sub changable_area {
 
 =pod
 
-=item * viewport_geometry_js {
+=item * &viewport_geometry_js 
 
 Provides javascript object (Geometry) which can provide information about the viewport geometry for the client browser.
 
@@ -1195,7 +1210,7 @@ GEOMETRY
 
 =pod
 
-=item * viewport_size_js {
+=item * &viewport_size_js()
 
 Provides a javascript function to set values of two form elements - width and height (elements are passed in as arguments to the javascript function) to the dimensions of the user's browser window. 
 
@@ -1219,7 +1234,7 @@ DIMS
 
 =pod
 
-=item * resize_textarea_js
+=item * &resize_textarea_js()
 
 emits the needed javascript to resize a textarea to be as big as possible
 
@@ -1228,6 +1243,7 @@ the id of the element to resize, second
 surrounds everything that comes after the textarea, this routine needs
 to be attached to the <body> for the onload and onresize events.
 
+=back
 
 =cut
 
@@ -1280,8 +1296,6 @@ RESIZE
 
 =pod
 
-=back
- 
 =head1 Excel and CSV file utility routines
 
 =over 4
@@ -1293,7 +1307,7 @@ RESIZE
 
 =pod
 
-=item * csv_translate($text) 
+=item * &csv_translate($text) 
 
 Translate $text to allow it to be output as a 'comma separated values' 
 format.
@@ -1314,7 +1328,7 @@ sub csv_translate {
 
 =pod
 
-=item * define_excel_formats
+=item * &define_excel_formats()
 
 Define some commonly used Excel cell formats.
 
@@ -1370,7 +1384,7 @@ sub define_excel_formats {
 
 =pod
 
-=item * create_workbook
+=item * &create_workbook()
 
 Create an Excel worksheet.  If it fails, output message on the
 request object and return undefs.
@@ -1413,7 +1427,7 @@ sub create_workbook {
 
 =pod
 
-=item * create_text_file
+=item * &create_text_file()
 
 Create a file to write to and eventually make available to the user.
 If file creation fails, outputs an error message on the request object and 
@@ -1481,7 +1495,7 @@ sub domain_select {
 
 =over 4
 
-=item * multiple_select_form($name,$value,$size,$hash,$order)
+=item * &multiple_select_form($name,$value,$size,$hash,$order)
 
 Returns a string containing a <select> element int multiple mode
 
@@ -1531,7 +1545,7 @@ sub multiple_select_form {
 
 =pod
 
-=item * select_form($defdom,$name,%hash)
+=item * &select_form($defdom,$name,%hash)
 
 Returns a string containing a <select name='$name' size='1'> form to 
 allow a user to select options from a hash option_name => displayed text.  
@@ -1618,7 +1632,7 @@ sub select_level_form {
 
 =pod
 
-=item * select_dom_form($defdom,$name,$includeempty,$showdomdesc)
+=item * &select_dom_form($defdom,$name,$includeempty,$showdomdesc)
 
 Returns a string containing a <select name='$name' size='1'> form to 
 allow a user to select the domain to preform an operation in.  
@@ -1658,7 +1672,7 @@ sub select_dom_form {
 
 =pod
 
-=item * home_server_form_item($domain,$name,$defaultflag)
+=item * &home_server_form_item($domain,$name,$defaultflag)
 
 input: 4 arguments (two required, two optional) - 
     $domain - domain of new user
@@ -1818,14 +1832,12 @@ sub decode_user_agent {
 
 =over 4
 
-=item * authform_xxxxxx
+=item * &authform_xxxxxx()
 
 The authform_xxxxxx subroutines provide javascript and html forms which 
 handle some of the conveniences required for authentication forms.  
 This is not an optimal method, but it works.  
 
-See loncreateuser.pm for invocation and use examples.
-
 =over 4
 
 =item * authform_header
@@ -1842,7 +1854,7 @@ See loncreateuser.pm for invocation and
 
 =back
 
-=back 
+See loncreateuser.pm for invocation and use examples.
 
 =cut
 
@@ -2305,14 +2317,20 @@ sub get_assignable_auth {
 
 =pod
 
-=item * get_kerberos_defaults
+=item * &get_kerberos_defaults()
 
 get_kerberos_defaults($target_domain) returns the default kerberos
 version and domain. If not found, it defaults to version 4 and the 
 domain of the server.
 
+=over 4
+
 ($def_version, $def_krb_domain) = &get_kerberos_defaults($target_domain);
 
+=back
+
+=back
+
 =cut
 
 #-------------------------------------------
@@ -2332,11 +2350,6 @@ sub get_kerberos_defaults {
     return ($krbdef,$krbdefdom);
 }
 
-=pod
-
-=back
-
-=cut
 
 ###############################################################
 ##                Thesaurus Functions                        ##
@@ -2348,7 +2361,7 @@ sub get_kerberos_defaults {
 
 =over 4
 
-=item * initialize_keywords
+=item * &initialize_keywords()
 
 Initializes the package variable %Keywords if it is empty.  Uses the
 package variable $thesaurus_db_file.
@@ -2393,7 +2406,7 @@ sub initialize_keywords {
 
 =pod
 
-=item * keyword($word)
+=item * &keyword($word)
 
 Returns true if $word is a keyword.  A keyword is a word that appears more 
 than the average number of times in the thesaurus database.  Calls 
@@ -2414,7 +2427,7 @@ sub keyword {
 
 =pod 
 
-=item * get_related_words
+=item * &get_related_words()
 
 Look up a word in the thesaurus.  Takes a scalar argument and returns
 an array of words.  If the keyword is not in the thesaurus, an empty array
@@ -2472,7 +2485,7 @@ sub get_related_words {
 
 =over 4
 
-=item * plainname($uname,$udom,$first)
+=item * &plainname($uname,$udom,$first)
 
 Takes a users logon name and returns it as a string in
 "first middle last generation" form 
@@ -2501,7 +2514,7 @@ sub plainname {
 # -------------------------------------------------------------------- Nickname
 =pod
 
-=item * nickname($uname,$udom)
+=item * &nickname($uname,$udom)
 
 Gets a users name and returns it as a string as
 
@@ -2551,18 +2564,21 @@ sub getnames {
 }
 
 # -------------------------------------------------------------------- getemails
+
 =pod
 
-=item * getemails($uname,$udom)
+=item * &getemails($uname,$udom)
 
 Gets a user's email information and returns it as a hash with keys:
 notification, critnotification, permanentemail
 
 For notification and critnotification, values are comma-separated lists 
-of e-mail address(es); for permanentemail, value is a single e-mail address.
+of e-mail addresses; for permanentemail, value is a single e-mail address.
  
+
 =cut
 
+
 sub getemails {
     my ($uname,$udom)=@_;
     if ($udom eq 'public' && $uname eq 'public') {
@@ -2597,7 +2613,7 @@ sub flush_email_cache {
 
 =pod
 
-=item * screenname($uname,$udom)
+=item * &screenname($uname,$udom)
 
 Gets a users screenname and returns it as a string
 
@@ -2693,7 +2709,7 @@ sub student_image_tag {
 
 =over 4
 
-=item * languageids() 
+=item * &languageids() 
 
 returns list of all language ids
 
@@ -2705,7 +2721,7 @@ sub languageids {
 
 =pod
 
-=item * languagedescription() 
+=item * &languagedescription() 
 
 returns description of a specified language id
 
@@ -2730,7 +2746,7 @@ sub supportedlanguagecode {
 
 =pod
 
-=item * copyrightids() 
+=item * &copyrightids() 
 
 returns list of all copyrights
 
@@ -2742,7 +2758,7 @@ sub copyrightids {
 
 =pod
 
-=item * copyrightdescription() 
+=item * &copyrightdescription() 
 
 returns description of a specified copyright id
 
@@ -2754,7 +2770,7 @@ sub copyrightdescription {
 
 =pod
 
-=item * source_copyrightids() 
+=item * &source_copyrightids() 
 
 returns list of all source copyrights
 
@@ -2766,7 +2782,7 @@ sub source_copyrightids {
 
 =pod
 
-=item * source_copyrightdescription() 
+=item * &source_copyrightdescription() 
 
 returns description of a specified source copyright id
 
@@ -2778,7 +2794,7 @@ sub source_copyrightdescription {
 
 =pod
 
-=item * filecategories() 
+=item * &filecategories() 
 
 returns list of all file categories
 
@@ -2790,7 +2806,7 @@ sub filecategories {
 
 =pod
 
-=item * filecategorytypes() 
+=item * &filecategorytypes() 
 
 returns list of file types belonging to a given file
 category
@@ -2804,7 +2820,7 @@ sub filecategorytypes {
 
 =pod
 
-=item * fileembstyle() 
+=item * &fileembstyle() 
 
 returns embedding style for a specified file type
 
@@ -2828,7 +2844,7 @@ sub filecategoryselect {
 
 =pod
 
-=item * filedescription() 
+=item * &filedescription() 
 
 returns description for a specified file type
 
@@ -2842,7 +2858,7 @@ sub filedescription {
 
 =pod
 
-=item * filedescriptionex() 
+=item * &filedescriptionex() 
 
 returns description for a specified file type with
 extra formatting
@@ -2960,7 +2976,7 @@ sub languages {
 
 =over 4
 
-=item * get_previous_attempt($symb, $username, $domain, $course,
+=item * &get_previous_attempt($symb, $username, $domain, $course,
     $getattempt, $regexp, $gradesub)
 
 Return string with previous attempt on problem. Arguments:
@@ -3104,7 +3120,7 @@ sub relative_to_absolute {
 
 =pod
 
-=item * get_student_view
+=item * &get_student_view()
 
 show a snapshot of what student was looking at
 
@@ -3137,7 +3153,7 @@ sub get_student_view {
 
 =pod
 
-=item * get_student_answers() 
+=item * &get_student_answers() 
 
 show a snapshot of how student was answering problem
 
@@ -5401,8 +5417,15 @@ sub endheadtag {
 
 Returns a uniform complete <head>..</head> section for LON-CAPA web pages.
 
-Inputs: $title - optional title for the page
-        $head_extra - optional extra HTML to put inside the <head>
+Inputs:
+
+=over 4
+
+$title - optional title for the page
+
+$head_extra - optional extra HTML to put inside the <head>
+
+=back
 
 =cut
 
@@ -5417,44 +5440,54 @@ sub head {
 
 Returns a complete <html> .. <body> section for LON-CAPA web pages.
 
-Inputs: $title - optional title for the page
-        $head_extra - optional extra HTML to incude inside the <head>
-        $args - additional optional args supported are:
-                  only_body      -> is true will set &bodytag() onlybodytag
+Inputs:
+
+=over 4
+
+$title - optional title for the page
+
+$head_extra - optional extra HTML to incude inside the <head>
+
+$args - additional optional args supported are:
+
+=over 8
+
+             only_body      -> is true will set &bodytag() onlybodytag
                                     arg on
-                  no_nav_bar     -> is true will set &bodytag() notopbar arg on
-                  add_entries    -> additional attributes to add to the  <body>
-                  domain         -> force to color decorate a page for a 
+             no_nav_bar     -> is true will set &bodytag() notopbar arg on
+             add_entries    -> additional attributes to add to the  <body>
+             domain         -> force to color decorate a page for a 
                                     specific domain
-                  function       -> force usage of a specific rolish color
+             function       -> force usage of a specific rolish color
                                     scheme
-                  redirect       -> see &headtag()
-                  bgcolor        -> override the default page bg color
-                  js_ready       -> return a string ready for being used in 
+             redirect       -> see &headtag()
+             bgcolor        -> override the default page bg color
+             js_ready       -> return a string ready for being used in 
                                     a javascript writeln
-                  html_encode    -> return a string ready for being used in 
+             html_encode    -> return a string ready for being used in 
                                     a html attribute
-                  force_register -> if is true will turn on the &bodytag()
+             force_register -> if is true will turn on the &bodytag()
                                     $forcereg arg
-                  body_title     -> alternate text to use instead of $title
+             body_title     -> alternate text to use instead of $title
                                     in the title box that appears, this text
                                     is not auto translated like the $title is
-                  frameset       -> if true will start with a <frameset>
+             frameset       -> if true will start with a <frameset>
                                     rather than <body>
-                  no_title       -> if true the title bar won't be shown
-                  skip_phases    -> hash ref of 
+             no_title       -> if true the title bar won't be shown
+             skip_phases    -> hash ref of 
                                     head -> skip the <html><head> generation
                                     body -> skip all <body> generation
-
-                  no_inline_link -> if true and in remote mode, don't show the 
+             no_inline_link -> if true and in remote mode, don't show the 
                                     'Switch To Inline Menu' link
-
-                  no_auto_mt_title -> prevent &mt()ing the title arg
-
-                  inherit_jsmath -> when creating popup window in a page,
+             no_auto_mt_title -> prevent &mt()ing the title arg
+             inherit_jsmath -> when creating popup window in a page,
                                     should it have jsmath forced on by the
                                     current page
 
+=back
+
+=back
+
 =cut
 
 sub start_page {
@@ -6784,7 +6817,7 @@ sub get_institutional_codes {
 
 =over 4
 
-=item * get_unprocessed_cgi($query,$possible_names)
+=item * &get_unprocessed_cgi($query,$possible_names)
 
 Modify the %env hash to contain unprocessed CGI form parameters held in
 $query.  The parameters listed in $possible_names (an array reference),
@@ -6813,7 +6846,7 @@ sub get_unprocessed_cgi {
 
 =pod
 
-=item * cacheheader() 
+=item * &cacheheader() 
 
 returns cache-controlling header code
 
@@ -6830,7 +6863,7 @@ sub cacheheader {
 
 =pod
 
-=item * no_cache($r) 
+=item * &no_cache($r) 
 
 specifies header code to not have cache
 
@@ -6866,7 +6899,7 @@ sub content_type {
 
 =pod
 
-=item * add_to_env($name,$value) 
+=item * &add_to_env($name,$value) 
 
 adds $name to the %env hash with value
 $value, if $name already exists, the entry is converted to an array
@@ -6893,7 +6926,7 @@ sub add_to_env {
 
 =pod
 
-=item * get_env_multiple($name) 
+=item * &get_env_multiple($name) 
 
 gets $name from the %env hash, it seemlessly handles the cases where multiple
 values may be defined and end up as an array ref.
@@ -6925,7 +6958,7 @@ sub get_env_multiple {
 
 =over 4
 
-=item * upfile_store($r)
+=item * &upfile_store($r)
 
 Store uploaded file, $r should be the HTTP Request object,
 needs $env{'form.upfile'}
@@ -6955,7 +6988,7 @@ sub upfile_store {
 
 =pod
 
-=item * load_tmp_file($r)
+=item * &load_tmp_file($r)
 
 Load uploaded file from tmp, $r should be the HTTP Request object,
 needs $env{'form.datatoken'},
@@ -6979,7 +7012,7 @@ sub load_tmp_file {
 
 =pod
 
-=item * upfile_record_sep()
+=item * &upfile_record_sep()
 
 Separate uploaded file into records
 returns array of records,
@@ -7001,7 +7034,7 @@ sub upfile_record_sep {
 
 =pod
 
-=item * record_sep($record)
+=item * &record_sep($record)
 
 Separate a record into fields $record should be an item from the upfile_record_sep(), needs $env{'form.upfiletype'}
 
@@ -7086,7 +7119,7 @@ sub record_sep {
 
 =pod
 
-=item * upfile_select_html()
+=item * &upfile_select_html()
 
 Return HTML code to select a file from the users machine and specify 
 the file type.
@@ -7133,7 +7166,7 @@ sub get_samples {
 
 =pod
 
-=item * csv_print_samples($r,$records)
+=item * &csv_print_samples($r,$records)
 
 Prints a table of sample values from each column uploaded $r is an
 Apache Request ref, $records is an arrayref from
@@ -7169,7 +7202,7 @@ sub csv_print_samples {
 
 =pod
 
-=item * csv_print_select_table($r,$records,$d)
+=item * &csv_print_select_table($r,$records,$d)
 
 Prints a table to create associations between values and table columns.
 
@@ -7215,7 +7248,7 @@ sub csv_print_select_table {
 
 =pod
 
-=item * csv_samples_select_table($r,$records,$d)
+=item * &csv_samples_select_table($r,$records,$d)
 
 Prints a table of sample values from the upload and can make associate samples to internal names.
 
@@ -7265,7 +7298,7 @@ sub csv_samples_select_table {
 
 =pod
 
-=item clean_excel_name($name)
+=item * &clean_excel_name($name)
 
 Returns a replacement for $name which does not contain any illegal characters.
 
@@ -7284,7 +7317,7 @@ sub clean_excel_name {
 
 =pod
 
-=item * check_if_partid_hidden($id,$symb,$udom,$uname)
+=item * &check_if_partid_hidden($id,$symb,$udom,$uname)
 
 Returns either 1 or undef
 
@@ -7325,7 +7358,7 @@ sub check_if_partid_hidden {
 
 =over 4
 
-=item get_cgi_id
+=item * &get_cgi_id()
 
 Inputs: none
 
@@ -7349,7 +7382,7 @@ sub get_cgi_id {
 
 =pod
 
-=item DrawBarGraph
+=item * &DrawBarGraph()
 
 Facilitates the plotting of data in a (stacked) bar graph.
 Puts plot definition data into the users environment in order for 
@@ -7493,7 +7526,7 @@ sub DrawBarGraph {
 
 =pod
 
-=item DrawXYGraph
+=item * &DrawXYGraph()
 
 Facilitates the plotting of data in an XY graph.
 Puts plot definition data into the users environment in order for 
@@ -7583,7 +7616,7 @@ sub DrawXYGraph {
 
 =pod
 
-=item DrawXYYGraph
+=item * &DrawXYYGraph()
 
 Facilitates the plotting of data in an XY graph with two Y axes.
 Puts plot definition data into the users environment in order for 
@@ -7693,7 +7726,7 @@ Bad place for them but what the hell.
 
 =over 4
 
-=item &chartlink
+=item * &chartlink()
 
 Returns a link to the chart for a specific student.  
 
@@ -7732,9 +7765,9 @@ sub chartlink {
 
 =over 4
 
-=item &restore_course_settings 
+=item * &restore_course_settings()
 
-=item &store_course_settings
+=item * &store_course_settings()
 
 Restores/Store indicated form parameters from the course environment.
 Will not overwrite existing values of the form parameters.
@@ -7845,7 +7878,7 @@ sub restore_settings {
 
 =over 4
 
-=item &build_recipient_list
+=item * &build_recipient_list()
 
 Build recipient lists for three types of e-mail:
 (a) Error Reports, (b) Package Updates, (c) Help requests, generated by