My reorganization of chapter 9.

Reviewed by:	jfieber

4 files changed, 141 insertions, 58 deletions

diff --git a/share/doc/handbook/esdi.sgml b/share/doc/handbook/esdi.sgml
index 6d2c3dee5df4..dee7b4408dc0 100644
--- a/share/doc/handbook/esdi.sgml
+++ b/share/doc/handbook/esdi.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: esdi.sgml,v 1.1 1995/09/25 04:53:30 jfieber Exp $ -->
+<!-- $Id: esdi.sgml,v 1.2 1995/10/07 04:31:20 jfieber Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <!--
@@ -21,7 +21,7 @@
       </abstract>
 -->
 
-    <sect><heading>ESDI hard disks and FreeBSD<label id="esdi"></heading>
+    <sect1><heading>Using ESDI hard disks<label id="esdi"></heading>
 
       <p><em>Copyright &copy; 1995, &a.wilko;.<newline>24 September 1995.</em>
 
@@ -46,9 +46,9 @@
 	the availability of free or cheap surplus drives makes them 
 	ideal for low (or now) budget systems.
 
-    <sect1><heading>Concepts of ESDI</heading>
+    <sect2><heading>Concepts of ESDI</heading>
       <p>
-      <sect2><heading>Physical connections</heading>
+      <sect3><heading>Physical connections</heading>
         <p>
 	The ESDI interface uses two cables connected to each drive. 
 	One cable is a 34 pin flatcable edge connector that carries
@@ -67,7 +67,7 @@
 	compatibility feature(?) left over from the WD1003 standard
 	that reserves only a single bit for device addressing.
 
-      <sect2><heading>Device addressing</heading>
+      <sect3><heading>Device addressing</heading>
         <p>
 	On each command cable a maximum of 7 devices and 1 controller
 	can be present. To enable the controller to uniquely 
@@ -80,7 +80,7 @@
 	two drives/controller maximum the first drive is drive 0, the
 	second is drive 1.
 
-      <sect2><heading>Termination</heading>
+      <sect3><heading>Termination</heading>
 	<p>
 	The daisy chained command cable (the 34 pin cable remember?)
 	needs to be terminated at the last drive on the chain.
@@ -95,7 +95,7 @@
 	Please note that this implies that the controller must be 
 	at one end of the cable and <it>not</it> in the middle.
 
-    <sect1><heading>Using ESDI disks with FreeBSD</heading>
+    <sect2><heading>Using ESDI disks with FreeBSD</heading>
       <p>
         Why is ESDI such a pain to get working in the first place?
       
@@ -109,7 +109,7 @@
 	The following sections try to list all the pitfalls and 
 	solutions.
 
-      <sect2><heading>ESDI speed variants</heading>
+      <sect3><heading>ESDI speed variants</heading>
 	<p>
 	As briefly mentioned before, ESDI comes in two speed flavours.
 	The older drives and controllers use a 10 Mbits/second
@@ -120,7 +120,7 @@
 	As always, consult your controller <it>and</it> drive 
 	documentation to see if things match.
 
-      <sect2><heading>Stay on track</heading>
+      <sect3><heading>Stay on track</heading>
 	<p>
 	Mainstream ESDI drives use 34 to 36 sectors per track. 
 	Most (older) controllers cannot handle more than this 
@@ -139,7 +139,7 @@
 	or might not work. Give it a try or get another more
 	capable controller.
 
-      <sect2><heading>Hard or soft sectoring</heading>
+      <sect3><heading>Hard or soft sectoring</heading>
 	<p>
 	Most ESDI drives allow hard or soft sectoring to be 
 	selected using a jumper. Hard sectoring means that the
@@ -167,7 +167,7 @@
 	FreeBSD because you need to re-run the low-level format
 	after each change.
 
-      <sect2><heading>Low level formatting</heading>
+      <sect3><heading>Low level formatting</heading>
 	<p>
 	ESDI drives need to be low level formatted before they
 	are usable. A reformat is needed whenever you figgle
@@ -191,7 +191,7 @@
 	and more importantly causes you grief with bad144
 	(see the section on bad144).
 	
-      <sect2><heading>Translations</heading>
+      <sect3><heading>Translations</heading>
 	<p>
 	Translations, although not exclusively a ESDI-only problem, 
 	might give you real trouble.
@@ -240,7 +240,7 @@
 	read the info and presented itself to the system based on
 	the info from the disk.
 
-      <sect2><heading>Spare sectoring</heading>
+      <sect3><heading>Spare sectoring</heading>
         <p>
 	Most ESDI controllers offer the possibility to remap bad sectors.
 	During/after the low-level format of the disk bad sectors are
@@ -265,7 +265,7 @@
 	whatever it may be called by the controller manufacturer when you
 	want to use the disk for FreeBSD.</em>
 	
-      <sect2><heading>Bad block handling</heading>
+      <sect3><heading>Bad block handling</heading>
 	<p>
 	The preceding section leaves us with a problem. The controller's
 	bad block handling is not usable and still FreeBSD's filesystems
@@ -303,7 +303,7 @@
 	rather the entire <em>slice</em> that contains the root filesystem.
 
 
-      <sect2><heading>Kernel configuration</heading>
+      <sect3><heading>Kernel configuration</heading>
         <p>
 	ESDI disks are handled by the same <it>wd</it>driver as
 	IDE and ST412 MFM disks. The <it>wd</it> driver should work
@@ -332,13 +332,13 @@ disk            wd3     at wdc1 drive 1
 </verb></tscreen>
 
 <!--
-      <sect2><heading>Tuning your ESDI kernel setup</heading>
+      <sect3><heading>Tuning your ESDI kernel setup</heading>
         <p>
 -->
 
-    <sect1><heading>Particulars on ESDI hardware</heading>
+    <sect2><heading>Particulars on ESDI hardware</heading>
       <p>
-	<sect2><heading>Adaptec 2320 controllers</heading>
+	<sect3><heading>Adaptec 2320 controllers</heading>
 	<p>
 	I succesfully installed FreeBSD onto a ESDI disk controlled by a
 	ACB-2320. No other operating system was present on the disk.
@@ -370,7 +370,7 @@ disk            wd3     at wdc1 drive 1
 	All variations should be capable of using 1:1 interleaving. Use 1:1,
 	FreeBSD is fast enough to handle it.
 
-    	<sect2><heading>Western Digital WD1007 controllers</heading>
+    	<sect3><heading>Western Digital WD1007 controllers</heading>
 	<p>
 	I succesfully installed FreeBSD onto a ESDI disk controlled by a
         WD1007 controller. To be precise, it was a WD1007-WA2. Other
@@ -382,7 +382,7 @@ disk            wd3     at wdc1 drive 1
 	WDFMT.EXE from www.wdc.com Running this formatted my drive
 	just fine. 
 	
-	<sect2><heading>Ultrastor U14F controllers</heading>
+	<sect3><heading>Ultrastor U14F controllers</heading>
 	<p>
 	According to multiple reports from the net, Ultrastor ESDI 
 	boards work OK with FreeBSD. I lack any further info on
@@ -390,11 +390,11 @@ disk            wd3     at wdc1 drive 1
 	
 <!--
 
-    <sect1><heading>Tracking down problems</heading>
+    <sect2><heading>Tracking down problems</heading>
       <p>
 -->
 
-    <sect1><heading>Further reading<label id="esdi:further-reading"></>
+    <sect2><heading>Further reading<label id="esdi:further-reading"></>
       <p>
         If you intend to do some serious ESDI hacking, you might want to
         have the official standard at hand:
@@ -414,7 +414,7 @@ disk            wd3     at wdc1 drive 1
 	For info on Western Digital controllers see <htmlurl
         url="http://www.wdc.com/">.
 
-    <sect1>Thanks to...
+    <sect2>Thanks to...
 	<p>
 	Andrew Gordon for sending me an Adaptec 2320 controller and ESDI disk 
 	for testing.
diff --git a/share/doc/handbook/handbook.sgml b/share/doc/handbook/handbook.sgml
index d53b485f6d7f..a21ba8c0ac98 100644
--- a/share/doc/handbook/handbook.sgml
+++ b/share/doc/handbook/handbook.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: handbook.sgml,v 1.7.4.5 1995/10/30 17:48:17 jfieber Exp $ -->
+<!-- $Id: handbook.sgml,v 1.34 1995/11/20 01:10:20 jfieber Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
@@ -78,13 +78,7 @@ Web server">.
          documentation supplied by the <url url="http://www.xfree86.org/"
          name="The XFree86 Project, Inc">.
 
-    <chapt><heading>Managing hardware</heading>
-      <sect><heading>* Adding and reconfiguring disks</heading>
-      &scsi;
-      &esdi;
-      <sect><heading>* Tapes and backups</heading>
-      <sect><heading>* Serial ports</heading>
-      <sect><heading>* Sound cards</heading>
+    &hw;
 
 <!-- ************************************************************ -->	      
 
@@ -140,7 +134,6 @@ Web server">.
     &mirrors;
     &bibliography;
     &eresources;
-    &hw;
     <chapt><heading>Assorted technical topics</heading>
       &booting;
       &memoryuse;
diff --git a/share/doc/handbook/hw.sgml b/share/doc/handbook/hw.sgml
index a85bfa81f679..472611389cf2 100644
--- a/share/doc/handbook/hw.sgml
+++ b/share/doc/handbook/hw.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: hw.sgml,v 1.7 1995/10/02 15:59:53 wollman Exp $ -->
+<!-- $Id: hw.sgml,v 1.8 1995/10/07 04:31:26 jfieber Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <!-- 
@@ -32,6 +32,95 @@
     FreeBSD you are using and include as many details of your
     hardware as possible.
 
+<sect><heading>Sample Configurations<label id="hw:configs"></heading>
+<p>The following list of sample hardware configurations by no means
+constitutes an endorsement of a given hardware vendor or product by
+<em>The FreeBSD Project</em>.  This information is provided only as a public
+service and merely catalogs some of the experiences that various individuals
+have had with different hardware combinations.  Your mileage may vary.
+Slippery when wet.  Beware of dog.
+
+ <sect1><heading>Jordan's Picks</heading>
+    <p>I have had fairly good luck building workstation and server
+    configurations with the following components.  I can't guarantee that
+    you will too, nor that any of the companies here will remain "best buys"
+    forever.  I will try, when I can, to keep this list up-to-date but
+    cannot obviously guarantee that it will be at any given time.
+
+  <sect2><heading>Motherboards</heading>
+    <p>The <htmlurl url="http://asustek.asus.com.tw/" name="ASUS"> P55TP4XE
+    motherboard appears to be a good choice for mid-to-high range Pentium
+    server and workstation systems.  If you're really looking for performance,
+    be also sure to get the <htmlurl url="http://asustek.asus.com.tw/Products/TB/mem-0002.html" name="pipelined burst cache module">.  It's worth the extra
+    cost, I feel.  If you're looking for a 486 class motherboard, you might
+    also investigate ASUS's 486SP3G offering.
+
+  <sect2><heading>Disk Controllers</heading>
+    <p>This one is a bit trickier, and while I used to recommend the
+    <htmlurl url="http://www.buslogic.com" name="Buslogic"> controllers
+    unilaterally for everything from ISA to PCI, now I tend to lean
+    towards the <htmlurl url="http://www.adaptec.com" name="Adaptec">
+    1542CF for ISA, Buslogic Bt747c for EISA and Adaptec 2940 for PCI.
+    I've currently heard nothing about Buslogic's new Bt-930 controller
+    but would welcome any reports on its performance.
+
+  <sect2><heading>Disk drives</heading>
+    <p>In this particular game of russian roulette, I'll make few specific
+    recommendations except to say "SCSI over IDE whenever you can afford it."
+    Even in small desktop configurations, SCSI often makes more sense since it
+    allows you to migrate drives from server to desktop as falling drive
+    prices make it economical to do so.  If you have more than one machine
+    to administer then think of it not simply as storage, think of it as a
+    food chain.
+
+    <p>I do not currently see SCSI WIDE drives as a necessary expense unless
+    you're putting together an NFS or NEWS server that will be doing a lot
+    of multiuser disk I/O.  
+
+  <sect2><heading>Video Cards</heading>
+    <p>If you can also afford to buy a commercial X server for $99 from
+    <htmlurl url="http://www.xinside.com/" name="X Inside"> then I
+    can heartily recommend the <htmlurl url="http://www.matrox.com/"
+    name="Matrox"> <htmlurl url="http://www.matrox.com/mgaweb/brochure.htm"
+    name="Millenium"> card.  If free X servers are more to your
+    liking, you certainly can't go wrong with one of <htmlurl url="http://www.nine.com/" name="Number 9's"> cards.  Their S3 Vision 868 and 968 based cards 
+    (the 9FX series) are no slouches either, and are supported by
+    <htmlurl url="http://www.xfree86.org" name="XFree86">'s S3 server.
+
+  <sect2><heading>Monitors</heading>
+    <p>I have had very good luck with the <htmlurl url="http://cons3.sel.sony.com/SEL/ccpg/display/ms17se2.html"
+    name="Sony Multiscan 17SE monitors">, as have I with 
+    the Viewsonic offering in the same (trinitron) tube.  For larger than
+    17", all I can recommend at the time of this writing is to not spend
+    any less than U.S. $2,500 for a 21" monitor if that's what you really
+    need.  There are good monitors available in the >=20" range and there
+    are also cheap monitors in the >=20" range.  Unfortunately, none are
+    both cheap and good!
+
+  <sect2><heading>Networking</heading>
+    <p>I can recommend the <htmlurl url="http://www.smc.com/" name="SMC">
+    Ultra 16 controller for any ISA application and the SMC EtherPower
+    or Compex ENET32 cards for any serious PCI based networking.  Both of
+    the PCI cards are based around DEC's DC21041 ethernet controller
+    chip and other cards using it, such as the Zynx ZX342 or DEC DE435,
+    will generally work as well.
+
+    <p>If you're looking for high-speed serial networking solutions, then
+    <htmlurl url="http://www.digiboard.com/" name="Digi International">
+    makes the <htmlurl url="http://www.digiboard.com/prodprofiles/profiles-prices/arnetprofiles/sync570i.html" name="SYNC 570i"> series, with drivers now in
+    FreeBSD-current. <htmlurl url="http://www.etinc.com"
+    name="Emerging Technologies"> also manufactures a board with T1/E1
+    capabilities, using software they provide.
+
+   <sect2><heading>Audio</heading>
+    <p>I currently use the <htmlurl url="http://www.gravis.com/" name="Gravis">
+    Ultrasound MAX due to its high sound quality and full-duplex audio
+    capabilities (dual DMA channels).  Support for Windows NT and OS/2 is
+    fairly anemic, however, so I'm not sure that I can recommend it as an
+    all-around card for a machine that will be running both FreeBSD and NT
+    or OS/2.  In such a scenario, I might recommend the <htmlurl url="http://www.creaf.com/" name="Creative Labs"> AWE32 instead.
+
+
 <sect><heading>Core/Processing<label id="hw:core"></heading>
 
 <sect1><heading>Motherboards, busses, and chipsets</heading>
@@ -300,8 +389,9 @@ sio16: type 16550A (multiport master)
 <sect1><heading>* Mice</heading>
 <sect1><heading>* Other</heading>
 
-<sect><heading>* Storage Devices<label id="hw:storage"></heading>
-
+<sect><heading>Storage Devices<label id="hw:storage"></heading>
+&esdi;
+&scsi;
 <sect1><heading>* Disk/tape controllers</heading>
   <sect2><heading>* SCSI</heading>
   <sect2><heading>* IDE</heading>
@@ -311,9 +401,9 @@ sio16: type 16550A (multiport master)
 <sect1><heading>* CD-ROM drives</heading>
 <sect1><heading>* Other</heading>
 
-<sect><heading>* Other<label id="hw:other"></heading>
-
+<sect1><heading>* Adding and reconfiguring disks</heading>
+<sect1><heading>* Tapes and backups</heading>
+<sect1><heading>* Serial ports</heading>
+<sect1><heading>* Sound cards</heading>
 <sect1><heading>* PCMCIA</heading>
-	  
-
-
+<sect1><heading>* Other<label id="hw:other"></heading>
diff --git a/share/doc/handbook/scsi.sgml b/share/doc/handbook/scsi.sgml
index f1e18704b60f..c683647e755e 100644
--- a/share/doc/handbook/scsi.sgml
+++ b/share/doc/handbook/scsi.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: scsi.sgml,v 1.7 1995/11/20 01:10:30 jfieber Exp $ -->
+<!-- $Id: scsi.sgml,v 1.8 1995/11/20 05:46:00 julian Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <!--
@@ -13,7 +13,7 @@
       </abstract>
       
 -->
-    <sect><heading>SCSI<label id="scsi"></heading>
+    <sect1><heading>What is SCSI?<label id="scsi"></heading>
 
       <p><em>Copyright &copy; 1995, &a.wilko;.<newline>3 September 1995.</em>
 
@@ -87,9 +87,9 @@
 	pre-SCSI-1 disk, a SCSI-2 QIC tape unit, a SCSI-1 helical scan
 	tape unit and 2 SCSI-1 disks work together quite happily.
 
-    <sect1><heading>Components of SCSI</heading>
+    <sect2><heading>Components of SCSI</heading>
       <p>
-<!--      <sect2><heading>A <it>smart</it> interface</heading>
+<!--      <sect3><heading>A <it>smart</it> interface</heading>
         <p> -->
           As said before, SCSI devices are smart.  The idea is to put the
           knowledge about intimate hardware details onto the SCSI device
@@ -104,7 +104,7 @@
 	  there is no longer a need to change (and qualify!) drivers for 
 	  every odd new device that is introduced.
 
-<!--      <sect2><heading>Do's and don't's on interconnections</heading>
+<!--      <sect3><heading>Do's and don't's on interconnections</heading>
         <p> -->
           For cabling and connectors there is a golden rule: get good
           stuff. With bus speeds going up all the time you will save
@@ -217,7 +217,7 @@
 	    AH1740 as a single ended board, whereas the AH1744 was differential.
 	    The software interface to the host is identical for both.
 
-        <sect2><heading>Terminators</heading>
+        <sect3><heading>Terminators</heading>
           <p>
             Terminators in SCSI terminology are resistor networks that are
             used to get a correct impedance matching.  Impedance matching
@@ -278,7 +278,7 @@
             for the internal flat cable connectors. This makes
             reconfiguration much easier.
         
-        <sect2><heading>Terminator power</heading>
+        <sect3><heading>Terminator power</heading>
           <p>
             The terminators discussed in the previous chapter need power to
             operate properly.  On the SCSI bus, a line is dedicated to this
@@ -318,7 +318,7 @@
             configurable, using some sort of setup tool. Consult you
 	    documentation!
 
-        <sect2><heading>Device addressing</heading>
+        <sect3><heading>Device addressing</heading>
           <p>
             Because the SCSI bus is, ehh, a bus there must be a way to
             distinguish or address the different devices connected to it.
@@ -350,7 +350,7 @@
             tape changer. In this way, the host system can address each of
             the parts of the tape unit as desired.
 
-        <sect2><heading>Bus layout</heading>
+        <sect3><heading>Bus layout</heading>
           <p>
             SCSI buses are linear. So, not shaped like Y-junctions, star
             topologies, cobwebs or whatever else people might want to
@@ -365,9 +365,9 @@
 
             <bf>Stick to the linear bus rule!</bf>
 
-    <sect1><heading>Using SCSI with FreeBSD</heading>
+    <sect2><heading>Using SCSI with FreeBSD</heading>
       <p>
-      <sect2><heading>About translations, BIOSes and magic...</heading>
+      <sect3><heading>About translations, BIOSes and magic...</heading>
         <p>
           As stated before, you should first make sure that you have a
           electrically sound bus.
@@ -458,7 +458,7 @@
 	  about this disk</em>, (e.g. it is not a booting disk) to supply a
 	  ficticious geometry that is convenient.
 
-      <sect2><heading>SCSI subsystem design</heading>
+      <sect3><heading>SCSI subsystem design</heading>
         <p>
           FreeBSD uses a layered SCSI subsystem. For each different
           controller card a device driver is written. This driver
@@ -478,7 +478,7 @@
           banging and more high level stuff. Adding support for another
           piece of hardware is a much more managable problem.
         
-      <sect2><heading>Kernel configuration</heading>
+      <sect3><heading>Kernel configuration</heading>
         <p>
           Dependent on your hardware, the kernel configuration file must
           contain one or more lines describing your host adapter(s). 
@@ -604,7 +604,7 @@ device          cd0     #Only need one of these, the code dynamically grows &lsq
           subsystem. For more detailed info on host adapter drivers use eg
           <tt>man 4 aha</tt> for info on the Adaptec 154x driver.
 
-      <sect2><heading>Tuning your SCSI kernel setup</heading>
+      <sect3><heading>Tuning your SCSI kernel setup</heading>
         <p>
           Experience has shown that some devices are slow to respond to INQUIRY 
 	  commands after a SCSI bus reset (which happens at Boot time).
@@ -626,7 +626,7 @@ options         "SCSI_DELAY=15"         #Be pessimistic about Joe SCSI device
 	  with device recognition. If this helps, tune it back until it just stays
 	  working.
 
-      <sect2><heading>Rogue SCSI devices</heading>
+      <sect3><heading>Rogue SCSI devices</heading>
         <p>  
 	  Although the SCSI standard tries to be complete and concise, it is
 	  a complex standard and implementing things correctly is no easy task.
@@ -662,7 +662,7 @@ Mar 29 21:16:37 yedi /386bsd: st1: Archive  Viper 150 is a known rogue
           to connect your bogus Mumbletech SCSI cdrom you might be the one
 	  that has to define which workaround is needed.
 
-      <sect2><heading>Busmaster host adapters</heading>
+      <sect3><heading>Busmaster host adapters</heading>
         <p>
 	  Most, but not all, SCSI host adapters are bus mastering controllers.
 	  This means that they can do I/O on their own without putting load onto
@@ -693,7 +693,7 @@ options        "TUNE_1542"             #dynamic tune of bus DMA speed
 	  Check the man pages for the host adapter that you use. Or better
 	  still, use the ultimate documentation (read: driver source).
 
-    <sect1><heading>Tracking down problems</heading>
+    <sect2><heading>Tracking down problems</heading>
       <p>
         The following list is an attempt to give a guideline for the most
         common SCSI problems and their solutions. It is by no means
@@ -731,7 +731,7 @@ options        "TUNE_1542"             #dynamic tune of bus DMA speed
 	    Also look at <tt>man 8 scsi</tt>.
         </itemize>
 
-    <sect1><heading>Further reading<label id="scsi:further-reading"></heading>
+    <sect2><heading>Further reading<label id="scsi:further-reading"></heading>
       <p>
         If you intend to do some serious SCSI hacking, you might want to
         have the official standard at hand: