Whitespace-only changes. Wrap long lines, fix indentation.

svn path=/head/; revision=38641

en_US.ISO8859-1/books/arch-handbook/pccard/chapter.sgml

@@ -38,32 +38,32 @@
 	driver.</para>
 
       <para>Original equipment manufacturers (<acronym>OEM</acronym>s)
-	often develop a
+	often develop a reference design for a PC Card product, then
-	reference design for a PC Card product, then sell this design
+	sell this design to other companies to market.  Those
-	to other companies to market.  Those companies refine the
+	companies refine the design, market the product to their
-	design, market the product to their target audience or
+	target audience or geographic area, and put their own name
-	geographic area, and put their own name plate onto the card.
+	plate onto the card.  The refinements to the physical card are
-	The refinements to the physical card are typically very minor,
+	typically very minor, if any changes are made at all.  To
-	if any changes are made at all.  To strengthen their brand,
+	strengthen their brand, these vendors place their company name
-	these vendors place their company name in the human readable strings in
+	in the human readable strings in the CIS space, but leave the
-	the CIS space, but leave the manufacturer and product IDs
+	manufacturer and product IDs unchanged.</para>
-	unchanged.</para>
 
       <indexterm><primary>NetGear</primary></indexterm>
       <indexterm><primary>Linksys</primary></indexterm>
       <indexterm><primary>D-Link</primary></indexterm>
 
       <para>Because of this practice, FreeBSD drivers usually rely on
-	numeric IDs for device identification.  Using numeric IDs and a centralized database
+	numeric IDs for device identification.  Using numeric IDs and
-	complicates adding IDs and support for cards to the system.
+	a centralized database complicates adding IDs and support for
-	One must carefully check to see who really made the card,
+	cards to the system.  One must carefully check to see who
-	especially when it appears that the vendor who made the card
+	really made the card, especially when it appears that the
-	might already have a different manufacturer ID listed in the
+	vendor who made the card might already have a different
-	central database.  Linksys, D-Link, and NetGear are a number of
+	manufacturer ID listed in the central database.  Linksys,
-	US manufacturers of LAN hardware that often sell the same
+	D-Link, and NetGear are a number of US manufacturers of LAN
-	design.  These same designs can be sold in Japan under names
+	hardware that often sell the same design.  These same designs
-	such as Buffalo and Corega.  Often, these devices will all
+	can be sold in Japan under names such as Buffalo and Corega.
-	have the same manufacturer and product IDs.</para>
+	Often, these devices will all have the same manufacturer and
+	product IDs.</para>
 
       <para>The PC Card bus code keeps a central database of card
 	information, but not which driver is associated with them, in
@@ -108,7 +108,7 @@
 	information.  For example, here are the first few vendor
 	IDs:</para>
 
-<programlisting>vendor FUJITSU			0x0004  Fujitsu Corporation
+      <programlisting>vendor FUJITSU			0x0004  Fujitsu Corporation
 vendor NETGEAR_2		0x000b  Netgear
 vendor PANASONIC		0x0032	Matsushita Electric Industrial Co.
 vendor SANDISK			0x0045	Sandisk Corporation</programlisting>
@@ -136,7 +136,7 @@ vendor SANDISK			0x0045	Sandisk Corporation</programlisting>
 	shown in this example, the format is similar to the vendor
 	lines:</para>
 
-<programlisting>/* Allied Telesis K.K. */
+      <programlisting>/* Allied Telesis K.K. */
 product ALLIEDTELESIS LA_PCM	0x0002 Allied Telesis LA-PCM
 
 /* Archos */
@@ -168,34 +168,34 @@ product	ARCHOS ARC_ATAPI	0x0043 MiniCD</programlisting>
 	section of the file.</para>
 
       <para>The final section contains the entries for those cards
-	that must be identified by string entries.  This section's format
+	that must be identified by string entries.  This section's
-	is a little different from the generic section:</para>
+	format is a little different from the generic section:</para>
 
-<programlisting>product ADDTRON AWP100		{ "Addtron", "AWP-100&amp;spWireless&amp;spPCMCIA", "Version&amp;sp01.02", NULL }
+      <programlisting>product ADDTRON AWP100		{ "Addtron", "AWP-100&amp;spWireless&amp;spPCMCIA", "Version&amp;sp01.02", NULL }
 product ALLIEDTELESIS WR211PCM	{ "Allied&amp;spTelesis&amp;spK.K.", "WR211PCM", NULL, NULL } Allied Telesis WR211PCM</programlisting>
 
       <para>The familiar <literal>product</literal> keyword is
 	followed by the vendor name and the card name, just as in the
 	second section of the file.  Here the format deviates from
-	that used earlier.  There is a {} grouping, followed by a number of
+	that used earlier.  There is a {} grouping, followed by a
-	strings.  These strings correspond to the vendor, product, and
+	number of strings.  These strings correspond to the vendor,
-	extra information that is defined in a CIS_INFO tuple.  These
+	product, and extra information that is defined in a CIS_INFO
-	strings are filtered by the program that generates
+	tuple.  These strings are filtered by the program that
-	<filename>pccarddevs.h</filename> to replace &amp;sp with a
+	generates <filename>pccarddevs.h</filename> to replace &amp;sp
-	real space.  NULL strings mean that the corresponding part of
+	with a real space.  NULL strings mean that the corresponding
-	the entry should be ignored.  The example shown here contains
+	part of the entry should be ignored.  The example shown here
-	a bad entry.  It should not contain the version number unless
+	contains a bad entry.  It should not contain the version
-	that is critical for the operation of the card.  Sometimes
+	number unless that is critical for the operation of the card.
-	vendors will have many different versions of the card in the
+	Sometimes vendors will have many different versions of the
-	field that all work, in which case that information only makes
+	card in the field that all work, in which case that
-	it harder for someone with a similar card to use it with
+	information only makes it harder for someone with a similar
-	FreeBSD.  Sometimes it is necessary when a vendor wishes to
+	card to use it with FreeBSD.  Sometimes it is necessary when a
-	sell many different parts under the same brand due to market
+	vendor wishes to sell many different parts under the same
-	considerations (availability, price, and so forth).  Then it
+	brand due to market considerations (availability, price, and
-	can be critical to disambiguating the card in those rare cases
+	so forth).  Then it can be critical to disambiguating the card
-	where the vendor kept the same manufacturer/product pair.
+	in those rare cases where the vendor kept the same
-	Regular expression matching is not available at this
+	manufacturer/product pair.  Regular expression matching is not
-	time.</para>
+	available at this time.</para>
     </sect2>
 
     <sect2 id="pccard-probe">
@@ -309,7 +309,8 @@ product BUFFALO LPC_CF_CLT	0x0307	BUFFALO LPC-CF-CLT
 product	BUFFALO	LPC3_CLT	0x030a	BUFFALO LPC3-CLT Ethernet Adapter
 product BUFFALO WLI_CF_S11G	0x030b	BUFFALO AirStation 11Mbps CF WLAN</programlisting>
 
-      <para>To add the device, we can just add this entry to <filename>pccarddevs</filename>:</para>
+      <para>To add the device, we can just add this entry to
+	<filename>pccarddevs</filename>:</para>
 
       <programlisting>product BUFFALO WLI2_CF_S11G	0x030c	BUFFALO AirStation ultra 802.11b CF</programlisting>
 
@@ -322,8 +323,9 @@ product BUFFALO WLI_CF_S11G	0x030b	BUFFALO AirStation 11Mbps CF WLAN</programlis
       <screen>&prompt.root; <userinput>cd src/sys/dev/pccard</userinput>
 &prompt.root; <userinput>make -f Makefile.pccarddevs</userinput></screen>
 
-      <para>Once these steps are complete, the card can be added to the
+      <para>Once these steps are complete, the card can be added to
-	driver.  That is a simple operation of adding one line:</para>
+	the driver.  That is a simple operation of adding one
+	line:</para>
 
       <programlisting>static const struct pccard_product wi_pccard_products[] = {
 	PCMCIA_CARD(3COM, 3CRWE737A, 0),
@@ -338,38 +340,37 @@ product BUFFALO WLI_CF_S11G	0x030b	BUFFALO AirStation 11Mbps CF WLAN</programlis
 	line before the line that I added, but that is simply to
 	highlight the line.  Do not add it to the actual driver.  Once
 	you have added the line, you can recompile your kernel or
-	module and test it.  If the device is recognized
+	module and test it.  If the device is recognized and works,
-	and works, please submit a patch.  If it does not work, please
+	please submit a patch.  If it does not work, please figure out
-	figure out what is needed to make it work and submit a patch.
+	what is needed to make it work and submit a patch.  If the
-	If the device is not recognized at all, you have done something
+	device is not recognized at all, you have done something wrong
-	wrong and should recheck each step.</para>
+	and should recheck each step.</para>
 
       <para>If you are a FreeBSD src committer, and everything appears
 	to be working, then you can commit the changes to the tree.
 	However, there are some minor tricky things to be considered.
-	<filename>pccarddevs</filename> must be committed to the tree first.
+	<filename>pccarddevs</filename> must be committed to the tree
-	Then <filename>pccarddevs.h</filename> must be regenerated
+	first.  Then <filename>pccarddevs.h</filename> must be
-	and committed as a second
+	regenerated and committed as a second step, ensuring that the
-	step, ensuring that the right
+	right &dollar;FreeBSD&dollar; tag is in the latter file.
-	&dollar;FreeBSD&dollar; tag is in the latter file.  Finally,
+	Finally, commit the additions to the driver.</para>
-	commit the additions to the driver.</para>
     </sect2>
 
     <sect2 id="pccard-pr">
       <title>Submitting a New Device</title>
 
       <para>Please do not send entries for new devices to the author
-	directly.  Instead, submit them as a PR
+	directly.  Instead, submit them as a PR and send the author
-	and send the author the PR number for his records.  This
+	the PR number for his records.  This ensures that entries are
-	ensures that entries are not lost.  When submitting a PR, it is
+	not lost.  When submitting a PR, it is unnecessary to include
-	unnecessary to include the <filename>pccardevs.h</filename>
+	the <filename>pccardevs.h</filename> diffs in the patch, since
-	diffs in the patch, since those will be regenerated.  It is
+	those will be regenerated.  It is necessary to include a
-	necessary to include a description of the device, as well as
+	description of the device, as well as the patches to the
-	the patches to the client driver.  If you do not know the
+	client driver.  If you do not know the name, use OEM99 as the
-	name, use OEM99 as the name, and the author will adjust OEM99
+	name, and the author will adjust OEM99 accordingly after
-	accordingly after investigation.  Committers should not commit
+	investigation.  Committers should not commit OEM99, but
-	OEM99, but instead find the highest OEM entry and commit one
+	instead find the highest OEM entry and commit one more than
-	more than that.</para>
+	that.</para>
     </sect2>
   </sect1>
 </chapter>