| Name | errers JSON |
| Version |
3.2.1
JSON |
| download |
| home_page | |
| Summary | ERRERS: Enhanced Review of Reports via Extraction using Rule-based Substitutions |
| upload_time | 2024-03-06 20:25:23 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.6 |
| license | |
| keywords |
latex
grammar
spelling
regular expression
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
..
SPDX-FileCopyrightText: 2023 His Majesty in Right of Canada
SPDX-License-Identifier: LicenseRef-MIT-DND
This file is part of the ERRERS package.
=========================
ERRERS: Quick Start Guide
=========================
Purpose
=======
ERRERS 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.
Requirements
============
ERRERS 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; and
pywin32 (Windows only)
Enables creation of shortcuts and inclusion of a "Check" button to initiate
grammar and spell check in Microsoft Word.
Installation
============
Option 1
--------
ERRERS is distributed as a platform-independent Python package, which requires
a local Python installation. To install it:
1. 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.
2. Type ``python3 -m pip install errers`` and press enter. On some systems, you
may need to use ``py`` or ``python`` rather than ``python3``. You may also
need to use ``pipx`` rather than ``pip``.
3. Type ``errers --shortcuts`` at the command prompt and press enter.
4. 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:
a) On Windows: Desktop, "Send To" menu, and Start menu;
b) On macOS: user Applications folder, Launchpad, and "Open with" menu; and
c) On Linux: Desktop (or Home directory), Application menu, and "Open With"
menu.
5. 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 2
--------
If pip cannot download ERRERS at step 2 above, you may be able to download it
manually from https://pypi.org/project/errers/#files. If so:
1. Obtain the installation file: errers-VERSION-py3-none-any.whl, where VERSION
represents the version number of ERRERS that you wish to install.
2. Open a command prompt or shell from which Python can be run.
3. At the command prompt, change directory to the location of the installation
file from step 1.
4. Type ``python3 -m pip install WHEEL`` and press enter, where ``WHEEL`` is
the name of the installation file from step 1. On some systems, you may need
to use ``py`` or ``python`` rather than ``python3``. You may also need to
use ``pipx`` rather than ``pip``.
5. Continue with step 3 to 5 of option 1.
Notes
-----
The 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-deps`` when calling pip, which omits package dependencies:
``python3 -m pip install --no-deps errers`` or
``python3 -m pip install --no-deps WHEEL``. 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 from
https://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.
Removal
=======
To remove ERRERS:
1. 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.
2. Type ``errers --shortcuts`` at the command prompt and press enter.
3. 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.
4. Type ``python3 -m pip uninstall errers`` and press enter. On some systems,
you may need to use ``py`` or ``python`` rather than ``python3``. You may
also need to use ``pipx`` rather than ``pip``.
Usage
=====
GUI
---
1. Drag 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.
2. 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.
3. 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.
4. 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-line
------------
ERRERS can also be used from the command-line. Type ``errers -h`` at the
command prompt and press enter for more information.
Customization
=============
The 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:
1. 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.
2. 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>, ...
3. 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.
4. 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 information
======================
More 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.
Acknowledgements
================
The 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.
License
=======
The 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.
Raw data
{
"_id": null,
"home_page": "",
"name": "errers",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "LaTeX,grammar,spelling,regular expression",
"author": "",
"author_email": "\"Steve Guillouzic, Defence Research and Development Canada\" <steve.guillouzic@forces.gc.ca>",
"download_url": "",
"platform": null,
"description": "..\n SPDX-FileCopyrightText: 2023 His Majesty in Right of Canada\n\n SPDX-License-Identifier: LicenseRef-MIT-DND\n\n This file is part of the ERRERS package.\n\n=========================\nERRERS: Quick Start Guide\n=========================\n\nPurpose\n=======\nERRERS stands for \"Enhanced Review of Reports via Extraction using Rule-based\nSubstitutions\". It extracts text from LaTeX files so as to reduce the number of\nfalse positives when checking grammar and spelling with Microsoft Word or other\nsoftware. It is performed through the application of substitution rules based\non regular expressions.\n\nRequirements\n============\n\nERRERS runs on Python 3, more specifically version 3.6 or more recent. Version\n3.2 was tested on Microsoft Windows 10 and 11, Apple macOS 14, and Debian\nGNU/Linux 12. It uses the third-party regex module if available\n(https://pypi.org/project/regex), as it allows for faster execution, but\ndefaults back to the standard re module if not.\n\nThe Python distribution provided by Apple on macOS includes an older version of\nthe Tkinter GUI library with which ERRERS is not compatible, but it can still\nbe used in command-line mode. To use ERRERS in GUI mode on that platform, an\nalternate version of Python must be installed, such as those available from the\nPython website (https://www.python.org/). On macOS 14, it is preferable to use\nPython 3.11.7 or more recent, as buttons may become unresponsive with the\nversion of Tkinter included in earlier versions. There are two workarounds for\nthe unresponsiveness bug if upgrading Python is not an option: the first is to\nuse keyboard shortcuts, and the second one is to move the window (which\nreactivates the buttons).\n\nERRERS depends on two third-party Python packages:\n\nregex (all platforms)\n Provides faster and more robust processing of regular expressions; and\n\npywin32 (Windows only)\n Enables creation of shortcuts and inclusion of a \"Check\" button to initiate\n grammar and spell check in Microsoft Word.\n\nInstallation\n============\n\nOption 1\n--------\n\nERRERS is distributed as a platform-independent Python package, which requires\na local Python installation. To install it:\n\n1. Open a command prompt or shell from which Python can be run. For instance,\n with the Anaconda Python distribution, you would choose Programs >>\n Anaconda3 >> Anaconda Prompt in the Windows Start menu.\n2. Type ``python3 -m pip install errers`` and press enter. On some systems, you\n may need to use ``py`` or ``python`` rather than ``python3``. You may also\n need to use ``pipx`` rather than ``pip``.\n3. Type ``errers --shortcuts`` at the command prompt and press enter.\n4. In the shortcut-update window that appears, choose the locations where you\n would like application shortcuts to be created and click \"Create\". The\n available locations vary from one operating system to another:\n\n a) On Windows: Desktop, \"Send To\" menu, and Start menu;\n b) On macOS: user Applications folder, Launchpad, and \"Open with\" menu; and\n c) On Linux: Desktop (or Home directory), Application menu, and \"Open With\"\n menu.\n\n5. Copy shortcuts to other locations if desired. For instance, on Windows, one\n of them could be pinned to the taskbar; on macOS, it could be added to the\n Dock.\n\nOption 2\n--------\n\nIf pip cannot download ERRERS at step 2 above, you may be able to download it\nmanually from https://pypi.org/project/errers/#files. If so:\n\n1. Obtain the installation file: errers-VERSION-py3-none-any.whl, where VERSION\n represents the version number of ERRERS that you wish to install.\n2. Open a command prompt or shell from which Python can be run.\n3. At the command prompt, change directory to the location of the installation\n file from step 1.\n4. Type ``python3 -m pip install WHEEL`` and press enter, where ``WHEEL`` is\n the name of the installation file from step 1. On some systems, you may need\n to use ``py`` or ``python`` rather than ``python3``. You may also need to\n use ``pipx`` rather than ``pip``.\n5. Continue with step 3 to 5 of option 1.\n\nNotes\n-----\n\nThe installation procedures above fail if regex is not available. On Windows,\nthey also fail if pywin32 is not available. If for some reason these two\npackages cannot be installed, the installation can be forced by using option\n``--no-deps`` when calling pip, which omits package dependencies:\n``python3 -m pip install --no-deps errers`` or \n``python3 -m pip install --no-deps WHEEL``. Without regex, text extraction will\nbe slower. Without pywin32 on Windows, shortcut creation will not be available,\nand the \"Check\" button will be missing.\n\nInstallation files can also be downloaded from\nhttps://github.com/steve-guillouzic-gc/errers/releases, where pre-release\nversions will also be made available.\n\nLocal network administrators may offer other methods of installing ERRERS. For\ninstance, the ERRERS source code is distributed with a script that bundles it\ninto a standalone Windows application that does not require Python. This is not\ncovered here, as it is outside the scope of this manual.\n\nRemoval\n=======\n\nTo remove ERRERS:\n\n1. Open a command prompt or shell from which Python can be run. For instance,\n with the Anaconda Python distribution, you would choose Programs >>\n Anaconda3 >> Anaconda Prompt in the Windows Start menu.\n2. Type ``errers --shortcuts`` at the command prompt and press enter.\n3. In the shortcut-update window that appears, click \"Delete\" to delete\n application shortcuts. If shortcuts had been copied to other locations, they\n must be deleted manually.\n4. Type ``python3 -m pip uninstall errers`` and press enter. On some systems,\n you may need to use ``py`` or ``python`` rather than ``python3``. You may\n also need to use ``pipx`` rather than ``pip``.\n\nUsage\n=====\n\nGUI\n---\n\n1. Drag the LaTeX file and drop it on one of the shortcuts created during \n installation, or right-click on the LaTeX file and choose ERRERS under the\n \"Send To\" menu (on Windows) or \"Open with\" menu (on macOS and Linux). This\n launches the application GUI with the input file path already filled out.\n Alternately, one can launch the application from one of the shortcuts and\n click on the input field to choose the file.\n2. Click on the \"Extract\" button. This creates a text file named INPUT-dy.txt\n in the same directory as the LaTeX file, where INPUT is the stem of the\n input file name. Errors and warnings are shown in the \"Extraction log\" box\n at the bottom left of the main window, including a list of remaining LaTeX\n commands (if any). A more detailed log is saved to INPUT-dy-log.txt.\n3. Click on the \"Copy\" button to copy the text file to the clipboard, and paste\n it into a grammar and spell checking application. (Text must be pasted\n before closing ERRERS.) Alternately, on Windows, one can click on the\n \"Check\" button to load the text file into MS Word and start the grammar and\n spelling check automatically.\n4. Errors can be reported to the developer using the email address provided in\n the top left of the window or the command-line help text.\n\nCommand-line\n------------\n\nERRERS can also be used from the command-line. Type ``errers -h`` at the\ncommand prompt and press enter for more information.\n\nCustomization\n=============\n\nThe extraction is performed through the application of substitution rules based\non regular expressions. The current set of rules covers the most common LaTeX\ncommands, and additional rules will be added over time. Rules are created\nautomatically for LaTeX commands defined in the document using \\\\newcommand,\n\\\\rewnewcommand, \\\\providecommand, \\\\def, \\\\edef, \\\\gdef, and \\\\xdef. In many\ncases, there is no need for users to define additional substitution rules.\n\nHowever, if needed, rules can be defined directly in LaTeX documents; such\nrules are applied first and can be used to override those provided with ERRERS\nor determined automatically from command definitions. When installed as Python\npackage rather than standalone application, users can also place custom rules\nin a local.py file saved to the rules sub-directory of the ERRERS installation\nfolder so they can be applied to all their documents.\n\nThe substitution rules being based on regular expressions, the first step in \nlearning how to create new rules is to look at the re module page: \nhttps://docs.python.org/3/library/re.html.\n\nThe ERRERS package provides LaTeX-specific sequences for use in regular \nexpressions:\n\n1. The %c, %r, and %s strings are replaced with patterns that respectively\n match pairs of curly, round, and square brackets with arbitrary content in\n between. The content of these bracket pairs is accessed in substitution\n strings as sequentially numbered named groups: \\\\g<c1>, \\\\g<c2>, ... for %c\n placeholders; \\\\g<r1>, \\\\g<r2>, ... for %r; and \\\\g<s1>, \\\\g<s2>, ... for\n %s.\n2. The %C string is replaced with a pattern that, in addition to matching curly\n brackets with arbitrary content, can also match an unbracketed LaTeX command\n or single character. This matches how curly brackets are handled in LaTeX.\n The captured text is accessed using the same sequence of named groups as %c:\n \\\\g<c1>, \\\\g<c2>, ...\n3. The %h, %n, and %w strings are replaced with patterns that match optional\n white space: %h matches an arbitrary amount of horizontal white space (space\n or tab), including none; %n is similar to %h, but may also include at most\n one newline character; and %w is similar to %n, but may include an arbitrary\n number of newline characters.\n4. The %m string is replaced by a pattern that matches the name of LaTeX\n commands (or \"macros\"). This is used internally by ERRERS but is unlikely to\n be needed in regular substitution rules.\n\nFor instance, Rule(r'\\\\\\\\foo%C%C', r'\\\\g<c1>') substitutes each occurrence of a\ntwo-argument \\\\foo command with the content of its first argument. If the rule\nshould be applied only when the arguments are in curly brackets, %C should be\nreplaced with %c. To use it in a given document, add the following line\nanywhere in the LaTeX file:\n\n% Rule(r'\\\\\\\\foo%C%C', r'\\\\g<c1>')\n\nAdditional information\n======================\n\nMore information can be found in the user manual:\nhttps://cradpdf.drdc-rddc.gc.ca/PDFS/unc459/p813656_A1b.pdf.\n\nA list of changes from one version to the next is provided in the change log:\nhttps://github.com/steve-guillouzic-gc/errers/blob/main/CHANGELOG.rst.\n\nIf you wish to contribute to the development of ERRERS, please see the\nCONTRIBUTING file:\nhttps://github.com/steve-guillouzic-gc/errers/blob/main/CONTRIBUTING.rst.\n\nThe source code is hosted on GitHub:\nhttps://github.com/steve-guillouzic-gc/errers.\n\nAcknowledgements\n================\n\nThe following people contributed to the project:\n\n- Patrick Dooley, Pierre-Luc Drouin, Fred Ma, Matthew MacLeod, Paul Melchin,\n and Stephen Okazawa helped brainstorm the name for the tool.\n- Janice Lang suggested the original idea for the icon, and Adison Rossiter\n designed it using the Google Poppins font\n (https://fonts.google.com/specimen/Poppins).\n- Pierre-Luc Drouin, Joshua Goldman, Fred Ma, and Paul Melchin helped with beta\n testing.\n \nLicense\n=======\n\nThe ERRERS source code is distributed under the MIT license\n(https://spdx.org/licenses/MIT). The LICENSES directory in the source code,\nwheel, and source distribution files contains the text of the license.\n",
"bugtrack_url": null,
"license": "",
"summary": "ERRERS: Enhanced Review of Reports via Extraction using Rule-based Substitutions",
"version": "3.2.1",
"project_urls": {
"Bug tracker": "https://github.com/steve-guillouzic-gc/errers/issues",
"Change log": "https://github.com/steve-guillouzic-gc/errers/blob/main/CHANGELOG.rst",
"Contribution guidelines": "https://github.com/steve-guillouzic-gc/errers/blob/main/CONTRIBUTING.rst",
"Source code": "https://github.com/steve-guillouzic-gc/errers",
"User manual": "https://cradpdf.drdc-rddc.gc.ca/PDFS/unc459/p813656_A1b.pdf"
},
"split_keywords": [
"latex",
"grammar",
"spelling",
"regular expression"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "956c33a250fa8691f65d5a94fcfe9182c84cd7f777466017b02bb0b57797d20c",
"md5": "1b3783ac9a5417bf21b72686b0f45a34",
"sha256": "5abbef3236f54f50a8bc04be0f1df8d41c5bf492fe9dea45417fa07773694e04"
},
"downloads": -1,
"filename": "errers-3.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b3783ac9a5417bf21b72686b0f45a34",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 146542,
"upload_time": "2024-03-06T20:25:23",
"upload_time_iso_8601": "2024-03-06T20:25:23.326162Z",
"url": "https://files.pythonhosted.org/packages/95/6c/33a250fa8691f65d5a94fcfe9182c84cd7f777466017b02bb0b57797d20c/errers-3.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-06 20:25:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "steve-guillouzic-gc",
"github_project": "errers",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "errers"
}
