diff --git a/.gitignore b/.gitignore index 789a3e6..d1ffc8d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ *.pyc /extensions/debug.log /dist -/__pycache__ \ No newline at end of file +/__pycache__ +/readme.html \ No newline at end of file diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..a7a3d1a --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,32 @@ +Copyright (c) 2015-18 by Mark Lillibridge. + +Copyright (c) 2012-15 by Hewlett-Packard Development Company, L.P. + +Copyright (c) 2002-2011 by Rick Mohr. + +Mark says: +I am providing code in this repository to you under an open source +license. Because this is my personal repository, the license you +receive to my code is from me and not from my employer (Facebook). + + +[MIT license] + + Permission is hereby granted, free of charge, to any person +obtaining a copy of this software and associated documentation files +(the "Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + + The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index c4ac22e..010ba34 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,132 @@ -Temporary README.md +## Synopsis + +Vocola is a **vo**ice **co**mmand **la**nguage — a language for +creating commands to control a computer by voice — created by Rick +Mohr. Two versions are available: Vocola 2 works with Dragon +NaturallySpeaking (DNS) and Vocola 3 works with Windows Speech +Recognition (WSR) on Windows 8, 7, and Vista. This repository contains +the source code for Vocola 2. While DNS and WSR handle the heavy +lifting, Vocola (pronounced "vo-CO-luh") concentrates on features and +ease of use. In particular, Vocola offers the following: + +Easy to use: + +* Simple, concise command syntax—most commands are one-liners +* Easy to view and modify commands +* Changed commands are loaded automatically +* Large set of useful sample commands +* Free + +Features: + +* Create commands which capture any dictated words +* Use concise number ranges, optional words, and inline word lists +* Specify different actions for variable words +* Speak a continuous sequence of commands +* Re-use work with include files and user-defined functions + +Complete documentation can be found at the Vocola website. + + +## Examples + +Here are four voice commands defined in Vocola: + + Copy That = {Ctrl+c}; + Copy to WordPad = {Ctrl+a}{Ctrl+c} AppBringUp(WordPad); + 1..40 (Left | Right | Up | Down) = {$2_$1}; + Sort by (Date=e | Sender=n | Subject=s) = {Alt+v}o $1; + +The first is a simple keystroke command—saying "Copy That" sends the +keystroke Control-C, which copies the current selection to the +clipboard. The great majority of commands needed for controlling a +computer by voice are simple keystroke commands like this. + +The second command, invoked by saying "Copy to WordPad", copies a window +of text (Control-A selects all text and Control-C copies it) and brings +up the WordPad editor (using the built-in function AppBringUp). + +The third command allows controlling the cursor, by saying for example +"3 Left" to move left three characters, or "6 Down" to move down six +lines. Spoken words match variable terms on the left and are +substituted into the keystroke sequence on the right. For example, when +saying "3 Left" the spoken "3" matches the numeric range `1..40` and the +spoken "Left" matches the alternative set `(Left | Right | Up | Down)`. +The keystroke sequence `{Left 3}` is constructed and sent, and the +cursor moves left three characters. + +The fourth command allows sorting messages in Mozilla's Thunderbird +Mailer, by saying "Sort by Date", "Sort by Sender", or "Sort by +Subject". The matched word "Date", "Sender", or "Subject", causes the +appropriate keystroke "e", "n", or "s" to be inserted into the keystroke +sequence, choosing the desired option in Thunderbird's View > Sort menu. + + +## Why a custom voice command language? + +Other systems for defining voice commands are grafted onto existing +programming languages. This means you can program any behavior you +want, but you're stuck with the syntactic overhead of the base language. +In contrast, Vocola is designed specifically as a voice command +language, not as a general-purpose programming language. This means you +can write quickly and concisely the great majority of voice commands you +need, and use another language in the few cases where you need more +power. + +When I (Rick) switched from the Dragon Macro Language to Vocola I was +able to convert all but two of my 200+ Dragon macros (achieving a source +line count reduction of roughly 6:1) and at this writing use well over +1,000 Vocola commands. + + +## Installation + +Natlink and Vocola2 have been upgraded to Python 3 fom Python 2. + +The current Vocola2 Unimacro is stable, but not yet released. Install from the [Test Python Package Index](https://test.pypi.org/) +with the following. + +`pip install --no-cache --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple vocola2` + +Instructions for installing the latest released version can be found at +http://vocola.net/v2/InstallVocola.asp + +To install the version checked out in your git repository, +uininstall vocoal +`pip uninstall vocola2` + +In your root of your repository: +`build_package +flit install --symlink` + + + +## Tests + +To be written: describe and show how to run the tests with code +examples. + + +## Contributors + +To be written: let people know how they can dive into the project, +include important links to things like issue trackers, irc, twitter +accounts if applicable. + + +## License + +MIT (see LICENSE.txt) + + + + + + +# Location of Samples + +sample commands installed with Vocolas2 will be installed in: +the Lib\site-packages\vocola2\samples subfolder of your +Python installation. Good ones to start with include msedge.vcl for sending commands to Microsoft Edge. -All Vocola stuff is now (2020-12-18) in the src/vocola2 directory (Doug/Quintijn) \ No newline at end of file diff --git a/build_package.cmd b/build_package.cmd new file mode 100644 index 0000000..43e7a1c --- /dev/null +++ b/build_package.cmd @@ -0,0 +1 @@ +flit build --format sdist --no-setup-py \ No newline at end of file diff --git a/compile_README.cmd b/compile_README.cmd new file mode 100644 index 0000000..bae8f31 --- /dev/null +++ b/compile_README.cmd @@ -0,0 +1,5 @@ +@echo for testing the README.md. +@echo the outpout is not used for publishing. it is only so you know your README.md will +@echo compile ok before publishing with flit. + +python -m markdown README.md > README.html diff --git a/publish_package_pypi.cmd b/publish_package_pypi.cmd new file mode 100644 index 0000000..d06db5d --- /dev/null +++ b/publish_package_pypi.cmd @@ -0,0 +1 @@ +flit publish --format sdist --no-setup-py --repository pypi \ No newline at end of file diff --git a/publish_package_tesetpypi.cmd b/publish_package_tesetpypi.cmd new file mode 100644 index 0000000..b99fc8c --- /dev/null +++ b/publish_package_tesetpypi.cmd @@ -0,0 +1 @@ +flit publish --format sdist --no-setup-py --repository testpypi \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 594fee6..b5928aa 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -10,7 +10,7 @@ home-page = "https://github.com/dictation-toolbox/unimacro" description-file = "README.md" module="vocola2" requires=["unimacro", - "natlink"] + "natlinkpy"] classifiers=[ "Development Status :: 4 - Beta", diff --git a/src/vocola2/__init__.py b/src/vocola2/__init__.py index 43d8d1c..882ada2 100644 --- a/src/vocola2/__init__.py +++ b/src/vocola2/__init__.py @@ -1,3 +1,3 @@ """Vocola""" -__version__ = '0.1.0.2' +__version__ = '0.1.0.4'