Package: errers
PurposeERRERS stands for “Enhanced Review of Reports via Extraction using Rule-based
Substitutions”. It extracts text from LaTeX files so as to reduce the number of
false positives when checking grammar and spelling with Microsoft Word or other
software. It is performed through the application of substitution rules based
on regular expressions.RequirementsERRERS runs on Python 3, more specifically version 3.6 or more recent. Version
3.2 was tested on Microsoft Windows 10 and 11, Apple macOS 14, and Debian
GNU/Linux 12. It uses the third-party regex module if available
(https://pypi.org/project/regex), as it allows for faster execution, but
defaults back to the standard re module if not.The Python distribution provided by Apple on macOS includes an older version of
the Tkinter GUI library with which ERRERS is not compatible, but it can still
be used in command-line mode. To use ERRERS in GUI mode on that platform, an
alternate version of Python must be installed, such as those available from the
Python website (https://www.python.org/). On macOS 14, it is preferable to use
Python 3.11.7 or more recent, as buttons may become unresponsive with the
version of Tkinter included in earlier versions. There are two workarounds for
the unresponsiveness bug if upgrading Python is not an option: the first is to
use keyboard shortcuts, and the second one is to move the window (which
reactivates the buttons).ERRERS depends on two third-party Python packages:regex (all platforms)Provides faster and more robust processing of regular expressions; andpywin32 (Windows only)Enables creation of shortcuts and inclusion of a “Check” button to initiate
grammar and spell check in Microsoft Word.InstallationOption 1ERRERS is distributed as a platform-independent Python package, which requires
a local Python installation. To install it:Open a command prompt or shell from which Python can be run. For instance,
with the Anaconda Python distribution, you would choose Programs >>
Anaconda3 >> Anaconda Prompt in the Windows Start menu.Typepython3-mpip install errersand press enter. On some systems, you
may need to usepyorpythonrather thanpython3. You may also
need to usepipxrather thanpip.Typeerrers--shortcutsat the command prompt and press enter.In the shortcut-update window that appears, choose the locations where you
would like application shortcuts to be created and click “Create”. The
available locations vary from one operating system to another:On Windows: Desktop, “Send To” menu, and Start menu;On macOS: user Applications folder, Launchpad, and “Open with” menu; andOn Linux: Desktop (or Home directory), Application menu, and “Open With”
menu.Copy shortcuts to other locations if desired. For instance, on Windows, one
of them could be pinned to the taskbar; on macOS, it could be added to the
Dock.Option 2If pip cannot download ERRERS at step 2 above, you may be able to download it
manually fromhttps://pypi.org/project/errers/#files. If so:Obtain the installation file: errers-VERSION-py3-none-any.whl, where VERSION
represents the version number of ERRERS that you wish to install.Open a command prompt or shell from which Python can be run.At the command prompt, change directory to the location of the installation
file from step 1.Typepython3-mpip install WHEELand press enter, whereWHEELis
the name of the installation file from step 1. On some systems, you may need
to usepyorpythonrather thanpython3. You may also need to
usepipxrather thanpip.Continue with step 3 to 5 of option 1.NotesThe installation procedures above fail if regex is not available. On Windows,
they also fail if pywin32 is not available. If for some reason these two
packages cannot be installed, the installation can be forced by using option--no-depswhen calling pip, which omits package dependencies:python3-mpip install--no-depserrersorpython3-mpip install--no-depsWHEEL. Without regex, text extraction will
be slower. Without pywin32 on Windows, shortcut creation will not be available,
and the “Check” button will be missing.Installation files can also be downloaded fromhttps://github.com/steve-guillouzic-gc/errers/releases, where pre-release
versions will also be made available.Local network administrators may offer other methods of installing ERRERS. For
instance, the ERRERS source code is distributed with a script that bundles it
into a standalone Windows application that does not require Python. This is not
covered here, as it is outside the scope of this manual.RemovalTo remove ERRERS:Open a command prompt or shell from which Python can be run. For instance,
with the Anaconda Python distribution, you would choose Programs >>
Anaconda3 >> Anaconda Prompt in the Windows Start menu.Typeerrers--shortcutsat the command prompt and press enter.In the shortcut-update window that appears, click “Delete” to delete
application shortcuts. If shortcuts had been copied to other locations, they
must be deleted manually.Typepython3-mpip uninstall errersand press enter. On some systems,
you may need to usepyorpythonrather thanpython3. You may
also need to usepipxrather thanpip.UsageGUIDrag the LaTeX file and drop it on one of the shortcuts created during
installation, or right-click on the LaTeX file and choose ERRERS under the
“Send To” menu (on Windows) or “Open with” menu (on macOS and Linux). This
launches the application GUI with the input file path already filled out.
Alternately, one can launch the application from one of the shortcuts and
click on the input field to choose the file.Click on the “Extract” button. This creates a text file named INPUT-dy.txt
in the same directory as the LaTeX file, where INPUT is the stem of the
input file name. Errors and warnings are shown in the “Extraction log” box
at the bottom left of the main window, including a list of remaining LaTeX
commands (if any). A more detailed log is saved to INPUT-dy-log.txt.Click on the “Copy” button to copy the text file to the clipboard, and paste
it into a grammar and spell checking application. (Text must be pasted
before closing ERRERS.) Alternately, on Windows, one can click on the
“Check” button to load the text file into MS Word and start the grammar and
spelling check automatically.Errors can be reported to the developer using the email address provided in
the top left of the window or the command-line help text.Command-lineERRERS can also be used from the command-line. Typeerrers-hat the
command prompt and press enter for more information.CustomizationThe extraction is performed through the application of substitution rules based
on regular expressions. The current set of rules covers the most common LaTeX
commands, and additional rules will be added over time. Rules are created
automatically for LaTeX commands defined in the document using \newcommand,
\rewnewcommand, \providecommand, \def, \edef, \gdef, and \xdef. In many
cases, there is no need for users to define additional substitution rules.However, if needed, rules can be defined directly in LaTeX documents; such
rules are applied first and can be used to override those provided with ERRERS
or determined automatically from command definitions. When installed as Python
package rather than standalone application, users can also place custom rules
in a local.py file saved to the rules sub-directory of the ERRERS installation
folder so they can be applied to all their documents.The substitution rules being based on regular expressions, the first step in
learning how to create new rules is to look at the re module page:https://docs.python.org/3/library/re.html.The ERRERS package provides LaTeX-specific sequences for use in regular
expressions:The %c, %r, and %s strings are replaced with patterns that respectively
match pairs of curly, round, and square brackets with arbitrary content in
between. The content of these bracket pairs is accessed in substitution
strings as sequentially numbered named groups: \g<c1>, \g<c2>, … for %c
placeholders; \g<r1>, \g<r2>, … for %r; and \g<s1>, \g<s2>, … for
%s.The %C string is replaced with a pattern that, in addition to matching curly
brackets with arbitrary content, can also match an unbracketed LaTeX command
or single character. This matches how curly brackets are handled in LaTeX.
The captured text is accessed using the same sequence of named groups as %c:
\g<c1>, \g<c2>, …The %h, %n, and %w strings are replaced with patterns that match optional
white space: %h matches an arbitrary amount of horizontal white space (space
or tab), including none; %n is similar to %h, but may also include at most
one newline character; and %w is similar to %n, but may include an arbitrary
number of newline characters.The %m string is replaced by a pattern that matches the name of LaTeX
commands (or “macros”). This is used internally by ERRERS but is unlikely to
be needed in regular substitution rules.For instance, Rule(r’\\foo%C%C’, r’\g<c1>’) substitutes each occurrence of a
two-argument \foo command with the content of its first argument. If the rule
should be applied only when the arguments are in curly brackets, %C should be
replaced with %c. To use it in a given document, add the following line
anywhere in the LaTeX file:% Rule(r’\\foo%C%C’, r’\g<c1>’)Additional informationMore information can be found in the user manual:https://cradpdf.drdc-rddc.gc.ca/PDFS/unc459/p813656_A1b.pdf.A list of changes from one version to the next is provided in the change log:https://github.com/steve-guillouzic-gc/errers/blob/main/CHANGELOG.rst.If you wish to contribute to the development of ERRERS, please see the
CONTRIBUTING file:https://github.com/steve-guillouzic-gc/errers/blob/main/CONTRIBUTING.rst.The source code is hosted on GitHub:https://github.com/steve-guillouzic-gc/errers.AcknowledgementsThe following people contributed to the project:Patrick Dooley, Pierre-Luc Drouin, Fred Ma, Matthew MacLeod, Paul Melchin,
and Stephen Okazawa helped brainstorm the name for the tool.Janice Lang suggested the original idea for the icon, and Adison Rossiter
designed it using the Google Poppins font
(https://fonts.google.com/specimen/Poppins).Pierre-Luc Drouin, Joshua Goldman, Fred Ma, and Paul Melchin helped with beta
testing.LicenseThe ERRERS source code is distributed under the MIT license
(https://spdx.org/licenses/MIT). The LICENSES directory in the source code,
wheel, and source distribution files contains the text of the license.