[Emacs-diffs] /srv/bzr/emacs/emacs-24 r107852: More small doc and lispref edits related to processes

[Glenn Morris]

------------------------------------------------------------
revno: 107852
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Wed 2012-04-18 00:21:18 -0700
message:
  More small doc and lispref edits related to processes
  
  * doc/lispref/processes.texi (Serial Ports, Byte Packing, Bindat Spec)
  (Bindat Functions): Copyedits.
  
  * src/process.c (Fset_process_inherit_coding_system_flag)
  (Fset_process_query_on_exit_flag): Doc fix (mention return value).
  (Fmake_network_process, Fmake_serial_process): Doc fix.
  
  * admin/FOR-RELEASE: Related markup.
modified:
  admin/FOR-RELEASE
  doc/lispref/ChangeLog
  doc/lispref/processes.texi
  src/ChangeLog
  src/process.c

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-04-14 20:43:11 +0000
+++ b/admin/FOR-RELEASE 2012-04-18 07:21:18 +0000
@@ -214,7 +214,7 @@
 os.texi           cyd
 package.texi      rgm
 positions.texi    cyd
-processes.texi
+processes.texi    rgm
 searching.texi    rgm
 sequences.texi    cyd
 streams.texi      cyd

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-04-18 06:20:47 +0000
+++ b/doc/lispref/ChangeLog     2012-04-18 07:21:18 +0000
@@ -1,3 +1,8 @@
+2012-04-18  Glenn Morris  <address@hidden>
+
+       * processes.texi (Serial Ports, Byte Packing, Bindat Spec)
+       (Bindat Functions): Copyedits.
+
 2012-04-18  Christopher Schmidt  <address@hidden>
 
        * files.texi (Saving Buffers): Document `visit and `visit-save'

=== modified file 'doc/lispref/processes.texi'
--- a/doc/lispref/processes.texi        2012-04-18 03:48:43 +0000
+++ b/doc/lispref/processes.texi        2012-04-18 07:21:18 +0000
@@ -2493,11 +2493,11 @@
 terminal window created by @code{serial-term}, you can click on the
 mode line for configuration.
 
-  A serial connection is represented by a process object which can be
-used similar to a subprocess or network process.  You can send and
-receive data and configure the serial port.  A serial process object
-has no process ID, you can't send signals to it, and the status codes
-are different from other types of processes.
+  A serial connection is represented by a process object, which can be
+used in a similar way to a subprocess or network process.  You can send and
+receive data, and configure the serial port.  A serial process object
+has no process ID, however, and you can't send signals to it, and the
+status codes are different from other types of processes.
 @code{delete-process} on the process object or @code{kill-buffer} on
 the process buffer close the connection, but this does not affect the
 device connected to the serial port.
@@ -2505,15 +2505,17 @@
   The function @code{process-type} returns the symbol @code{serial}
 for a process object representing a serial port connection.
 
-  Serial ports are available on GNU/Linux, Unix, and Windows systems.
+  Serial ports are available on GNU/Linux, Unix, and MS Windows systems.
 
 @deffn Command serial-term port speed
 Start a terminal-emulator for a serial port in a new buffer.
address@hidden is the name of the serial port to which to connect.  For
-example, this could be @file{/dev/ttyS0} on Unix.  On Windows, this
address@hidden is the name of the serial port to connect to.  For
+example, this could be @file{/dev/ttyS0} on Unix.  On MS Windows, this
 could be @file{COM1}, or @file{\\.\COM10} (double the backslashes in
 Lisp strings).
 
address@hidden FIXME is 9600 still the most common value, or is it 115200 now?
address@hidden (Same value, 9600, appears below as well.)
 @var{speed} is the speed of the serial port in bits per second.  9600
 is a common value.  The buffer is in Term mode; see @ref{Term Mode,,,
 emacs, The GNU Emacs Manual}, for the commands to use in that buffer.
@@ -2522,25 +2524,27 @@
 
 @defun make-serial-process &rest args
 This function creates a process and a buffer.  Arguments are specified
-as keyword/argument pairs.  Here's the list of the meaningful keywords:
+as keyword/argument pairs.  Here's the list of the meaningful
+keywords, with the first two (@var{port} and @var{speed}) being mandatory:
 
 @table @code
address@hidden :port @address@hidden (mandatory)}
address@hidden :port @var{port}
 This is the name of the serial port.  On Unix and GNU systems, this is
 a file name such as @file{/dev/ttyS0}.  On Windows, this could be
 @file{COM1}, or @file{\\.\COM10} for ports higher than @file{COM9}
 (double the backslashes in Lisp strings).
 
address@hidden :speed @address@hidden (mandatory)}
address@hidden :speed @var{speed}
 The speed of the serial port in bits per second.  This function calls
address@hidden to handle the speed.
address@hidden to handle the speed; see the
+following documentation of that function for more details.
 
 @item :name @var{name}
 The name of the process.  If @var{name} is not given, @var{port} will
 serve as the process name as well.
 
 @item :buffer @var{buffer}
-The buffer to associate with the process.  The value could be either a
+The buffer to associate with the process.  The value can be either a
 buffer or a string that names a buffer.  Process output goes at the
 end of that buffer, unless you specify an output stream or filter
 function to handle the output.  If @var{buffer} is not given, the
@@ -2550,9 +2554,9 @@
 @item :coding @var{coding}
 If @var{coding} is a symbol, it specifies the coding system used for
 both reading and writing for this process.  If @var{coding} is a cons
address@hidden(decoding . encoding)}, @var{decoding} is used for reading, and
address@hidden is used for writing.  If not specified, the default is
-to determine the coding systems from data itself.
address@hidden(@var{decoding} . @var{encoding})}, @var{decoding} is used for
+reading, and @var{encoding} is used for writing.  If not specified,
+the default is to determine the coding systems from the data itself.
 
 @item :noquery @var{query-flag}
 Initialize the process query flag to @var{query-flag}.  @xref{Query
@@ -2574,8 +2578,7 @@
 @item :plist @var{plist}
 Install @var{plist} as the initial plist of the process.
 
address@hidden :speed
address@hidden :bytesize
address@hidden :bytesize
 @itemx :parity
 @itemx :stopbits
 @itemx :flowcontrol
@@ -2603,7 +2606,7 @@
 This functions configures a serial port connection.  Arguments are
 specified as keyword/argument pairs.  Attributes that are not given
 are re-initialized from the process's current configuration (available
-via the function @code{process-contact}) or set to reasonable default
+via the function @code{process-contact}), or set to reasonable default
 values.  The following arguments are defined:
 
 @table @code
@@ -2621,8 +2624,8 @@
 at a few defined values between 1200 and 115200, with 9600 being the
 most common value.  If @var{speed} is @code{nil}, the function ignores
 all other arguments and does not configure the port.  This may be
-useful for special serial ports such as Bluetooth-to-serial converters
-which can only be configured through AT commands sent through the
+useful for special serial ports such as Bluetooth-to-serial converters,
+which can only be configured through @samp{AT} commands sent through the
 connection.  The value of @code{nil} for @var{speed} is valid only for
 connections that were already opened by a previous call to
 @code{make-serial-process} or @code{serial-term}.
@@ -2649,9 +2652,9 @@
 flow control.
 @end table
 
address@hidden is called by
address@hidden for the initial configuration of the serial
-port.
+Internally, @code{make-serial-process} calls
address@hidden for the initial configuration of the
+serial port.
 @end defun
 
 @node Byte Packing
@@ -2661,8 +2664,12 @@
   This section describes how to pack and unpack arrays of bytes,
 usually for binary network protocols.  These functions convert byte arrays
 to alists, and vice versa.  The byte array can be represented as a
address@hidden FIXME?  No multibyte?
 unibyte string or as a vector of integers, while the alist associates
 symbols either with fixed-size objects or with recursive sub-alists.
+To use the functions referred to in this section, load the
address@hidden library.
address@hidden It doesn't have any autoloads.
 
 @cindex serializing
 @cindex deserializing
@@ -2683,7 +2690,7 @@
 
   To control unpacking and packing, you write a @dfn{data layout
 specification}, a special nested list describing named and typed
address@hidden  This specification controls length of each field to be
address@hidden  This specification controls the length of each field to be
 processed, and how to pack or unpack it.  We normally keep bindat specs
 in variables whose names end in @samp{-bindat-spec}; that kind of name
 is automatically recognized as ``risky''.
@@ -2732,12 +2739,12 @@
 Zero-terminated string, in a fixed-size field with length @var{len}.
 
 @item vec @var{len} address@hidden
-Vector of @var{len} elements of type @var{type}, or bytes if not
address@hidden is specified.
+Vector of @var{len} elements of type @var{type}, defaulting to bytes.
 The @var{type} is any of the simple types above, or another vector
-specified as a list @code{(vec @var{len} address@hidden)}.
+specified as a list of the form @code{(vec @var{len} address@hidden)}.
 
 @item ip
address@hidden FIXME?  IPv6?
 Four-byte vector representing an Internet address.  For example:
 @code{[127 0 0 1]} for localhost.
 
@@ -2765,12 +2772,11 @@
 should evaluate to an integer, specifying the field length.
 
 A field specification generally has the form @code{(address@hidden
address@hidden)}.  The square braces indicate that @var{name} is
-optional.  (Don't use names that are symbols meaningful as type
-specifications (above) or handler specifications (below), since that
-would be ambiguous.)  @var{name} can be a symbol or the expression
address@hidden(eval @var{form})}, in which case @var{form} should evaluate to
-a symbol.
address@hidden)}, where @var{name} is optional.  Don't use names that
+are symbols meaningful as type specifications (above) or handler
+specifications (below), since that would be ambiguous.  @var{name} can
+be a symbol or an expression @code{(eval @var{form})}, in which case
address@hidden should evaluate to a symbol.
 
 @var{handler} describes how to unpack or pack the field and can be one
 of the following:
@@ -2817,10 +2823,11 @@
 
 @item repeat @var{count} @address@hidden
 Process the @var{field-specs} recursively, in order, then repeat
-starting from the first one, processing all the specs @var{count}
+starting from the first one, processing all the specifications @var{count}
 times overall.  The @var{count} is given using the same formats as a
 field length---if an @code{eval} form is used, it is evaluated just once.
-For correct operation, each spec in @var{field-specs} must include a name.
+For correct operation, each specification in @var{field-specs} must
+include a name.
 @end table
 
 For the @code{(eval @var{form})} forms used in a bindat specification,
@@ -2859,9 +2866,10 @@
 alist representing unpacked field data.
 
 @defun bindat-unpack spec bindat-raw &optional bindat-idx
address@hidden FIXME?  Again, no multibyte?
 This function unpacks data from the unibyte string or byte
 array @code{bindat-raw}
-according to @var{spec}.  Normally this starts unpacking at the
+according to @var{spec}.  Normally, this starts unpacking at the
 beginning of the byte array, but if @var{bindat-idx} is address@hidden, it
 specifies a zero-based starting position to use instead.
 
@@ -2897,7 +2905,7 @@
 
 @defun bindat-pack spec struct &optional bindat-raw bindat-idx
 This function returns a byte array packed according to @var{spec} from
-the data in the alist @var{struct}.  Normally it creates and fills a
+the data in the alist @var{struct}.  It normally creates and fills a
 new byte array starting at the beginning.  However, if @var{bindat-raw}
 is address@hidden, it specifies a pre-allocated unibyte string or vector to
 pack into.  If @var{bindat-idx} is address@hidden, it specifies the starting
@@ -2910,6 +2918,7 @@
 @defun bindat-ip-to-string ip
 Convert the Internet address vector @var{ip} to a string in the usual
 dotted notation.
address@hidden FIXME?  Does it do IPv6?
 
 @example
 (bindat-ip-to-string [127 0 0 1])
@@ -2919,10 +2928,16 @@
 
 @node Bindat Examples
 @subsection Examples of Byte Unpacking and Packing
address@hidden FIXME?  This seems a very long example for something that is not 
used
address@hidden very often.  As of 24.1, gdb-mi.el is the only user of bindat.el 
in Emacs.
address@hidden Maybe one or both of these examples should just be moved to the
address@hidden commentary of bindat.el.
 
   Here is a complete example of byte unpacking and packing:
 
 @lisp
+(require 'bindat)
+
 (defvar fcookie-index-spec
   '((:version  u32)
     (:count    u32)
@@ -2931,16 +2946,14 @@
     (:flags    u32)
     (:delim    u8)
     (:ignored  fill 3)
-    (:offset   repeat (:count)
-               (:foo u32)))
+    (:offset   repeat (:count) (:foo u32)))
   "Description of a fortune cookie index file's contents.")
 
 (defun fcookie (cookies &optional index)
   "Display a random fortune cookie from file COOKIES.
 Optional second arg INDEX specifies the associated index
-filename, which is by default constructed by appending
-\".dat\" to COOKIES.  Display cookie text in possibly
-new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME
+filename, by default \"COOKIES.dat\".  Display cookie text
+in buffer \"*Fortune Cookie: BASENAME*\", where BASENAME
 is COOKIES without the directory part."
   (interactive "fCookies file: ")
   (let* ((info (with-temp-buffer
@@ -2963,10 +2976,9 @@
 
 (defun fcookie-create-index (cookies &optional index delim)
   "Scan file COOKIES, and write out its index file.
-Optional second arg INDEX specifies the index filename,
-which is by default constructed by appending \".dat\" to
-COOKIES.  Optional third arg DELIM specifies the unibyte
-character which, when found on a line of its own in
+Optional arg INDEX specifies the index filename, which by
+default is \"COOKIES.dat\".  Optional arg DELIM specifies the
+unibyte character that, when found on a line of its own in
 COOKIES, indicates the border between entries."
   (interactive "fCookies file: ")
   (setq delim (or delim ?%))
@@ -3003,8 +3015,8 @@
         (write-file (or index (concat cookies ".dat")))))))
 @end lisp
 
-Following is an example of defining and unpacking a complex structure.
-Consider the following C structures:
+The following is an example of defining and unpacking a complex
+structure.  Consider the following C structures:
 
 @example
 struct header @{
@@ -3017,14 +3029,14 @@
 struct data @{
     unsigned char    type;
     unsigned char    opcode;
-    unsigned short   length;  /* In network byte order */
+    unsigned short   length;  /* in network byte order  */
     unsigned char    id[8];   /* null-terminated string  */
     unsigned char    data[/* (length + 3) & ~3 */];
 @};
 
 struct packet @{
     struct header    header;
-    unsigned long    counters[2];  /* In little endian order */
+    unsigned long    counters[2];  /* in little endian order  */
     unsigned char    items;
     unsigned char    filler[3];
     struct data      item[/* items */];
@@ -3032,7 +3044,7 @@
 @};
 @end example
 
-The corresponding data layout specification:
+The corresponding data layout specification is:
 
 @lisp
 (setq header-spec
@@ -3044,21 +3056,21 @@
 (setq data-spec
       '((type      u8)
         (opcode    u8)
-        (length    u16)  ;; network byte order
+        (length    u16)  ; network byte order
         (id        strz 8)
         (data      vec (length))
         (align     4)))
 
 (setq packet-spec
       '((header    struct header-spec)
-        (counters  vec 2 u32r)   ;; little endian order
+        (counters  vec 2 u32r)   ; little endian order
         (items     u8)
         (fill      3)
         (item      repeat (items)
                    (struct data-spec))))
 @end lisp
 
-A binary data representation:
+A binary data representation is:
 
 @lisp
 (setq binary-data
@@ -3068,7 +3080,7 @@
         1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])
 @end lisp
 
-The corresponding decoded structure:
+The corresponding decoded structure is:
 
 @lisp
 (setq decoded (bindat-unpack packet-spec binary-data))
@@ -3092,7 +3104,7 @@
         (type . 1))))
 @end lisp
 
-Fetching data from this structure:
+An example of fetching data from this structure:
 
 @lisp
 (bindat-get-field decoded 'item 1 'id)

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2012-04-18 03:48:43 +0000
+++ b/src/ChangeLog     2012-04-18 07:21:18 +0000
@@ -2,7 +2,7 @@
 
        * process.c (Fset_process_inherit_coding_system_flag)
        (Fset_process_query_on_exit_flag): Doc fix (mention return value).
-       (Fmake_network_process): Doc fix.
+       (Fmake_network_process, Fmake_serial_process): Doc fix.
 
 2012-04-17  Eli Zaretskii  <address@hidden>
 

=== modified file 'src/process.c'
--- a/src/process.c     2012-04-18 03:48:43 +0000
+++ b/src/process.c     2012-04-18 07:21:18 +0000
@@ -2528,7 +2528,7 @@
 the backslashes in strings).
 
 :speed SPEED -- (mandatory) is handled by `serial-process-configure',
-which is called by `make-serial-process'.
+which this function calls.
 
 :name NAME -- NAME is the name of the process.  If NAME is not given,
 the value of PORT is used.
@@ -2557,13 +2557,12 @@
 
 :plist PLIST -- Install PLIST as the initial plist of the process.
 
-:speed
 :bytesize
 :parity
 :stopbits
 :flowcontrol
--- These arguments are handled by `serial-process-configure', which is
-called by `make-serial-process'.
+-- This function calls `serial-process-configure' to handle these
+arguments.
 
 The original argument list, possibly modified by later configuration,
 is available via the function `process-contact'.