|
dangerousMacros.pl - Macros which require elevated permissions to execute.
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
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.
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(@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.
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 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.
# 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.
# 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.
# 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.
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.
# 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.
- 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.
- 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.
- 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($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 |>
|
