Amend recently added documentation on new engines

Re: dictation-toolbox#139, dictation-toolbox#376, dictation-toolbox#383.

I've added a section on new engines back into the CONTRIBUTING.rst
file and given criteria for new engine implementations.

Author: drmfinlay

CONTRIBUTING.rst

@@ -1,3 +1,5 @@
+.. _RefContributing:
+
 Contributing
 ============
 
@@ -76,6 +78,56 @@ Other languages such as German and Dutch only have mappings for using
 ``IntegerRef`` (and similar) elements.
 
 
+.. _RefContributingNewEngines:
+
+Contributing New Speech Recognition Engines
+-------------------------------------------
+
+Introduction and Criteria
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Contribution of new Dragonfly speech recognition engine implementations is
+welcome, provided certain criteria are met.  New implementations must:
+
+ * be as functional as the current engines
+ * have some significant advantage over the current engines, perhaps in
+   terms of accuracy, speed, CPU/memory requirements and/or platform support
+ * have a willing maintainer or require little maintenance
+
+Before setting out to implement a new Dragonfly engine, please know that
+it is difficult to achieve the first criterion on functionality.
+Dragonfly's feature set requires a very specific type of speech recognition
+engine.  Namely, it must be one which supports each of the following
+features:
+
+ 1. definition of voice commands in a grammar format
+ 2. efficient and dynamic activation and deactivation of (parts of) grammars
+    at the beginning of an utterance
+ 3. in-speech transition between dictated prose (dictation mode), loaded
+    voice commands (command mode) and vice versa
+
+Each Dragonfly engine supports features one and two.  All engines support
+feature three except the CMU Pocket Sphinx engine.  However, Sphinx is
+only limited in that dictated prose must be spoken in separate utterances.
+
+These three requirements have effectively ruled out Dragonfly support for
+most speech recognition engines that users have asked about in the past.
+This is not meant to discourage those wishing to contribute new
+implementations, it is simply a fact.
+
+As for the second and third criteria listed above, they are fairly
+self-explanatory.  There is no sense in contributing a new engine that
+brings nothing new to the table and this library's maintainer does not wish
+to substantially increase the effort needed to keep things working.
+
+.. _RefContributingNewEngineGuide:
+
+New SR Engine Guide
+~~~~~~~~~~~~~~~~~~~
+
+TODO
+
+
 .. Links.
 .. _Read the docs: https://readthedocs.org/
 .. _Sphinx documentation engine: https://www.sphinx-doc.org/en/master/

documentation/faq.txt

@@ -165,31 +165,10 @@ the following resources from might be of use:
 Will Dragonfly add support for speech recognition engine X?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-We are not considering the addition of new Dragonfly engine implementations.
-The main reason for this is that Dragonfly requires a very specific type of
-speech recognition engine to work.  It must be one which supports each of
-the following features:
-
-1. definition of voice commands in a grammar format
-2. efficient and dynamic activation and deactivation of (parts of) grammars
-   at the beginning of an utterance
-3. in-speech transition between dictated prose (dictation mode), loaded
-   voice commands (command mode) and vice versa
-
-Each Dragonfly engine supports features one and two.  All engines support
-feature three except the CMU Pocket Sphinx engine.  However, Sphinx is
-only limited in that dictated prose must be spoken in separate utterances.
-
-These three requirements have effectively ruled out Dragonfly support for
-most speech recognition engines that users have asked about in the past.
-
-Even if a new speech recognition engine comes along that supports the above
-features, we will probably not accept an engine implementation for it
-because Dragonfly already has very good engine implementations.
-
-We may make an exception for new implementations meant to replace current,
-deprecated ones.  However, none of Dragonfly's current engines really need
-replacing.
+The answer is 'it depends.'  No new engine implementations are currently
+under development.  Contribution of new implementations is welcome, provided
+certain criteria are met.  Please see :ref:`RefContributingNewEngines` for
+more information.
 
 
 API Questions
@@ -373,12 +352,11 @@ prints the name of the current engine if one has been initialized:
        print("No engine has been initialized.")
 
 
-Can I implement my own custom Dragonfly engine?
+Can I implement my own custom Dragonfly engine externally?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Yes, this is possible.  Although Dragonfly is :ref:`not accepting new engine
-implementations <RefFAQSupportEngineX>`, you can write one externally,
-register it and use it like any of the in-package engines.
+Yes, you can write a Dragonfly engine implementation externally and use it
+like any of the in-package engines.
 
 Implementing a custom Dragonfly engine is a complex task.  It is
 recommended that you start with a copy of the text-input engine source code