finished doc of cmdInput1

Author: wlammen

src/mminou.h

@@ -259,6 +259,11 @@ vstring cmdInput(FILE *stream, const char *ask);
  * copied from the appropriate entry of \ref g_commandFileSilent, unless the
  * interactive mode is reached; here output is never suppressed (value 0).
  *
+ * 3. remove all CR (0x0D) characters, not only those in compination with LF.
+ *
+ * 4. prompt and command is printed, if not suppressed, then the read line is
+ * returned.
+ *
  * \return first not interpreted line as \ref vstring, or "EXIT" on error. 
  * \pre
  *   The following variables are honored during execution and should be properly
@@ -289,6 +294,9 @@ vstring cmdInput(FILE *stream, const char *ask);
  *     \ref g_pntrStartTempAlloc.
  *   - interactive mode: The \ref backBuffer is cleared, then filled with
  *     prompt (last line only) and input of the user.
+ *   - submit mode: In case of EOF the previous \ref g_commandFileNestingLevel
+ *     is activated, necessary cleanups performed, and 
+ *     the \ref g_commandFileSilentFlag is updated appropriately.
  * \warning the calling program must deallocate the returned string.
  */
 vstring cmdInput1(const char *ask);

src/mmvstr.h

@@ -454,6 +454,31 @@ temp_vstring left(const char *sin, long n);
  * \bug a stack overflow of \a tempAllocStack is not handled correctly.
  */
 temp_vstring right(const char *sin, long n);
+/*!
+ * \fn temp_vstring edit(const char *sin, long control)
+ * perform a combination of transformations on \p sin based on the set bits in
+ * \p control.
+ *      Bit   Effect
+ *      1        Clear parity bits
+ *      2        Discard all spaces and tabs
+ *      4        Discard characters: CR, LF, FF, ESC, RUBOUT, and NULL
+ *      8        Discard leading spaces and tabs
+ *      16       Reduce spaces and tabs to one space
+ *      32       Convert lowercase to uppercase
+ *      64       Convert [ to ( and ] to )
+ *      128      Discard trailing spaces and tabs
+ *      256      Do not alter characters inside quotes
+ *      512      Convert uppercase to lowercase
+ *      1024     Tab the line (convert spaces to equivalent tabs)
+ *      2048     Untab the line (convert tabs to equivalent spaces)
+ *      4096     Convert VT220 screen print frame graphics to -,|,+ characters
+ *      8192     Discard CR only (to assist DOS-to-Unix conversion)
+ *      16384    Discard trailing spaces, tabs, and LFs
+ * \param[in] sin (not null) NUL terminated string to convert
+ * \param[in] control a combination of set bit requesting the desired
+ *   transformation(s)
+ * \return the transformed \p sin ready for pushing on \ref tempAllocStack.
+ */
 temp_vstring edit(const char *sin, long control);
 /*!
  * \fn temp_vstring space(long n)