Prerequisite:
Learn about how to write "regular expressions" to match patterns in the text.
Create the expression(s) you want to search for and test them with the regex: prefix in the search dialog. When you have your expression working, you can follow the steps below to create your entry in the Custom Tools menu.
Create the Files
- Make copies of the
SampleCheck and
SampleCheck files.
- Rename them both to reflect the check you will be doing.
Set up the CMS file
\check
This is followed by a space and the name of the check. This check will be featured in the project menu of Paratext under Tools -> Custom tools
\description
The description will show in the dialog that pops up when selecting the check from the menu:
\helpFile
Optionally include an rtf file here. This will place a help button on the dialog box that opens the rtf file. (Not sure if it needs to be RTF -- what about html? Someone try it and update the instructions)
\subMenu
You can create a new submenu for your scripts or include them in one of the existing submenus just by naming it here. Many scripts are listed in the Unsupported menu, but we are not a fan of unsupported products. If your script is designed to help people, wouldn't you want to follow through?
\script
This must point to the name of the python file that you will be editing in the next step.
\rank
This determines where your plugin shows in the list. Rank 1 is near the top. If only Google made it this easy...
Edit the Python File
The Python file contains a number of options that can be configured, and the more you know about Python, the more these will make sense to you. For the most basic RegEx check, you can just comment out this line by typing # in front of it:
# patterns.addPattern(r"\bhad had\b")
Then add your regular expression in the next session that contains the bad pattern you are looking for.
Example:
patterns.addPattern(r"\\v[0-9]", "Missing space after \\v")
Testing your Check
If you run the check and it fails, you may need to use a Python debugger to troubleshoot. You can download the free ActivePython development envirnonment from ActiveState.com. Then you can step through the check in the Python debugger by opening the file tmp.py from the My Paratext Projects\cms directory.
Reference
This reference contains all of the commands that are found in the existing cms file. Because the documentation is sparse, we will add a description as we learn what they do.
\books
Places the Book selector on the dialog:
\check
The name of the check. This check will be featured in the project menu of Paratext under Tools -> Custom tools
\description
The description will show in the dialog that pops up when selecting the check from the menu:
\helpFile
Adding an RTF file will add a help button to the dialog which will open the RTF file
\noText
No idea
\optionDefault
Which setting should this option default to?
\optionDescription
Describe the purpose of this option
\optionHidden
No idea
\optionListAllTexts
?Select box to select a project from all installed projects
\optionLocalized
?Provide options in an additional language. Don't know how this works.
\optionLocalizedName
This is the name which the user will see
\optionName
This is the name by which the option will be know to the python program. It must begin with a letter and not include anything except letters and numbers.
\outputProject
The project to send the results to.
\parameter1
Request user input as a text variable.
\parameter2
Request user input as a text variable
\programToRun
Usually Python
\rank
The order this will show in the Paratext menu
\script
The name of the Python script to run
\subMenu
The submenu you want this script listed under
\supportMessage
No idea
\toHtml
Send output to html
\toList
Send output to the Paratext list
\toText
Send output to a text file
\utf8
Send output in utf8 (probably not needed anymore)
\wordlist
No idea