Revert "test"

This reverts commit a0682dc.

Commit a0682d contains numerous bits and pieces that shouldn't
have been published, so I'm reverting it.

Author: drmfinlay

README.rst

@@ -142,9 +142,6 @@ pip:
 
     pip install dragonfly
 
-
-### TODO Update this section to mention release candidates and link to both RTD stable/latest builds ###
-
 If you are installing this on Linux, you will also need to install the
 `wmctrl <https://www.freedesktop.org/wiki/Software/wmctrl/>`__, `xdotool
 <https://www.semicomplete.com/projects/xdotool/>`__ and `xsel

documentation/ccr.txt

@@ -23,7 +23,12 @@ a few projects using dragonfly which make writing CCR rules easier:
   (`documentation <https://dragonfluid.readthedocs.io>`__)
   --- dragonfluid has drop-in replacements for dragonfly's element, grammar
   and rule classes that support CCR. The documentation has more information
-  on this.
+  on this. You should be able to use `dragonfluid` with `dragonfly2` by
+  installing it without dependencies:
+
+  .. code:: shell
+
+     pip install --no-deps dragonfluid
 
 - `dragonfly-scripts
   <https://github.com/dictation-toolbox/dragonfly-scripts/>`__

documentation/faq.txt

@@ -41,9 +41,8 @@ Dragonfly supports the following speech recognition (SR) engines:
   work too.
 * :ref:`Windows Speech Recognition <RefSapi5Engine>` (WSR), included with
   Microsoft Windows Vista, Windows 7+, and freely available for Windows XP.
-* :ref:`Kaldi <RefKaldiEngine>`, open source (AGPL) and multi-platform.
-* :ref:`CMU Pocket Sphinx <RefSphinxEngine>`, open source and
-  multi-platform.
+* :ref:`Kaldi <RefKaldiEngine>`
+* :ref:`CMU Pocket Sphinx <RefSphinxEngine>`
 
 Dragonfly has cross platform support for Windows, macOS and Linux
 (X11-only).  The following table shows which engines are available on which
@@ -66,7 +65,9 @@ using Dragonfly voice macros on remote hosts.
 Dragonfly's X11 support is dependent on the external *xdotool*, *wmctrl*
 and *xsel* programs.  These programs are available for most Linux
 distributions.  They are also available for other operating systems, such as
-FreeBSD.
+FreeBSD.  At present, since *xdotool* is not available for it, Dragonfly
+will not work properly in a Cygwin environment.
+
 
 Where can I find examples Dragonfly command modules?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -80,18 +81,25 @@ example command modules in `dragonfly/examples`_.
 What is the difference between dragonfly and dragonfly2?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The names *dragonfly* and *dragonfly2* are two distribution names for the
-same package.  They are now synonymous as of version 1.0.0 of the library.
-Prior to that version, *dragonfly2* was the distribution name since 2008.
+*Dragonfly* is the `original project`_ written by Christo Butcher.  It is no
+longer maintained.  *Dragonfly2* is a `fork`_ of Dragonfly that uses a
+different *distribution* name.
 
 It is important to note that the *import name* is still "dragonfly":
 
 .. code-block:: python
 
    from dragonfly import Grammar, MappingRule, Key, Text, Mouse, Dictation
 
-Dragonfly2 started out as a backwards-compatible continuation of the
-original project written by Christo Butcher.
+Dragonfly2 is intended to be backwards-compatible continuation of the
+original project.  Many problems are fixed in this version.  It supports
+alternative speech recognition engine backends (e.g. the
+:ref:`Kaldi engine <RefKaldiEngine>`), works with Python 3 and has
+cross-support for macOS and the X Window System (X11).  Dragonfly2 also has
+some new features not found in the old version.
+
+See the :ref:`changelog <RefChangelog>` for the full list of changes between
+the two versions.
 
 
 How can I use older Dragonfly scripts written for Python 2.7?
@@ -120,6 +128,19 @@ end:
 
 The `Python 2-3 code porting guide`_ may also be of interest.
 
+A number of older Dragonfly command modules also include the following code:
+
+.. code-block:: python
+
+   try:
+       import pkg_resources
+       pkg_resources.require("dragonfly >= 0.6.5")
+   except ImportError:
+       pass
+
+Since the distribution name has been changed to *dragonfly2*,
+:code:`dragonfly` will need to be replaced with :code:`dragonfly2`.
+
 
 Where are some good resources on learning Python?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

documentation/kaldi_engine.txt

@@ -110,8 +110,8 @@ distributions, you can get them by running::
 
   sudo apt install wmctrl xdotool xsel
 
-Dragonfly only supports the X window system (X11) on Linux.  You may also
-need to manually set the ``DISPLAY`` environment variable.
+You may also need to manually set the ``DISPLAY`` environment
+variable.
 
 Once the dependencies and model are installed, you're ready to go!
 

documentation/language.txt

@@ -1,13 +1,9 @@
 
-.. _RefLanguage:
-
-Language sub-package
+Spoken Language Support
 ============================================================================
 
 This section documents Dragonfly's support for spoken languages.
 
-TODO Move engine-specific sections into the relevant engine pages.
-TODO Document the languages Split this file and the documentation for dragonfly.language.
 
 Languages with speech recognition engine support
 ----------------------------------------------------------------------------
@@ -31,18 +27,59 @@ U.S. English and U.K. English will both yield :code:`"en"` and be treated as
 the same language, even though there are some differences.
 
 
+Languages supported by Dragon
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following languages are supported by *Dragon Professional Individual*
+version 15 [#f1]_:
+
+* English (multiple variants)
+* Dutch
+* French
+* German
+* Italian
+* Spanish
+
+Please check the linked Nuance knowledgebase page for the languages
+supported by other versions and editions of Dragon.
+
+
+Languages supported by Windows Speech Recognition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following languages are supported by Windows Speech Recognition (WSR) as
+of 2016 [#f2]_:
+
+* English (U.S.) (*)
+* English (U.K.)
+* Chinese (Simplified) (*)
+* Chinese (Traditional)
+* French (France)
+* German (Germany)
+* Japanese
+* Spanish (Spain)
+
+\* Successfully tested.
+
+Microsoft does not appear to be documenting the languages available for WSR
+any more, which is why the provided citation for this section is an
+archive.org link. Currently, the best way to find out if your language is
+supported is to look for available speech models in the Windows language
+settings: **Settings** > **Time & Language** > **Language**.
+
+
 Languages supported by CMU Pocket Sphinx
-----------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The CMU Pocket Sphinx engine documentation page has a section on
 :ref:`spoken language support <RefSphinxSpokenLanguageSupport>`. There are
 CMU Pocket Sphinx models and dictionaries available from Source Forge for
 the following languages [#f3]_:
 
-* English (U.S.)
+* English (U.S.) (*)
 * English (Indian)
 * Catalan
-* Chinese (Mandarin)
+* Chinese (Mandarin) (*)
 * Dutch
 * French
 * German
@@ -51,14 +88,16 @@ the following languages [#f3]_:
 * Italian
 * Kazakh
 * Portuguese
-* Russian
+* Russian (*)
 * Spanish
 
+\* Successfully tested.
+
 English (U.S.) is the default language used by the CMU Pocket Sphinx engine.
 
 
 Languages supported by Kaldi
-----------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following languages are supported by the :ref:`RefKaldiEngine`:
 
@@ -97,7 +136,7 @@ English has additional time, date and character related classes.
 
 
 Language classes reference
-----------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: dragonfly.language.en.short_number
    :members:

documentation/make.bat

@@ -5,7 +5,7 @@ pushd %~dp0
 REM Command file for Sphinx documentation
 
 if "%SPHINXBUILD%" == "" (
-        set SPHINXBUILD=py.exe -3 -msphinx
+        set SPHINXBUILD=python -msphinx
 )
 set SOURCEDIR=.
 set BUILDDIR=build

documentation/natlink_engine.txt

@@ -40,7 +40,8 @@ Please see the `Natlink install instructions
 it.
 
 A 32-bit Python installation is required to use this engine back-end.  This
-is because Natlink does not work with 64-bit Python.
+is because Natlink does not work with 64-bit Python.  This limitation is
+unlikely to be overcome.
 
 
 Post-install Use

documentation/tests.txt

@@ -125,6 +125,11 @@ command:
         python setup.py test --test-suite=sapi5inproc
 
 
+Some SAPI 5 engine tests will fail intermittently, particularly with
+the shared process engine class (``"sapi5"`` / ``"sapi5shared"``).
+There is not much we can do about this.
+
+
 Using the Kaldi engine
 ----------------------------------------------------------------------------
 

dragonfly/__main__.py

@@ -378,7 +378,7 @@ def make_arg_parser():
     )
     no_input_argument = _build_argument(
         "-n", "--no-input", default=False, action="store_true",
-        help="Whether to load command modules and exit without "
+        help="Whether to load command modules and then exit without "
              "reading input from stdin or recognizing speech."
     )
     log_level_argument = _build_argument(
@@ -466,7 +466,8 @@ def make_arg_parser():
 
 
 def main():
-    # Parse the arguments and get the relevant function.
+    # Parse the arguments and get the relevant function. Exit if the command
+    # is not implemented.
     args = make_arg_parser().parse_args()
 
     def not_implemented(_):
@@ -475,9 +476,10 @@ def not_implemented(_):
 
     func = _COMMAND_MAP.get(args.command, not_implemented)
 
-    # Call the command function and return the exit code.
-    return func(args)
+    # Call the function and exit using the result.
+    return_code = func(args)
+    exit(return_code)
 
 
 if __name__ == '__main__':
-    exit(main())
+    main()

dragonfly/actions/keyboard/_x11_base.py

@@ -25,7 +25,7 @@
 
 from dragonfly.actions.keyboard._base import (BaseKeyboard, BaseTypeable,
                                               BaseKeySymbols)
-# TODO Cleanup this file a little.
+
 
 KEY_TRANSLATION = {
     # Dragonfly references character keys as characters internally.

dragonfly/engines/backend_natlink/engine.py

@@ -178,7 +178,7 @@ def disconnect(self):
         for grammar in self.grammars:
             grammar.unload()
 
-        # Close the waitForSpeech() dialog box if it is active for this
+        # Close the the waitForSpeech() dialog box if it is active for this
         # process.
         from dragonfly import Window
         target_title = "Natlink / Python Subsystem"

dragonfly/engines/backend_sapi5/engine.py

@@ -132,7 +132,9 @@ def _load_grammar(self, grammar):
         #  the grammar wrapper object for managing this grammar.
         context = self._recognizer.CreateRecoContext()
 
-        # Enable audio retention, if appropriate.
+        # TODO Once audio retention is made modular, this block will need
+        #  to be exposed as an engine option "retain_audio".  Otherwise,
+        #  as I understand it, audio retention won't work.
         if self._retain_dir:
             context.RetainedAudio = constants.SRAORetainAudio
 

dragonfly/engines/backend_sphinx/engine.py

@@ -674,8 +674,6 @@ def _get_best_hypothesis(self, hypotheses):
         # Return the appropriate hypothesis.
         return hypotheses.get(hyp.hypstr, self._null_hypothesis)
 
-    # TODO I want to integrate this into an example command module.
-    # It is a good example of how to use process_buffer().
     def process_wave_file(self, path):
         """
         Recognize speech from a wave file and return the recognition

dragonfly/examples/_fruit_toggle.py

@@ -35,16 +35,16 @@ class AppleRule(CompoundRule):
     extras = [Dictation("text")]
     def _process_recognition(self, node, extras):
         print("I like apples!  (%s)" % extras.get("text", ""))
-        banana_rule.enable()
         apple_rule.disable()
+        banana_rule.enable()
 
 class BananaRule(CompoundRule):
     spec = "I like bananas [<text>]"
     extras = [Dictation("text")]
     def _process_recognition(self, node, extras):
         print("I like bananas!  (%s)" % extras.get("text", ""))
-        apple_rule.enable()
         banana_rule.disable()
+        apple_rule.enable()
 
 apple_rule = AppleRule()
 banana_rule = BananaRule()

dragonfly/examples/sphinx_wave_transcriber.py

@@ -1,25 +1,5 @@
-#
-# This file is part of Dragonfly.
-# (c) Copyright 2019 by Dane Finlay
-# Licensed under the LGPL.
-#
-#   Dragonfly is free software: you can redistribute it and/or modify it
-#   under the terms of the GNU Lesser General Public License as published
-#   by the Free Software Foundation, either version 3 of the License, or
-#   (at your option) any later version.
-#
-#   Dragonfly is distributed in the hope that it will be useful, but
-#   WITHOUT ANY WARRANTY; without even the implied warranty of
-#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-#   Lesser General Public License for more details.
-#
-#   You should have received a copy of the GNU Lesser General Public
-#   License along with Dragonfly.  If not, see
-#   <http://www.gnu.org/licenses/>.
-#
-
 """
-Example script for recognizing speech from a wave file using the CMU Pocket
+Example script for recognising speech from a wave file using the CMU Pocket
 Sphinx dragonfly engine.
 
 """
@@ -43,7 +23,7 @@ def main():
     engine = get_engine("sphinx")
 
     # Voice activity detection config values may need to be adjusted to
-    # recognize speech.  Do this by changing the decoder's config.
+    # recognise speech. Do this by changing the decoder's config.
     # Note that these values represent a number of audio frames, not time
     # intervals.
     # For example: