InstructorPGProblemEditor.html.ep

% layout 'help_macro';
% title maketext('PG Problem Editor Help');
%
<p>
	<%= maketext('This page allows one to edit the contents of PG problem files as well '
		. 'as set headers and other files.') =%>
</p>
<h2><%= maketext('Features:') %></h2>
<dl class="list-group">
	<dt><%= maketext('Links to pages that give information about writing problems:') %></dt>
	<dd class="list-group-item">
		<dl>
			<dt>
				<%= link_to maketext('Sample Problems') => url_for('sample_problem_index'),
					target => 'techniques_window' =%>
			</dt>
			<dd><%= maketext('Sample problem code with documentation.') %></dd>
			<dt>
				<a href="https://wiki.openwebwork.org/wiki/Category:MathObjects" target="math_objects">
					<%= maketext('Math Objects') %>
				</a>
			</dt>
			<dd><%= maketext('This links to a page describing Math Object usage.') %></dd>
			<dt><%= link_to maketext('POD') => url_for('pod_index'), target => 'pod_docs' =%></dt>
			<dd>
				<%= maketext('This link gives details for many macros. It links to documentation embedded in the '
					. 'macro files themselves.') =%>
			</dd>
			<dt>
				<%= link_to PGML => '#', class  => 'pgml-lab', target => 'PGML',
					data => { source => url_escape(readFile("$ce->{webworkDirs}{assets}/pg/PGMLLab/PGML-lab.pg")) } =%>
			</dt>
			<dd>
				<%= maketext(
					'This links to a WeBWorK "problem" which allows you to try out fragments of PGML code.'
				) =%>
			</dd>
			<dt>
				<a href="https://wiki.openwebwork.org/wiki/Category:Authors" target="author_info">
					<%= maketext('Author Info') %>
				</a>
			</dt>
			<dd><%= maketext('This links to problem authoring information on the WeBWorK wiki.') %></dd>
		</dl>
	</dd>
	<dt><%= maketext('Text Editor Window') %></dt>
	<dd class="list-group-item">
		<%= maketext('This is where you edit the code of the problem. Type Ctrl-Enter while this window '
			. 'has focus to re-render the problem. In addition, the following keyboard shortcuts are available.') =%>
		<table class="table table-bordered table-sm align-middle w-auto mb-0 mx-auto">
			<thead>
				<tr>
					<th class="text-nowrap"><%= maketext('Key Binding') %></th>
					<th class="text-nowrap"><%= maketext('Mac alternate') %></th>
					<th><%= maketext('Action') %></th>
				</tr>
			</thead>
			<tbody class="table-group-divider">
				<tr>
					<td>Ctrl-m</td>
					<td>Alt-Shift-m</td>
					<td>
						<%= maketext('Enable or disable tab-focus mode. When tab-focus mode is off, pressing Tab '
							. 'inside the editor window indents the current line. When tab-focus mode is on '
							. 'Tab and Shift-Tab move focus out of the editor window.') %>
					</td>
				<tr>
					<td>Ctrl-Shift-[</td>
					<td>Cmd-Shift-[</td>
					<td>
						<%= maketext('Fold the region that begins on the current line. Triangles in the gutter '
						. 'next to line numbers indicate which regions can be folded.') %>
					</td>
				</tr>
				<tr>
					<td>Ctrl-Shift-]</td>
					<td>Cmd-Shift-]</td>
					<td><%= maketext('Unfold the region that begins on the current line.') %></td>
				</tr>
				<tr><td>Ctrl-Alt-[</td><td>Cmd-Alt-[</td><td><%= maketext('Fold all regions.') %></td></tr>
				<tr><td>Cmd-Alt-]</td><td>Cmd-Alt-]</td><td><%= maketext('Unfold all regions.') %></td></tr>
				<tr><td>Ctrl-/</td><td>Cmd-/</td><td><%= maketext('Toggle comment.') %></td></tr>
				<tr>
					<td>Shift-Alt-a</td>
					<td></td>
					<td><%= maketext('Toggle block comment. (Only has effect inside PGML blocks.)') %></td>
				</tr>
				<tr>
					<td>Ctrl-Space</td>
					<td>Alt-`</td>
					<td><%= maketext('Show available autocompletions at the current cursor location.') %></td>
				</tr>
			</tbody>
		</table>
	</dd>
	<dt><%= maketext('Text Editor Options') %></dt>
	<dd class="list-group-item">
		<dl>
			<dt><%= maketext('Theme') %></dt>
			<dd><%= maketext('Select your favorite theme for the large text window.') %></dd>
			<dt><%= maketext('Key Map') %></dt>
			<dd>
				<%= maketext('The key maps that are available are "default", "emacs", "sublime", and "vim". The '
					. '"default" key map has the standard behavior of a browser text area. You can use Ctrl-C to copy, '
					. 'Ctrl-V to paste, Ctrl-F to search, etc. If you are more comfortable with the "emacs" '
					. ' or "vim" text editors then you may choose to use one of those key maps instead.') =%>
			</dd>
			<dt><%= maketext('Enable Spell Checking') %></dt>
			<dd>
				<%= maketext('Spell check the text of the file that your are editing. Note that there will be many '
					. 'spelling errors in the code parts of your file.') =%>
			</dd>
			<dt><%= maketext('Force RTL') %></dt>
			<dd>
				<%= maketext('Force the editor to display text from right-to-left. '
					. '(Note that this does not persist when reloading the page.)') =%>
			</dd>
		</dl>
	</dd>
</dl>

<h2><%= maketext('Actions:') %></h2>
<i><%= maketext('(If an action cannot be executed it will not appear.)') %></i>
<dl>
	<dt><%= maketext('View/Reload') %></dt>
	<dd>
		<%= maketext('Render or re-render the problem, course info file, or set header being edited. This does not '
			. 'change the permanent file on the disk. You can view different versions of the same problem by changing '
			. 'the seed. You can also change the manner in which the mathematics is typeset. If "Open in new window" '
			. 'is checked, then the problem will open in a new tab or window showing the problem as it will be '
			. 'rendered for students in the set.') =%>
	</dd>

	<dt><%= maketext('Generate Hardcopy') %></dt>
	<dd>
		<p>
		<%= maketext('Generate a hardcopy of the problem being edited. This does not change the permanent file on the '
			. 'disk. You can generate a hardcopy for different versions of the same problem by changing the seed. You '
			. 'can also change the format to "PDF" or "TeX Source". If "PDF" is selected, then a PDF file will be '
			. 'generated for download, unless there are errors. If errors occur or "TeX Source" is selected, then a '
			. 'zip file will be generated for download that contains the TeX source file and resources needed for '
			. 'generating the PDF file using LaTeX.') =%>
		</p>
		<p>
		<%= maketext('You can also click "Edit Selected Theme" to edit a hardcopy theme.  The new theme will be saved '
			. 'to the templates/hardcopyThemes folder.') =%>
		</p>
	</dd>

	<dt><%= maketext('Code Maintenance') %></dt>
	<dd>
		<%= maketext('Three code maintenance tools can be utilized. First, the code can be reformatted using perltidy. '
		. 'Using perltidy will change the code in the editor window, and save changes to the temporary file. In some '
		. 'cases (if the code contains backslashes or double tildes) this can result in odd spacing in the code. '
		. 'Second the code can be converted to PGML. This changes the code in text blocks to use PGML features. '
		. 'Generally the conversion of much of the formatting and LaTeX is performed correctly. However, answer '
		. 'blanks need attention. In any case, make sure to inspect the formatted code, and edit further or revert '
		. 'if needed. Third, the code can be analyzed by the "PG Critic." This checks that the code does not use '
		. 'old or deprecated features of PG and conforms to current best-practices in problem authoring, and offers '
		. 'suggestions on how to fix issues that are found.') =%>
	</dd>

	<dt><%= maketext('Save') %></dt>
	<dd>
		<%= maketext('Save the contents of the editor window to the file on disk and re-render the problem. If '
			. '"Open in new window" is checked, then the problem will open in a new tab or window showing the problem '
			. 'as it will be rendered for students in the set. If "Create backup" is checked then a backup of the '
			. 'current file on disk will be created before overwriting it with the contents of the editor window. If a '
			. 'backup already exists, then a "Delete oldest backup" check box will be present. If that is checked, '
			. 'then the oldest backup will be deleted when "Save" is clicked. These backups can be reverted '
			. 'to and managed on the "Revert" tab.') =%>
	</dd>

	<dt><%= maketext('Save As') %></dt>
	<dd>
		<p>
			<%= maketext(q{Makes a new copy of the file you are editing at the location relative to the course's }
				. 'templates (~[TMPL~]) directory. You may choose to replace the current problem in the current set, '
				. 'append to the end to then end of the current set as a new problem, or create a problem that is not '
				. 'attached to a problem set.') =%>
		</p>
		<p>
			<%= maketext('When saving the problem in a new location (directory), by default all auxiliary files, such '
				. 'as images, or other files that do not end in ".pg", will also be copied to the new location.  To '
				. 'stop this behavior, uncheck the "Copy auxiliary files" option.') =%>
		</p>
		<p>
			<%= maketext('You may want to create an unattached problem if you are using the current problem as a model '
				. 'for a new problem. You can add the new file to a homework set from the Library Browser or via the '
				. 'set detail page of the "Sets Manager".') =%>
		</p>
		<p>
			<%= maketext('If the original problem cannot be edited than the path name must be changed in order to be '
				. 'allowed to save the problem. Adding "local/" to the beginning of the original path is the default '
				. 'solution. All locally created and edited files will then appear in a subdirectory named '
				. '"local".') =%>
		</p>
		<p class="mb-0">
			<%= maketext('A new problem whose path ends in newProblem.pg should be given a new name, for example, '
				. '"myNewProblem.pg".') =%>
		</p>
	</dd>

	<dt><%= maketext('Append') %></dt>
	<dd>
		<%= maketext('Add this problem as the last problem of an existing set, either as a problem or as the set '
			. 'header (the text that appears on the home page of a homework set). You can rearrange the order of the '
			. 'problems later using the "Sets Manager".') =%>
	</dd>

	<dt><%= maketext('Revert') %></dt>
	<dd>
		<%= maketext('Reverts to the copy of the file saved on the disk or to a backup file. All unsaved editing '
			. 'changes will be lost. This option is only active when a temporary file or a backup file exists. You '
			. 'may also delete backups that have been made with this tab.') =%>
	</dd>
</dl>