WeBWorKdocs
sq_webwork:

Home
Current UR courses
Visitor page
Intro to WeBWorK
WeBWorK 2 Twiki
WW Community
Grant Support & awards
Discussion group
Problem library
Write/modify problems
Create & manage course
Tutorial on running a course
HowTos
FAQ
WeBWorK2 FAQ
Software Download
How to Install WW server
Feedback
Site Map
Change preferences
Change password
Prev | Next | pod

NAME

dangerousMacros.pl - Macros which require elevated permissions to execute.

SYNPOSIS

    loadMacros(macrofile1,macrofile2,...)

    insertGraph(graphObject); # returns a path to the file containing the graph image.

    tth(texString); # returns an HTML version of the tex code passed to it.

    alias(pathToFile); # returns URL which links to that file

DESCRIPTION

dangerousMacros.pl contains macros that use potentially dangerous functions like require and eval. They can reference disk files for reading and writing, create links, and execute commands. It may be necessary to modify certain addresses in this file to make the scripts run properly in different environments.

This file is loaded implicitly every time a new problem is rendered.

FIXME this information belongs in global.conf where modules to load are listed. I don't see why this shows up here.

Sharing modules

Most modules are loaded by dangerousMacros.pl

The modules must be loaded using require (not use) since the courseScriptsDirectory is defined at run time.

The following considerations come into play.

  • One needs to limit the access to modules for safety -- hence only modules in the courseScriptsDirectory can be loaded.

  • Loading them in dangerousMacros.pl is wasteful, since the modules would need to be reloaded everytime a new safe compartment is created. (I believe that using require takes care of this.)

  • Loading GD within a safeCompartment creates infinite recurrsion in AUTOLOAD (probably a bug) hence this module is loaded by translate.pl and then shared with the safe compartment.

  • Other modules loaded by translate.pl are Exporter and DynaLoader.

  • PGrandom is loaded by PG.pl, since it is needed there.

The module name spaces loaded in dangerousMacros are:

    PGrandom (if not previously loaded)
    WWPlot
    Fun
    Label
    Circle

in addition the subroutine &evaluate_units is shared from the module Units.

loadMacros

    loadMacros(@macroFiles)

loadMacros takes a list of file names and evaluates the contents of each file. This is used to load macros which define and augment the PG language. The macro files are searched for in the directories specified by the array referenced by $macrosPath, which by default is the current course's macros directory followed by WeBWorK's pg/macros directory. The latter is where the default behaviour of the PG language is defined. The default path is set in the global.conf file.

Macro files named PG.pl, IO.pl, or dangerousMacros.pl will be loaded with no opcode restrictions, hence any code in those files will be able to execute privileged operations. This is true no matter which macro directory the file is in. For example, if $macrosPath contains the path to a problem library macros directory which contains a PG.pl file, this file will be loaded and allowed to engage in privileged behavior.

Overloading macro files

An individual course can modify the PG language, for that course only, by duplicating one of the macro files in the system-wide macros directory and placing this file in the macros directory for the course. The new file in the course's macros directory will now be used instead of the file in the system-wide macros directory.

The new file in the course macros directory can by modified by adding macros or modifying existing macros.

Modifying existing macros

Modifying macros is for users with some experience.

Modifying existing macros might break other standard macros or problems which depend on the unmodified behavior of these macors so do this with great caution. In addition problems which use new macros defined in these files or which depend on the modified behavior of existing macros will not work in other courses unless the macros are also transferred to the new course. It helps to document the problems by indicating any special macros which the problems require.

There is no facility for modifying or overloading a single macro. The entire file containing the macro must be overloaded.

Modifications to files in the course macros directory affect only that course, they will not interfere with the normal behavior of WeBWorK in other courses.

insertGraph

    # returns a path to the file containing the graph image.
    $filePath = insertGraph($graphObject);

insertGraph writes a GIF or PNG image file to the gif subdirectory of the current course's HTML temp directory. The file name is obtained from the graph object. Warnings are issued if errors occur while writing to the file.

Returns a string containing the full path to the temporary file containing the image. This is most often used in the construct

    TEXT(alias(insertGraph($graph)));

where alias converts the directory address to a URL when serving HTML pages and insures that an EPS file is generated when creating TeX code for downloading.

[DEPRECATED] tth

    # returns an HTML version of the TeX code passed to it.
    tth($texString);

This macro sends $texString to the filter program TtH, a TeX to HTML translator written by Ian Hutchinson. TtH is available free of change non-commerical use at http://hutchinson.belmont.ma.us/tth/.

The purpose of TtH is to translate text in the TeX or LaTeX markup language into HTML markup as best as possible. Some symbols, such as square root symbols are not translated completely. Macintosh users must use the "MacRoman" encoding (available in 4.0 and higher browsers) in order to view the symbols correctly. WeBWorK attempts to force Macintosh browsers to use this encoding when such a browser is detected.

The contents of the file tthPreamble.tex in the courses template directory are prepended to each string. This allows one to define TeX macros which can be used in every problem. Currently there is no default tthPreamble.tex file, so if the file is not present in the course template directory no TeX macro definitions are prepended. TtH already understands most LaTeX commands, but will not in general know AMS-LaTeX commands.

This macro contains code which is system dependent and may need to be modified to run on different systems.

[DEPRECATED] math2img

    # returns an IMG tag pointing to an image version of the supplied TeX
    math2img($texString);

This macro was used by the HTML_img display mode, which no longer exists.

[DEPRECATED] dvipng

    dvipng($working_directory, $latex_path, $dvipng_path, $tex_string, $target_path)

This macro was used by the HTML_img display mode, which no longer exists.

alias

    # In HTML modes, returns the URL of a web-friendly version of the specified file.
    # In TeX mode, returns the path to a TeX-friendly version of the specified file.
    alias($pathToFile);

alias allows you to refer to auxiliary files which are in a directory along with the problem definition. In addition alias creates an EPS version of GIF or PNG files when called in TeX mode.

As a rule auxiliary files that are used by a number of problems in a course should be placed in html/gif or html or in a subdirectory of the html directory, while auxiliary files which are used in only one problem should be placed in the same directory as the problem in order to make the problem more portable.

Specific behavior of the alias macro

Files in the html subdirectory

When not in TeX mode

If the file lies under the html subdirectory, then the approriate URL for the file is returned. Since the html subdirectory is already accessible to the webserver no other changes need to be made. The file path for this type of file should be the complete file path. The path should start with the prefix defined in $courseDirs{html_temp} in global.conf.

When in TeX mode

GIF and PNG files will be translated into EPS files and placed in the directory tmp/eps. The full path to this file is returned for use by TeX in producing the hard copy. The conversion is done by a system dependent commands defined in global.conf $externalPrograms{gif2eps} (for GIF images) or $externalPrograms{png2eps} (for PNG images). The URLs for the other files are produced as in non-TeX mode but will of course not be usable to TeX.

Files in the tmp subdirectory

When not in TeX mode

If the file lies under the tmp subdirectory, then the approriate URL for the file is created. Since the tmp subdirectory is already accessible to the webserver no other changes need to be made. The file path for this type of file should be the complete file path. The path should start with the prefix defined in $courseDirs{html_temp} in global.conf.

When in TeX mode

GIF and PNG files will be translated into EPS files and placed in the directory tmp/eps. The full path to this file is returned for use by TeX in producing the hard copy. The conversion is done by a system dependent commands defined in global.conf $externalPrograms{gif2eps} (for GIF images) or $externalPrograms{png2eps} (for PNG images). The URLs for the other files are produced as in non-TeX mode but will of course not be usable to TeX.

Files in the course template subdirectory

When not in TeX mode

If the file lies under the course templates subdirectory, it is assumed to lie in subdirectory rooted in the directory containing the problem template file. An alias is created under the html/tmp/gif or html/tmp/html directory and linked to the original file. The file path for this type of file is a relative path rooted at the directory containing the problem template file.

When in TeX mode

GIF and PNG files will be translated into EPS files and placed in the directory tmp/eps. The full path to this file is returned for use by TeX in producing the hard copy. The conversion is done by a system dependent commands defined in global.conf $externalPrograms{gif2eps} (for GIF images) or $externalPrograms{png2eps} (for PNG images). The URLs for the other files are produced as in non-TeX mode but will of course not be usable to TeX.

sourceAlias

    sourceAlias($path_to_PG_file);

Returns a relative URL to the source.pl script, which may be installed in a course's html directory to allow formatted viewing of the problem source.

File path = /ww/webwork/pg/macros/dangerousMacros.pl

<| Post or View Comments |>


Prev | Next | pod
Last update: Sunday, January 28, 2001 at 5:45:47 PM.
This site maintained using Manila and Frontier software.