From jgabel@thilelli.net  Sat Aug 27 17:09:51 2005
Return-Path: <jgabel@thilelli.net>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 5FCA016A41F
	for <FreeBSD-gnats-submit@freebsd.org>; Sat, 27 Aug 2005 17:09:51 +0000 (GMT)
	(envelope-from jgabel@thilelli.net)
Received: from smtp.thilelli.net (smtp.thilelli.net [213.41.129.161])
	by mx1.FreeBSD.org (Postfix) with ESMTP id C4D2943D53
	for <FreeBSD-gnats-submit@freebsd.org>; Sat, 27 Aug 2005 17:09:50 +0000 (GMT)
	(envelope-from jgabel@thilelli.net)
Received: from localhost (localhost [127.0.0.1])
	by bento.thilelli.net (Postfix) with ESMTP id B15FB5C7D
	for <FreeBSD-gnats-submit@freebsd.org>; Sat, 27 Aug 2005 19:09:49 +0200 (CEST)
Received: from bento.thilelli.net ([127.0.0.1])
 by localhost (bento.thilelli.net [127.0.0.1]) (amavisd-new, port 10024)
 with LMTP id 87781-03 for <FreeBSD-gnats-submit@freebsd.org>;
 Sat, 27 Aug 2005 19:09:39 +0200 (CEST)
Received: from titeuf.thilelli.net (titeuf.thilelli.net [192.168.1.20])
	by bento.thilelli.net (Postfix) with ESMTP id E05945C7C
	for <FreeBSD-gnats-submit@freebsd.org>; Sat, 27 Aug 2005 19:09:39 +0200 (CEST)
Received: by titeuf.thilelli.net (Postfix, from userid 1001)
	id D13D073028; Sat, 27 Aug 2005 19:09:39 +0200 (CEST)
Message-Id: <20050827170939.D13D073028@titeuf.thilelli.net>
Date: Sat, 27 Aug 2005 19:09:39 +0200 (CEST)
From: Julien Gabel <jpeg@thilelli.net>
Reply-To: Julien Gabel <jpeg@thilelli.net>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [patch] Error in the pin numbers of the described connector in the Handbook (serial).
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         85355
>Category:       docs
>Synopsis:       [patch] Error in the pin numbers of the described connector in the Handbook (serial).
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    garys
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Aug 27 17:10:23 GMT 2005
>Closed-Date:    Fri Sep 30 18:06:57 GMT 2005
>Last-Modified:  Fri Sep 30 18:06:57 GMT 2005
>Originator:     Julien Gabel
>Release:        FreeBSD 5.4-STABLE i386
>Organization:
>Environment:
System: FreeBSD titeuf.thilelli.net 5.4-STABLE FreeBSD 5.4-STABLE #0: Sun Aug 21 14:49:33 CEST 2005 root@titeuf.thilelli.net:/usr/obj/usr/src/sys/TITEUF i386

>Description:
It seems there is a little mistake in the proposed pin numbers for null-modem DB-25
connector shown in the example.

>How-To-Repeat:
Compare different source of information about this topic, as in the proposed Hardware Book at:
 http://www.hardwarebook.net/cable/serial/nullmodem25to25.html

>Fix:
Here is a patch:

--- chapter.sgml.diff begins here ---
--- /usr/doc/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml	Wed Jul 27 06:14:18 2005
+++ /tmp/chapter.sgml	Sat Aug 27 19:00:26 2005
@@ -122,10 +122,11 @@
 	    example, the <quote>send data</quote> pin on one end goes to the
 	    <quote>receive data</quote> pin on the other end.</para>
 	      
-	  <para>If you like making your own cables, you can construct
-	    a null-modem cable for use with
-	    terminals.  This table shows the RS-232C signal names and the pin
-	    numbers on a DB-25 connector.</para>
+	  <para>If you like making your own cables, you can construct a
+	    null-modem cable for use with terminals.  This table shows the RS-232C
+	    signal names and the pin numbers on a DB-25 connector.  More information
+	    and collection of cable descriptions may be found in the <ulink
+	    url="http://www.hardwarebook.net/cable/index.html">Hardware Book</ulink>.</para>
 
 	  <informaltable frame="none" pgwide="1">
 	    <tgroup cols="5">
@@ -192,8 +193,8 @@
 		  <entry>DCD</entry>
 		  <entry>8</entry>
 		  <entry></entry>
-		  <entry>6</entry>
-		  <entry>DSR</entry>
+		  <entry>8</entry>
+		  <entry>DCD</entry>
 		</row>
 		
 		<row>
--- chapter.sgml.diff ends here ---
>Release-Note:
>Audit-Trail:

From: garys@opusnet.com (Gary W. Swearingen)
To: Julien Gabel <jpeg@thilelli.net>
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/85355: [patch] Error in the pin numbers of the described
 connector in the Handbook (serial).
Date: Sat, 27 Aug 2005 13:40:19 -0700

 Julien Gabel <jpeg@thilelli.net> writes:
 
 > +	  <para>If you like making your own cables, you can construct a
 > +	    null-modem cable for use with terminals.  This table shows the RS-232C
 
 "for asyncronous communications with terminals".  (I'm not sure what
 "terminals" include, but synchronous comm needs more wires.)
 
 (I'd also kill "If you like making your own cables, ".)
 
 > +	    signal names and the pin numbers on a DB-25 connector.  More information
 > +	    and collection of cable descriptions may be found in the <ulink
 > +	    url="http://www.hardwarebook.net/cable/index.html">Hardware Book</ulink>.</para>
 
 I'd add: The standard also calls for a straight-through pin 1 to pin 1
 "protective ground" line, but it is often omitted.  Some terminals can
 get by using only pins 2, 3, and 7, while others, especially printers,
 require other configurations than the example here.  Synchronous
 communications, for example, requires more lines to be used.
 
 > +		  <entry>8</entry>
 > +		  <entry>DCD</entry>
 
 That design (after the fix) seems to be the most popular, but a book
 "RS-232 Made Easy" uses several pages developing and justifying a
 generic null-modem design like that, except he has 4 & 5 going to 8
 and vice versa.  I probably used in at least one of my cables.  Oh,
 well; that's life with RS-232.
 

From: garys@opusnet.com (Gary W. Swearingen)
To: Julien Gabel <jpeg@thilelli.net>
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/85355: [patch] Error in the pin numbers of the described
 connector in the Handbook (serial).
Date: Sat, 27 Aug 2005 13:45:40 -0700

 Julien Gabel <jpeg@thilelli.net> writes:
 
 > +	    and collection of cable descriptions may be found in the <ulink
 
 "and a collection"; maybe "may be found in" -> "is in"

From: Yar Tikhiy <yar@comp.chem.msu.su>
To: "Gary W. Swearingen" <garys@opusnet.com>
Cc: jpeg@thilelli.net, bug-followup@FreeBSD.org
Subject: Re: docs/85355: [patch] Error in the pin numbers of the described connector in the Handbook (serial).
Date: Mon, 29 Aug 2005 12:30:36 +0400

 On Sat, Aug 27, 2005 at 08:40:20PM +0000, Gary W. Swearingen wrote:
 >  Julien Gabel <jpeg@thilelli.net> writes:
 >  
 >  > +	  <para>If you like making your own cables, you can construct a
 >  > +	    null-modem cable for use with terminals.  This table shows the RS-232C
 >  
 >  "for asyncronous communications with terminals".  (I'm not sure what
 >  "terminals" include, but synchronous comm needs more wires.)
 
 It might be reasonable to tell that in general, a null-modem cable
 is for connecting a DTE directly to another DTE.  AFAIK, null-modem
 cables can be constructed for synchronous comms, too.  Then, the
 topic can be narrowed down to async comms.
 
 >  > +	    signal names and the pin numbers on a DB-25 connector.  More information
 >  > +	    and collection of cable descriptions may be found in the <ulink
 >  > +	    url="http://www.hardwarebook.net/cable/index.html">Hardware Book</ulink>.</para>
 
 To me, www.hardwarebook.net doen't seem the definite resource.
 IMHO, if the topic is rather wide, the reader should better be
 hinted to do a (re)search on the Net instead of pointed to a single
 resource, which is likely to become incomplete, outdated, or down.
 
 >  I'd add: The standard also calls for a straight-through pin 1 to pin 1
 >  "protective ground" line, but it is often omitted.  Some terminals can
 >  get by using only pins 2, 3, and 7, while others, especially printers,
 >  require other configurations than the example here.  Synchronous
 >  communications, for example, requires more lines to be used.
 
 Perhaps, we can spend a paragraph on giving the reader some insight
 into null-modem design principles, eh?  In particular, the 3-wire
 cable, for which we happen to have some entries in /etc/gettytab,
 will provide data lines, but won't support flow control (RTS, CTS)
 or modem control (DTR, DSR, DCD).  So the reader could understand
 *why* he may or may not need the simpler or the more complex cable
 design.  I myself once spent some time making a 8-wire null-modem
 cable only to find out that my terminak didn't support flow control
 in the first place :-)
 
 Apropos, has there ever been a DTE printer?  I think that printers
 or sync comms shouldn't belong there if it were told above that we
 would deal with async DTE-DTE comms only in this section.
 
 >  > +		  <entry>8</entry>
 >  > +		  <entry>DCD</entry>
 >  
 >  That design (after the fix) seems to be the most popular, but a book
 >  "RS-232 Made Easy" uses several pages developing and justifying a
 >  generic null-modem design like that, except he has 4 & 5 going to 8
 >  and vice versa.  I probably used in at least one of my cables.  Oh,
 >  well; that's life with RS-232.
 
 We may show two or three different designs in the handbook if we
 can tell the reader about their merits.  The problem with the design
 currently in the handbook is that it is erroneous *and* bogus.  I'd
 suggest adding another row to the table so that it becomes evident
 that DTR on this side is connected to DSR+DCD on the other side
 while DTR on the other side is connected to DSR+DCD on this side.
 An RS-232 null-modem cable should be symmetric, to my mind.
 
 -- 
 Yar

From: garys@opusnet.com (Gary W. Swearingen)
To: Yar Tikhiy <yar@comp.chem.msu.su>
Cc: jpeg@thilelli.net, docs@freebsd.org
Subject: Re: docs/85355: [patch] Error in the pin numbers of the described
 connector in the Handbook (serial).
Date: Mon, 29 Aug 2005 07:52:16 -0700

 Yar Tikhiy <yar@comp.chem.msu.su> writes:
 
 > It might be reasonable to tell that in general, a null-modem cable
 > is for connecting a DTE directly to another DTE.  AFAIK, null-modem
 > cables can be constructed for synchronous comms, too.  Then, the
 > topic can be narrowed down to async comms.
 
 I doubt if Julien wants to do more rewrites on the section.  But I
 can't resist replying anyway; maybe Yar wants to rewrite it later.
 
 It probably should have some of the cable stuff from the "Serial
 Ports" section which says that a null-modem is AKA DTE-to-DTE cable
 and what DTE is, eg, a computer.  And terminals traditionally have
 included teletypes and printers. (Once there were no CRTs or LCDs.)
 
 > To me, www.hardwarebook.net doen't seem the definite resource.
 > IMHO, if the topic is rather wide, the reader should better be
 > hinted to do a (re)search on the Net instead of pointed to a single
 > resource, which is likely to become incomplete, outdated, or down.
 
 I was thinking the same things.
 
 > Apropos, has there ever been a DTE printer?  I think that printers
 > or sync comms shouldn't belong there if it were told above that we
 > would deal with async DTE-DTE comms only in this section.
 
 Serial printers were once common (I have one) and I think few, if any,
 were configured as DCE (eg, modems); the bulk were DTEs. But sync
 comms don't need to be mentioned; I don't know if FreeBSD can even
 handle it.  I just wanted some note about the large number of
 null-modem designs for different purposes, for folks raised on USB.
 
 > We may show two or three different designs in the handbook if we
 > can tell the reader about their merits.  The problem with the design
 > currently in the handbook is that it is erroneous *and* bogus.  I'd
 > suggest adding another row to the table so that it becomes evident
 > that DTR on this side is connected to DSR+DCD on the other side
 > while DTR on the other side is connected to DSR+DCD on this side.
 
 The Note below the pin-out is supposed to make it evident, and with
 the Note the design is symmetric.
 
 > An RS-232 null-modem cable should be symmetric, to my mind.
 
 A "typical async null-modem cable", yes.  But few of the many RS-232
 null-modem cable designs shown in the book are symmetric, owing to the
 variety of designs of much DTE. (Less true today than yesteryear.)

From: Yar Tikhiy <yar@comp.chem.msu.su>
To: "Gary W. Swearingen" <garys@opusnet.com>
Cc: jpeg@thilelli.net, bug-followup@freebsd.org
Subject: Re: docs/85355: [patch] Error in the pin numbers of the described connector in the Handbook (serial).
Date: Mon, 29 Aug 2005 20:24:04 +0400

 On Mon, Aug 29, 2005 at 07:52:16AM -0700, Gary W. Swearingen wrote:
 > Yar Tikhiy <yar@comp.chem.msu.su> writes:
 > 
 > > It might be reasonable to tell that in general, a null-modem cable
 > > is for connecting a DTE directly to another DTE.  AFAIK, null-modem
 > > cables can be constructed for synchronous comms, too.  Then, the
 > > topic can be narrowed down to async comms.
 > 
 > I doubt if Julien wants to do more rewrites on the section.  But I
 > can't resist replying anyway; maybe Yar wants to rewrite it later.
 
 I'd like to when time permits.  I use FreeBSD and null-modem cables
 often :-) It's good that our discussion of this topic will stay in
 the PR audit trail so that I can consult with it.  Thank you for
 your suggestions!
 
 > It probably should have some of the cable stuff from the "Serial
 > Ports" section which says that a null-modem is AKA DTE-to-DTE cable
 > and what DTE is, eg, a computer.  And terminals traditionally have
 > included teletypes and printers. (Once there were no CRTs or LCDs.)
 
 And I'd rather add a better definition for DTE and DCE, which are
 mistaken every there and then.
 
 -- 
 Yar

From: "Julien Gabel" <jpeg@thilelli.net>
To: "Gary W. Swearingen" <garys@opusnet.com>
Cc: "Yar Tikhiy" <yar@comp.chem.msu.su>,
 bug-followup@FreeBSD.org
Subject: Re: docs/85355: [patch] Error in the pin numbers of the described 
     connector in the Handbook (serial).
Date: Tue, 30 Aug 2005 11:48:35 +0200 (CEST)

 ------=_20050830114835_68297
 Content-Type: text/plain; charset="iso-8859-1"
 Content-Transfer-Encoding: 8bit
 
 >> It might be reasonable to tell that in general, a null-modem cable
 >> is for connecting a DTE directly to another DTE.  AFAIK, null-modem
 >> cables can be constructed for synchronous comms, too.  Then, the
 >> topic can be narrowed down to async comms.
 
 > I doubt if Julien wants to do more rewrites on the section.  But I
 > can't resist replying anyway; maybe Yar wants to rewrite it later.
 
 In fact i don't really want to do a rewrite of this particular section,
 especially since i don't have a _good_ knowledge on this topic.  The
 purpose of the initial PR was to correct what seems to be an error in
 the proposed table (and eventually a pointer to more information), based
 on a very recent experience to get a trace after a panic via a serial
 console... and so a null-modem cable.
 
 > It probably should have some of the cable stuff from the "Serial
 > Ports" section which says that a null-modem is AKA DTE-to-DTE cable
 > and what DTE is, eg, a computer.  And terminals traditionally have
 > included teletypes and printers. (Once there were no CRTs or LCDs.)
 
 >> To me, www.hardwarebook.net doen't seem the definite resource.
 >> IMHO, if the topic is rather wide, the reader should better be
 >> hinted to do a (re)search on the Net instead of pointed to a single
 >> resource, which is likely to become incomplete, outdated, or down.
 
 > I was thinking the same things.
 
 Ok.  Is it worth to mention a specialized book ("RS-232 Made Easy",
 for example) or not?
 
 >> We may show two or three different designs in the handbook if we
 >> can tell the reader about their merits.  The problem with the design
 >> currently in the handbook is that it is erroneous *and* bogus.  I'd
 >> suggest adding another row to the table so that it becomes evident
 >> that DTR on this side is connected to DSR+DCD on the other side
 >> while DTR on the other side is connected to DSR+DCD on this side.
 
 > The Note below the pin-out is supposed to make it evident, and with
 > the Note the design is symmetric.
 
 I tend to think the note is ok here, too.
 
 
 Please find a new patch attached which resumes the recent comments
 about the different null-modem designs, mainly based on the first
 reply from Gary.  I think it was the most concise and do not require
 a large rewriting or reorganization of the serial chapter (which can
 always be made later).
 
 Note: there are two versions of the patch.  One with a reference to
 the "RS-232 Made Easy" reference book, one without it.
 
 --
 -jpeg.
 ------=_20050830114835_68297
 Content-Type: application/octet-stream; name="chapter.sgml.diff"
 Content-Transfer-Encoding: base64
 Content-Disposition: attachment; filename="chapter.sgml.diff"
 
 LS0tIGNoYXB0ZXIuc2dtbC5vcmlnCU1vbiBBdWcgMjkgMjM6MjA6NTkgMjAwNQorKysgY2hhcHRl
 ci5zZ21sCVR1ZSBBdWcgMzAgMTE6NDA6NDUgMjAwNQpAQCAtMTIyLDEwICsxMjIsMTggQEAKIAkg
 ICAgZXhhbXBsZSwgdGhlIDxxdW90ZT5zZW5kIGRhdGE8L3F1b3RlPiBwaW4gb24gb25lIGVuZCBn
 b2VzIHRvIHRoZQogCSAgICA8cXVvdGU+cmVjZWl2ZSBkYXRhPC9xdW90ZT4gcGluIG9uIHRoZSBv
 dGhlciBlbmQuPC9wYXJhPgogCSAgICAgIAotCSAgPHBhcmE+SWYgeW91IGxpa2UgbWFraW5nIHlv
 dXIgb3duIGNhYmxlcywgeW91IGNhbiBjb25zdHJ1Y3QKLQkgICAgYSBudWxsLW1vZGVtIGNhYmxl
 IGZvciB1c2Ugd2l0aAotCSAgICB0ZXJtaW5hbHMuICBUaGlzIHRhYmxlIHNob3dzIHRoZSBSUy0y
 MzJDIHNpZ25hbCBuYW1lcyBhbmQgdGhlIHBpbgotCSAgICBudW1iZXJzIG9uIGEgREItMjUgY29u
 bmVjdG9yLjwvcGFyYT4KKwkgIDxwYXJhPklmIHlvdSBwcmVmZXIgbWFraW5nIHlvdXIgb3duIGNh
 YmxlcyAoZm9yIHF1YWxpdHkgcHVycG9zZSBmb3IKKwkgICAgZXhhbXBsZSksIHlvdSBjYW4gY29u
 c3RydWN0IGEgbnVsbC1tb2RlbSBjYWJsZSBmb3IgdXNlIHdpdGggdGVybWluYWxzLgorCSAgICBU
 aGlzIHRhYmxlIHNob3dzIHRoZSBSUy0yMzJDIHNpZ25hbCBuYW1lcyBhbmQgdGhlIHBpbiBudW1i
 ZXJzIG9uIGEKKwkgICAgREItMjUgY29ubmVjdG9yLiAgQSB3YXJuaW5nIHRob3VnaDogdGhlIHN0
 YW5kYXJkIGFsc28gY2FsbHMgZm9yIGEKKwkgICAgc3RyYWlnaHQtdGhyb3VnaCBwaW4gMSB0byBw
 aW4gMSA8cXVvdGU+cHJvdGVjdGl2ZSBncm91bmQ8L3F1b3RlPgorCSAgICBsaW5lLCBidXQgaXQg
 aXMgb2Z0ZW4gb21pdHRlZC4gIFNvbWUgdGVybWluYWxzIGNhbiBnZXQgYnkgdXNpbmcgb25seQor
 CSAgICBwaW5zIDIsIDMgYW5kIDcsIHdoaWxlIG90aGVycyByZXF1aXJlIGRpZmZlcmVudCBjb25m
 aWd1cmF0aW9ucyB0aGFuCisJICAgIHRoZSBleGFtcGxlIHNob3duIGJlbG93LjwvcGFyYT4KKwor
 CSAgPHBhcmE+SWYgdGhlIHByb3Bvc2VkIGRlc2lnbiBzZWVtcyB0byBiZSB0aGUgbW9zdCBwb3B1
 bGFyLCBvdGhlcnMgdGVuZAorCSAgdG8gcHJlZmVyIGEgZ2VuZXJpYyBudWxsLW1vZGVtIGRlc2ln
 biBsaWtlIHRoYXQsIGV4Y2VwdCBpdCBoYXMgcGlucyA0CisJICBhbmQgNSBnb2luZyB0byBwaW4g
 OCBhbmQgdmljZSB2ZXJzYS48L3BhcmE+CiAKIAkgIDxpbmZvcm1hbHRhYmxlIGZyYW1lPSJub25l
 IiBwZ3dpZGU9IjEiPgogCSAgICA8dGdyb3VwIGNvbHM9IjUiPgpAQCAtMTkyLDggKzIwMCw4IEBA
 CiAJCSAgPGVudHJ5PkRDRDwvZW50cnk+CiAJCSAgPGVudHJ5Pjg8L2VudHJ5PgogCQkgIDxlbnRy
 eT48L2VudHJ5PgotCQkgIDxlbnRyeT42PC9lbnRyeT4KLQkJICA8ZW50cnk+RFNSPC9lbnRyeT4K
 KwkJICA8ZW50cnk+ODwvZW50cnk+CisJCSAgPGVudHJ5PkRDRDwvZW50cnk+CiAJCTwvcm93Pgog
 CQkKIAkJPHJvdz4K
 ------=_20050830114835_68297
 Content-Type: application/octet-stream; name="chapter.sgml.wbook.diff"
 Content-Transfer-Encoding: base64
 Content-Disposition: attachment; filename="chapter.sgml.wbook.diff"
 
 LS0tIGNoYXB0ZXIuc2dtbC5vcmlnCU1vbiBBdWcgMjkgMjM6MjA6NTkgMjAwNQorKysgY2hhcHRl
 ci5zZ21sLndib29rCVR1ZSBBdWcgMzAgMTE6Mzg6NDcgMjAwNQpAQCAtMTIyLDEwICsxMjIsMjEg
 QEAKIAkgICAgZXhhbXBsZSwgdGhlIDxxdW90ZT5zZW5kIGRhdGE8L3F1b3RlPiBwaW4gb24gb25l
 IGVuZCBnb2VzIHRvIHRoZQogCSAgICA8cXVvdGU+cmVjZWl2ZSBkYXRhPC9xdW90ZT4gcGluIG9u
 IHRoZSBvdGhlciBlbmQuPC9wYXJhPgogCSAgICAgIAotCSAgPHBhcmE+SWYgeW91IGxpa2UgbWFr
 aW5nIHlvdXIgb3duIGNhYmxlcywgeW91IGNhbiBjb25zdHJ1Y3QKLQkgICAgYSBudWxsLW1vZGVt
 IGNhYmxlIGZvciB1c2Ugd2l0aAotCSAgICB0ZXJtaW5hbHMuICBUaGlzIHRhYmxlIHNob3dzIHRo
 ZSBSUy0yMzJDIHNpZ25hbCBuYW1lcyBhbmQgdGhlIHBpbgotCSAgICBudW1iZXJzIG9uIGEgREIt
 MjUgY29ubmVjdG9yLjwvcGFyYT4KKwkgIDxwYXJhPklmIHlvdSBwcmVmZXIgbWFraW5nIHlvdXIg
 b3duIGNhYmxlcyAoZm9yIHF1YWxpdHkgcHVycG9zZSBmb3IKKwkgICAgZXhhbXBsZSksIHlvdSBj
 YW4gY29uc3RydWN0IGEgbnVsbC1tb2RlbSBjYWJsZSBmb3IgdXNlIHdpdGggdGVybWluYWxzLgor
 CSAgICBUaGlzIHRhYmxlIHNob3dzIHRoZSBSUy0yMzJDIHNpZ25hbCBuYW1lcyBhbmQgdGhlIHBp
 biBudW1iZXJzIG9uIGEKKwkgICAgREItMjUgY29ubmVjdG9yLiAgQSB3YXJuaW5nIHRob3VnaDog
 dGhlIHN0YW5kYXJkIGFsc28gY2FsbHMgZm9yIGEKKwkgICAgc3RyYWlnaHQtdGhyb3VnaCBwaW4g
 MSB0byBwaW4gMSA8cXVvdGU+cHJvdGVjdGl2ZSBncm91bmQ8L3F1b3RlPgorCSAgICBsaW5lLCBi
 dXQgaXQgaXMgb2Z0ZW4gb21pdHRlZC4gIFNvbWUgdGVybWluYWxzIGNhbiBnZXQgYnkgdXNpbmcg
 b25seQorCSAgICBwaW5zIDIsIDMgYW5kIDcsIHdoaWxlIG90aGVycyByZXF1aXJlIGRpZmZlcmVu
 dCBjb25maWd1cmF0aW9ucyB0aGFuCisJICAgIHRoZSBleGFtcGxlIHNob3duIGJlbG93LjwvcGFy
 YT4KKworCSAgPHBhcmE+SWYgdGhlIHByb3Bvc2VkIGRlc2lnbiBzZWVtcyB0byBiZSB0aGUgbW9z
 dCBwb3B1bGFyLCBvdGhlcnMgdGVuZAorCSAgdG8gcHJlZmVyIGEgZ2VuZXJpYyBudWxsLW1vZGVt
 IGRlc2lnbiBsaWtlIHRoYXQsIGV4Y2VwdCBpdCBoYXMgcGlucyA0CisJICBhbmQgNSBnb2luZyB0
 byBwaW4gOCBhbmQgdmljZSB2ZXJzYSwgYXMgZXhwbGFpbmVkIGluIHRoZSBib29rCisJICA8cXVv
 dGU+UlMtMjMyIE1hZGUgRWFzeTwvcXVvdGU+LCBwdWJsaXNoZWQgYnkKKwkgIDx1bGluayB1cmw9
 Imh0dHA6Ly93d3cucHJlbmhhbGwuY29tLyI+UHJlbnRpY2UgSGFsbDwvdWxpbms+LCAxOTkxLgor
 CSAgSVNCTjogMDEzNzQ5ODU0My48L3BhcmE+CiAKIAkgIDxpbmZvcm1hbHRhYmxlIGZyYW1lPSJu
 b25lIiBwZ3dpZGU9IjEiPgogCSAgICA8dGdyb3VwIGNvbHM9IjUiPgpAQCAtMTkyLDggKzIwMyw4
 IEBACiAJCSAgPGVudHJ5PkRDRDwvZW50cnk+CiAJCSAgPGVudHJ5Pjg8L2VudHJ5PgogCQkgIDxl
 bnRyeT48L2VudHJ5PgotCQkgIDxlbnRyeT42PC9lbnRyeT4KLQkJICA8ZW50cnk+RFNSPC9lbnRy
 eT4KKwkJICA8ZW50cnk+ODwvZW50cnk+CisJCSAgPGVudHJ5PkRDRDwvZW50cnk+CiAJCTwvcm93
 PgogCQkKIAkJPHJvdz4K
 ------=_20050830114835_68297--
 
 

From: garys@opusnet.com (Gary W. Swearingen)
To: jpeg@thilelli.net
Cc: "Yar Tikhiy" <yar@comp.chem.msu.su>, bug-followup@FreeBSD.org
Subject: Re: docs/85355: [patch] Error in the pin numbers of the described 
 connector in the Handbook (serial).
Date: Tue, 30 Aug 2005 08:01:44 -0700

 "Julien Gabel" <jpeg@thilelli.net> writes:
 
 > Ok.  Is it worth to mention a specialized book ("RS-232 Made Easy",
 > for example) or not?
 
 I first wrote "not".  Too few people could find the old book in time
 for their need.  But it does have the important benefit of giving
 readers some reason to select the alternate design and thus justify
 the added paragraph's existance and discourage it's removal.  See
 below.
 
 > Note: there are two versions of the patch.  One with a reference to
 > the "RS-232 Made Easy" reference book, one without it.
 
 The first two paragraphs look OK to me, as-is.  But what you copied
 into the last para from my informal comments could be improved.  For
 example, I was wrong to have "generic null-modem"; there is no such
 thing.  I'll also comment on the first two paras, for kicks.
 
 +	  <para>If you prefer making your own cables (for quality purpose for
 +	    example), you can construct a null-modem cable for use with terminals.
 
 I would omit the (...); else, use "(for quality purposes, for example)"
 or "(e.g., for quality purposes)").  On second though, I would change
 it to simply "You can [...] with many serial devices".
 
 +	    DB-25 connector.  A warning though: the standard also calls for a
 
 I would omit "A warning though:" or at least "though".
 
 +	    straight-through pin 1 to pin 1 <quote>protective ground</quote>
 
 IIRC, that should be "<emphasis>", or something like that, so it
 could, for example, be rendered into italics.
 
 
 For the record: If this gets overhauled later, it should get a 9-pin
 version, which is more common these days (and which doesn't even have
 a protective ground pin).  Also: The design(s) _could_ be presented
 once in terms of signal names (eg, SG), and then the association of
 signals with pins given for 25-pin and 9-pin connectors.
 
 
 +	  <para>If the proposed design seems to be the most popular, others tend
 +	  to prefer a generic null-modem design like that, except it has pins 4
 +	  and 5 going to pin 8 and vice versa.</para>
 
    <para>The proposed design seems to be the most popular. In one
    variation (explained in the book <emphasis>RS-232 Made
    Easy</emphasis>) the note doesn't apply and at each end pins 4 and
    5 connect only to each other and to pin 8 at the other end.</para>
 
 The few who want to look for the book can start with a WWW search.
 
 Maybe someone can double-check my "replacement explanation".
 The book's diagram is something like this:
 
   1 -- 1  (No need to mention further, IMO)
   7 -- 7
   2 -- 3
   3 -- 2
   4+5 -- 8
   8 -- 4+5
   6 -- 20
  20 -- 6

From: Yar Tikhiy <yar@comp.chem.msu.su>
To: Julien Gabel <jpeg@thilelli.net>
Cc: "Gary W. Swearingen" <garys@opusnet.com>, bug-followup@FreeBSD.org
Subject: Re: docs/85355: [patch] Error in the pin numbers of the described connector in the Handbook (serial).
Date: Wed, 31 Aug 2005 14:03:11 +0400

 On Tue, Aug 30, 2005 at 11:48:35AM +0200, Julien Gabel wrote:
 > 
 > >> We may show two or three different designs in the handbook if we
 > >> can tell the reader about their merits.  The problem with the design
 > >> currently in the handbook is that it is erroneous *and* bogus.  I'd
 > >> suggest adding another row to the table so that it becomes evident
 > >> that DTR on this side is connected to DSR+DCD on the other side
 > >> while DTR on the other side is connected to DSR+DCD on this side.
 > 
 > > The Note below the pin-out is supposed to make it evident, and with
 > > the Note the design is symmetric.
 > 
 > I tend to think the note is ok here, too.
 
 I'd really like to see the design scheme all-sufficient without the
 note.  The note may clarify the scheme and help the reader to
 comprehend it, but the note should by no means be crucial to follow
 the scheme.  It is the matter of adding a mere row to the table:
 
 	...
 	DTR 20 connects to  6 DSR
 	DTR 20 connects to  8 DCD
 	DSR  6 connects to 20 DTR
 	DCD  8 connects to 20 DTR
 
 The reader is free either to install an internal strap between pins
 6 and 8 in each connector or to use two pairs of wires to connect
 pins 6 and 8 on each side to the single pin 20 on the other side.
 
 -- 
 Yar
State-Changed-From-To: open->analyzed 
State-Changed-By: garys 
State-Changed-When: Sat Sep 3 15:04:51 GMT 2005 
State-Changed-Why:  
Problem has been discussed; nearly decided on fix. 


Responsible-Changed-From-To: freebsd-doc->garys 
Responsible-Changed-By: garys 
Responsible-Changed-When: Sat Sep 3 15:04:51 GMT 2005 
Responsible-Changed-Why:  
I'll work with contributor and mentor on this. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=85355 

From: "Julien Gabel" <jpeg@thilelli.net>
To: "Gary W. Swearingen" <garys@opusnet.com>
Cc: "Yar Tikhiy" <yar@comp.chem.msu.su>,
 bug-followup@freebsd.org
Subject: Re: docs/85355: [patch] Error in the pin numbers of the described  
     connector in the Handbook (serial).
Date: Sat, 3 Sep 2005 23:11:41 +0200 (CEST)

 >> Ok.  Is it worth to mention a specialized book ("RS-232 Made Easy",
 >> for example) or not?
 
 > I first wrote "not".  Too few people could find the old book in time
 > for their need.  But it does have the important benefit of giving
 > readers some reason to select the alternate design and thus justify
 > the added paragraph's existance and discourage it's removal.  See
 > below.
 
 Seems fine to me.
 
 >> Note: there are two versions of the patch.  One with a reference to
 >> the "RS-232 Made Easy" reference book, one without it.
 
 > The first two paragraphs look OK to me, as-is.  But what you copied
 > into the last para from my informal comments could be improved.  For
 > example, I was wrong to have "generic null-modem"; there is no such
 > thing.  I'll also comment on the first two paras, for kicks.
 >
 > + <para>If you prefer making your own cables (for quality purpose for
 > + example), you can construct a null-modem cable for use with terminals.
 >
 > I would omit the (...); else, use "(for quality purposes, for example)"
 > or "(e.g., for quality purposes)").  On second though, I would change
 > it to simply "You can [...] with many serial devices".
 
 Ok, i will modify this part according to your proposal.
 
 > + DB-25 connector.  A warning though: the standard also calls for a
 >
 > I would omit "A warning though:" or at least "though".
 
 Same thing here.
 
 > + straight-through pin 1 to pin 1 <quote>protective ground</quote>
 >
 > IIRC, that should be "<emphasis>", or something like that, so it
 > could, for example, be rendered into italics.
 
 Don't know what is the best here.  If you think it is better to put
 "<emphasis>" instead of "<quote>", i have nothing against that (and
 will change it in the next patch).
 
 > For the record: If this gets overhauled later, it should get a 9-pin
 > version, which is more common these days (and which doesn't even have
 > a protective ground pin).  Also: The design(s) _could_ be presented
 > once in terms of signal names (eg, SG), and then the association of
 > signals with pins given for 25-pin and 9-pin connectors.
 
 Without overhaul all this section, i will try to include something
 about that since i agree that nowadays the DB-9 connectors are more
 common, as with modern PCs (i currently use my notebook as "terminal"
 for connecting to servers this way).
 
 > + <para>If the proposed design seems to be the most popular, others tend
 > +   to prefer a generic null-modem design like that, except it has pins 4
 > +   and 5 going to pin 8 and vice versa.</para>
 >
 >    <para>The proposed design seems to be the most popular. In one
 >    variation (explained in the book <emphasis>RS-232 Made
 >    Easy</emphasis>) the note doesn't apply and at each end pins 4 and
 >    5 connect only to each other and to pin 8 at the other end.</para>
 >
 > The few who want to look for the book can start with a WWW search.
 
 I will keep the ISBN number, in order to help further search on WWW.
 
 > Maybe someone can double-check my "replacement explanation".
 > The book's diagram is something like this:
 >
 >   1 -- 1  (No need to mention further, IMO)
 >   7 -- 7
 >   2 -- 3
 >   3 -- 2
 >   4+5 -- 8
 >   8 -- 4+5
 >   6 -- 20
 >  20 -- 6
 
 I will work with you directly to provide a new patch (one is pending
 behind the door), including Yar's proposition.
 
 -- 
 -jpeg.
 

From: "Julien Gabel" <jpeg@thilelli.net>
To: "Yar Tikhiy" <yar@comp.chem.msu.su>
Cc: "Gary W. Swearingen" <garys@opusnet.com>,
 bug-followup@freebsd.org
Subject: Re: docs/85355: [patch] Error in the pin numbers of the described 
     connector in the Handbook (serial).
Date: Sat, 3 Sep 2005 23:11:55 +0200 (CEST)

 >>>> We may show two or three different designs in the handbook if we
 >>>> can tell the reader about their merits.  The problem with the design
 >>>> currently in the handbook is that it is erroneous *and* bogus.  I'd
 >>>> suggest adding another row to the table so that it becomes evident
 >>>> that DTR on this side is connected to DSR+DCD on the other side
 >>>> while DTR on the other side is connected to DSR+DCD on this side.
 
 >>> The Note below the pin-out is supposed to make it evident, and with
 >>> the Note the design is symmetric.
 
 >> I tend to think the note is ok here, too.
 
 > I'd really like to see the design scheme all-sufficient without the
 > note.  The note may clarify the scheme and help the reader to
 > comprehend it, but the note should by no means be crucial to follow
 > the scheme.  It is the matter of adding a mere row to the table:
 >
 > 	...
 > 	DTR 20 connects to  6 DSR
 > 	DTR 20 connects to  8 DCD
 > 	DSR  6 connects to 20 DTR
 > 	DCD  8 connects to 20 DTR
 >
 > The reader is free either to install an internal strap between pins
 > 6 and 8 in each connector or to use two pairs of wires to connect
 > pins 6 and 8 on each side to the single pin 20 on the other side.
 
 I will propose a new patch with some modifications, incuding yours,
 in next hours to the responsible committer (Gary W. Swearingen).
 
 -- 
 -jpeg.
 
State-Changed-From-To: analyzed->closed 
State-Changed-By: garys 
State-Changed-When: Fri Sep 30 18:05:19 GMT 2005 
State-Changed-Why:  
Committed change after working with submitter on it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=85355 
>Unformatted:
