Skip site navigation (1)Skip section navigation (2)
Date:      Mon, 21 Apr 2014 15:54:17 +0000 (UTC)
From:      Dru Lavigne <dru@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r44614 - head/en_US.ISO8859-1/books/handbook/multimedia
Message-ID:  <201404211554.s3LFsH42002420@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: dru
Date: Mon Apr 21 15:54:17 2014
New Revision: 44614
URL: http://svnweb.freebsd.org/changeset/doc/44614

Log:
  Editorial review of Scanners chapter.
  
  Sponsored by:	iXsystems

Modified:
  head/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml	Mon Apr 21 12:24:37 2014	(r44613)
+++ head/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml	Mon Apr 21 15:54:17 2014	(r44614)
@@ -5,19 +5,19 @@
      $FreeBSD$
 -->
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="multimedia">
-  <!--
-  <chapterinfo>
+
+  <info>
+    <title>Multimedia</title>
     <authorgroup>
       <author>
+      <personname>
 	<firstname>Ross</firstname>
 	<surname>Lippert</surname>
+	</personname>
 	<contrib>Edited by </contrib>
       </author>
     </authorgroup>
-  </chapterinfo>
-  -->
-
-  <title>Multimedia</title>
+  </info>
 
   <sect1 xml:id="multimedia-synopsis">
     <title>Synopsis</title>
@@ -92,26 +92,28 @@
   </sect1>
 
   <sect1 xml:id="sound-setup">
-    <!--
-    <sect1info>
+    <info>
+    <title>Setting Up the Sound Card</title>
+
       <authorgroup>
 	<author>
+	<personname>
 	  <firstname>Moses</firstname>
 	  <surname>Moore</surname>
-	  <contrib>Contributed by in November 2000</contrib>
+	</personname>
+	<contrib>Contributed by </contrib> <!-- in November 2000-->
 	</author>
       </authorgroup>
       <authorgroup>
 	<author>
+	<personname>
 	  <firstname>Marc</firstname>
 	  <surname>Fonvieille</surname>
-	  <contrib>Enhanced by in September 2004</contrib>
+	  </personname>
+	  <contrib>Enhanced by </contrib> <!--in September 2004-->
 	</author>
       </authorgroup>
-    </sect1info>
-    -->
-
-    <title>Setting Up the Sound Card</title>
+    </info>
 
     <indexterm><primary>PCI</primary></indexterm>
     <indexterm><primary>sound cards</primary></indexterm>
@@ -385,18 +387,19 @@ pcm7: &lt;HDA Realtek ALC889 PCM #3 Digi
   </sect2>
 
   <sect2 xml:id="sound-multiple-sources">
-    <!--
-    <sect2info>
+    <info>
+    <title>Utilizing Multiple Sound Sources</title>
+
       <authorgroup>
 	<author>
+	<personname>
 	  <firstname>Munish</firstname>
 	  <surname>Chopra</surname>
+	  </personname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
-    </sect2info>
-    -->
-    <title>Utilizing Multiple Sound Sources</title>
+    </info>
 
     <para>It is often desirable to have multiple sources of sound that
       are able to play simultaneously.  &os; uses <quote>Virtual
@@ -435,19 +438,20 @@ pcm7: &lt;HDA Realtek ALC889 PCM #3 Digi
   </sect2>
 
   <sect2>
-        <!--
-    <sect2info>
+    <info>
+    <title>Setting Default Values for Mixer Channels</title>
+
       <authorgroup>
 	<author>
+	<personname>
 	  <firstname>Josef</firstname>
 	  <surname>El-Rayes</surname>
+	</personname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
-    </sect2info>
-    -->
+    </info>
 
-    <title>Setting Default Values for Mixer Channels</title>
 
     <para>The default values for the different mixer channels are
       hardcoded in the source code of the &man.pcm.4; driver.  While
@@ -467,19 +471,19 @@ pcm7: &lt;HDA Realtek ALC889 PCM #3 Digi
 </sect1>
 
 <sect1 xml:id="sound-mp3">
-  <!--
-  <sect1info>
+  <info>
+    <title>MP3 Audio</title>
+
     <authorgroup>
       <author>
+      <personname>
 	<firstname>Chern</firstname>
 	<surname>Lee</surname>
-	<contrib>Contributed by in Sept 2001</contrib>
+      </personname>
+      <contrib>Contributed by </contrib> <!--in Sept 2001-->
       </author>
     </authorgroup>
-  </sect1info>
-  -->
-
-    <title>MP3 Audio</title>
+  </info>
 
     <para>This section describes some <acronym>MP3</acronym>
       players available for &os;, how to rip audio CD tracks, and
@@ -554,13 +558,13 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz
       <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -B</userinput></screen>
 
       <para>The <option>-D <replaceable>0,1,0</replaceable></option>
-	indicates the SCSI device <filename>0,1,0</filename>,
+	indicates the <acronym>SCSI</acronym> device <filename>0,1,0</filename>,
 	which corresponds to the output of <command>cdrecord
 	  -scanbus</command>.</para>
 
       <para><application>cdda2wav</application> will support ATAPI
 	(IDE) CDROM drives.  To rip from an IDE drive, specify the
-	device name in place of the SCSI unit numbers.  For example,
+	device name in place of the <acronym>SCSI</acronym> unit numbers.  For example,
 	to rip track 7 from an IDE drive:</para>
 
       <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>/dev/acd0</replaceable> -t 7</userinput></screen>
@@ -711,19 +715,20 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz
   </sect1>
 
   <sect1 xml:id="video-playback">
-    <!--
-    <sect1info>
+    <info>
+    <title>Video Playback</title>
+
       <authorgroup>
 	<author>
+	<personname>
 	  <firstname>Ross</firstname>
 	  <surname>Lippert</surname>
-	  <contrib>Contributed by in June 2002</contrib>
+	  </personname>
+	  <contrib>Contributed by </contrib> <!--in June 2002-->
 	</author>
       </authorgroup>
-    </sect1info>
-    -->
+    </info>
 
-    <title>Video Playback</title>
 
     <para>Before configuring video playback, determine the model and
       chipset of the video card.  While
@@ -1158,26 +1163,28 @@ zoom=yes</programlisting>
 </sect1>
 
 <sect1 xml:id="tvcard">
-  <!--
-  <sect1info>
+  <info>
+    <title>TV Cards</title>
+
     <authorgroup>
       <author>
+      <personname>
 	<firstname>Josef</firstname>
 	<surname>El-Rayes</surname>
+      </personname>
 	<contrib>Original contribution by </contrib>
       </author>
     </authorgroup>
     <authorgroup>
       <author>
+      <personname>
 	<firstname>Marc</firstname>
 	<surname>Fonvieille</surname>
-	<contrib>Enhanced and adapted by in January 2004</contrib>
+      </personname>
+      <contrib>Enhanced and adapted by </contrib> <!-- in January 2004-->
       </author>
     </authorgroup>
-  </sect1info>
-  -->
-
-  <title>TV Cards</title>
+  </info>
 
   <indexterm>
     <primary>TV cards</primary>
@@ -1359,49 +1366,51 @@ bktr0: Pinnacle/Miro TV, Philips SECAM t
   </sect1>
 
   <sect1 xml:id="scanners">
-    <!--
-    <sect1info>
+    <info>
+    <title>Image Scanners</title>
+
       <authorgroup>
 	<author>
+	<personname>
 	  <firstname>Marc</firstname>
 	  <surname>Fonvieille</surname>
-	  <contrib>Written by in August 2004</contrib>
+	  </personname>
+	  <contrib>Written by </contrib> <!-- in August 2004-->
 	</author>
       </authorgroup>
-    </sect1info>
-    -->
-
-    <title>Image Scanners</title>
+    </info>
 
     <indexterm>
       <primary>image scanners</primary>
     </indexterm>
 
-    <para>In &os;, access to image scanners is provided by the
-      <application>SANE</application> (Scanner Access Now Easy)
-      <acronym role="Application Programming       Interface">API</acronym> available through the &os; Ports
-      Collection.  <application>SANE</application> will also use
+    <para>In &os;, access to image scanners is provided by
+      <application>SANE</application> (Scanner Access Now Easy), which
+      is available in the &os; Ports Collection.
+      <application>SANE</application> will also use
       some &os; device drivers to provide access to the scanner
       hardware.</para>
 
-    <para>&os; supports both SCSI and USB scanners.  Be sure the
+    <para>&os; supports both <acronym>SCSI</acronym> and
+      <acronym>USB</acronym> scanners.  Depending
+      upon the scanner interface, different device drivers are
+      required.  Be sure the
       scanner is supported by <application>SANE</application> prior
-      to performing any configuration.  Refer to the <link xlink:href="http://www.sane-project.org/sane-supported-devices.html">;
-      supported devices list</link> for more information about
+      to performing any configuration.  Refer to <link xlink:href="http://www.sane-project.org/sane-supported-devices.html">;
+      http://www.sane-project.org/sane-supported-devices.html</link>;
+      for more information about
       supported scanners.</para>
 
-    <sect2>
-      <title>Kernel Configuration</title>
-
-      <para>Both SCSI and USB interfaces are supported.  Depending
-	upon the scanner interface, different device drivers are
-	required.</para>
+    <para>This chapter describes how to determine if the scanner has
+      been detected by &os;.  It then provides an overview of how to
+      configure and use <application>SANE</application> on a &os;
+      system.</para>
 
-      <sect3 xml:id="scanners-kernel-usb">
-	<title>USB Interface</title>
+      <sect2 xml:id="scanners-kernel-usb">
+	<title>Checking the Scanner</title>
 
-	<para>The <filename>GENERIC</filename> kernel by default
-	  includes the device drivers needed to support USB scanners.
+	<para>The <filename>GENERIC</filename> kernel
+	  includes the device drivers needed to support <acronym>USB</acronym> scanners.
 	  Users with a custom kernel should ensure that the following
 	  lines are present in the custom kernel configuration
 	  file:</para>
@@ -1411,31 +1420,27 @@ device uhci
 device ohci
 device ehci</programlisting>
 
-	<para>Plug in the USB scanner.  Use &man.dmesg.8; to determine
+	<para>To determine if the <acronym>USB</acronym> scanner is
+	  detected, plug it in and use <command>dmesg</command> to determine
 	  whether the scanner appears in the system message
-	  buffer:</para>
+	  buffer.  If it does, it should display a message similar to
+	  this:</para>
 
 	<screen>ugen0.2: &lt;EPSON&gt; at usbus0</screen>
 
-	<para>These messages indicate that the scanner is using
-	  either <filename>/dev/ugen0.2</filename> or
-	  <filename>/dev/uscanner0</filename>, depending on the &os;
-	  version.  For this example, a
-	  &epson.perfection;&nbsp;1650 USB scanner was used.</para>
-      </sect3>
-
-      <sect3>
-	<title>SCSI Interface</title>
-
-	<para>If the scanner uses a SCSI interface, it is important to
-	  know which SCSI controller board it will use.  Depending
-	  upon the SCSI chipset, a custom kernel configuration file
+	<para>In this example, an &epson.perfection;&nbsp;1650
+	  <acronym>USB</acronym> scanner was detected on
+	  <filename>/dev/ugen0.2</filename>.</para>
+
+	<para>If the scanner uses a <acronym>SCSI</acronym> interface, it is important to
+	  know which <acronym>SCSI</acronym> controller board it will use.  Depending
+	  upon the <acronym>SCSI</acronym> chipset, a custom kernel configuration file
 	  may be needed.  The <filename>GENERIC</filename> kernel
-	  supports the most common SCSI controllers.  Refer to
+	  supports the most common <acronym>SCSI</acronym> controllers.  Refer to
 	  <filename>/usr/src/sys/conf/NOTES</filename> to determine
 	  the correct line to add to a custom kernel configuration
-	  file.  In addition to the SCSI adapter driver, the following
-	  lines are needed in the kernel configuration file:</para>
+	  file.  In addition to the <acronym>SCSI</acronym> adapter driver, the following
+	  lines are needed in a custom kernel configuration file:</para>
 
 	<programlisting>device scbus
 device pass</programlisting>
@@ -1448,9 +1453,9 @@ pass2: &lt;AGFA SNAPSCAN 600 1.10&gt; Fi
 pass2: 3.300MB/s transfers</screen>
 
 	<para>If the scanner was not powered-on at system boot, it
-	  is still possible to manually force the detection by
-	  performing a SCSI bus scan with the &man.camcontrol.8;
-	  command:</para>
+	  is still possible to manually force detection by
+	  performing a <acronym>SCSI</acronym> bus scan with
+	  <command>camcontrol</command>:</para>
 
 	<screen>&prompt.root; <userinput>camcontrol rescan all</userinput>
 Re-scan of bus 0 was successful
@@ -1458,7 +1463,7 @@ Re-scan of bus 1 was successful
 Re-scan of bus 2 was successful
 Re-scan of bus 3 was successful</screen>
 
-	<para>The scanner should now appear in the SCSI devices
+	<para>The scanner should now appear in the <acronym>SCSI</acronym> devices
 	  list:</para>
 
 	<screen>&prompt.root; <userinput>camcontrol devlist</userinput>
@@ -1468,22 +1473,24 @@ Re-scan of bus 3 was successful</screen>
 &lt;PHILIPS CDD3610 CD-R/RW 1.00&gt;     at scbus2 target 0 lun 0 (pass2,cd0)</screen>
 
 	<para>Refer to &man.scsi.4; and &man.camcontrol.8; for more
-	  details about SCSI devices on &os;.</para>
-      </sect3>
+	  details about <acronym>SCSI</acronym> devices on &os;.</para>
     </sect2>
 
     <sect2>
-      <title>SANE Configuration</title>
+      <title><application>SANE</application> Configuration</title>
 
       <para>The <application>SANE</application> system is split in two
 	parts: the backends (<package>graphics/sane-backends</package>) and the
-	frontends (<package>graphics/sane-frontends</package>).  The
-	backends provide access to the scanner.  The
-	<application>SANE</application>'s <link xlink:href="http://www.sane-project.org/sane-supported-devices.html">supported
-	devices</link> list specifies which backend will support the
-	image scanner.  The correct backend is needed in order to use
-	the scanner.  The frontends provide the graphical scanning
-	interface, <application>xscanimage</application>.</para>
+	frontends (<package>graphics/sane-frontends</package> or
+	<package>graphics/xsane</package>).  The
+	backends provide access to the scanner.  Refer to
+	<link xlink:href="http://www.sane-project.org/sane-supported-devices.html">http://www.sane-project.org/sane-supported-devices.html</link>;
+	to determine which backend supports the
+	scanner.  The frontends provide the graphical scanning
+	interface.   <package>graphics/sane-frontends</package>
+	installs <application>xscanimage</application> while
+	<package>graphics/xsane</package> installs
+	<application>xsane</application>.</para>
 
       <para>After installing the <package>graphics/sane-backends</package> port or
 	package, use <command>sane-find-scanner</command> to check the
@@ -1498,44 +1505,33 @@ found SCSI scanner "AGFA SNAPSCAN 600 1.
 	The vendor and the product model may or may not appear.</para>
 
       <note>
-	<para>Some USB scanners require firmware to be loaded.  Refer
-	  to &man.sane-find-scanner.1; and &man.sane.7; for
+	<para>Some <acronym>USB</acronym> scanners require firmware to be loaded.  Refer
+	  to sane-find-scanner(1) and sane(7) for
 	  details.</para>
       </note>
 
       <para>Next, check if the scanner will be identified by a
-	scanning frontend.  By default, the
-	<application>SANE</application> backends come with a command
-	line tool called &man.scanimage.1;.  This command can be used
+	scanning frontend.  The
+	<application>SANE</application> backends include
+	<command>scanimage</command> which can be used
 	to list the devices and perform an image acquisition.  Use
-	<option>-L</option> to list the scanner devices:</para>
-
-      <screen>&prompt.root; <userinput>scanimage -L</userinput>
-device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner</screen>
-
-      <para>Here is the output for the USB scanner used in <xref linkend="scanners-kernel-usb"/>:</para>
+	<option>-L</option> to list the scanner devices.  The first
+	example is for a <acronym>SCSI</acronym> scanner and the
+	second is for a <acronym>USB</acronym> scanner:</para>
 
       <screen>&prompt.root; <userinput>scanimage -L</userinput>
+device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner
+&prompt.root; <userinput>scanimage -L</userinput>
 device 'epson2:libusb:/dev/usb:/dev/ugen0.2' is a Epson GT-8200 flatbed scanner</screen>
 
-      <para>In this output,
+      <para>In this second example,
 	<literal>'epson2:libusb:/dev/usb:/dev/ugen0.2'</literal> is
-	the backend name (<literal>epson2</literal>) and the device
-	node (<literal>/dev/ugen0.2</literal>) used by the
+	the backend name (<literal>epson2</literal>) and
+	<literal>/dev/ugen0.2</literal> is the device node used by the
 	scanner.</para>
 
-      <note>
-	<para>No output or a message saying that no scanners were
-	  identified indicates that &man.scanimage.1; is unable to
-	  identify the scanner.  If this happens, edit the backend
-	  configuration file in <filename>/usr/local/etc/sane.d/</filename>
-	  and define the scanner device used.</para>
-
-	<para>In the above example, the USB scanner is perfectly
-	  detected and working.</para>
-
-	<para>To determine if the scanner is correctly
-	  identified:</para>
+	<para>If <command>scanimage</command> is unable to
+	  identify the scanner, this message will appear:</para>
 
 	<screen>&prompt.root; <userinput>scanimage -L</userinput>
 
@@ -1544,44 +1540,36 @@ check that the scanner is plugged in, tu
 sane-find-scanner tool (if appropriate). Please read the documentation
 which came with this software (README, FAQ, manpages).</screen>
 
-      <para>Since the scanner is not identified, edit
-	<filename>/usr/local/etc/sane.d/epson2.conf</filename>.  In
-	this example, the scanner model is
-	&epson.perfection;&nbsp;1650 and it uses the
-	<literal>epson2</literal> backend.  When editing, read the
-	help comments in the backend configuration file.  Line
-	changes are simple: comment out all lines that have the
-	wrong interface for the scanner.  In this example, comment
-	out all lines starting with the word <literal>scsi</literal>
-	as the scanner uses the USB interface.  Then, at the end
-	of the file, add a line specifying the interface and the
+      <para>If this happens, edit the backend
+	configuration file in <filename>/usr/local/etc/sane.d/</filename>
+	and define the scanner device used.  For example, if the undetected scanner model is
+	an &epson.perfection;&nbsp;1650 and it uses the
+	<literal>epson2</literal> backend, edit
+	<filename>/usr/local/etc/sane.d/epson2.conf</filename>.
+	When editing, add a line specifying the interface and the
 	device node used.  In this case, add the following
 	line:</para>
 
-      <programlisting>usb /dev/uscanner0</programlisting>
+      <programlisting>usb /dev/ugen0.2</programlisting>
 
       <para>Save the edits and verify that the scanner is
-	identified:</para>
+	identified with the right backend name and the device node:</para>
 
       <screen>&prompt.root; <userinput>scanimage -L</userinput>
-device `epson:/dev/uscanner0' is a Epson GT-8200 flatbed scanner</screen>
-
-      <para>The <literal>`epson:/dev/uscanner0'</literal> field now
-	gives the right backend name and the device node.</para>
-    </note>
+device 'epson2:libusb:/dev/usb:/dev/ugen0.2' is a Epson GT-8200 flatbed scanner</screen>
 
     <para>Once <command>scanimage -L</command> sees the scanner, the
-      configuration is complete and the device is now ready to
-      scan.</para>
+      configuration is complete and the scanner is now ready to
+      use.</para>
 
-    <para>While &man.scanimage.1; can be used to perform an image
+    <para>While <command>scanimage</command> can be used to perform an image
       acquisition from the command line, it is often preferable to
       use a graphical interface to perform image scanning.  The
       <package>graphics/sane-frontends</package>
       package or port installs a simple but efficient graphical
       interface, <application>xscanimage</application>.</para>
 
-    <para><application>Xsane</application>, which is installed with
+    <para>Alternately, <application>xsane</application>, which is installed with
       the <package>graphics/xsane</package> package
       or port, is another popular graphical scanning frontend.  It
       offers advanced features such as various scanning modes, color
@@ -1590,34 +1578,33 @@ device `epson:/dev/uscanner0' is a Epson
   </sect2>
 
   <sect2>
-    <title>Giving Other Users Access to the Scanner</title>
+    <title>Scanner Permissions</title>
 
     <para>In order to have access to the scanner, a user needs
       read and write permissions to the device node used by the
-      scanner.  In the previous example, the USB scanner uses the
+      scanner.  In the previous example, the <acronym>USB</acronym> scanner uses the
       device node <filename>/dev/ugen0.2</filename> which is really a
       symlink to the real device node
       <filename>/dev/usb/0.2.0</filename>.  The symlink and the device
       node are owned, respectively, by the
       <systemitem class="groupname">wheel</systemitem> and
-      <systemitem class="groupname">operator</systemitem> groups.  Adding the user to
-      these groups will allow access to the scanner.  However, for
-      security reasons, always think twice before adding a user
-      to any group, especially <systemitem class="groupname">wheel</systemitem>.  A better
-      solution is to create a group to make the scanner device
+      <systemitem class="groupname">operator</systemitem> groups.  While adding the user to
+      these groups will allow access to the scanner, it is considered insecure to
+      add a user
+      to <systemitem class="groupname">wheel</systemitem>.  A better
+      solution is to create a group and make the scanner device
       accessible to members of this group.</para>
 
     <para>This example creates a group called
-      <systemitem class="groupname"><replaceable>usb</replaceable></systemitem> using
-      &man.pw.8;:</para>
+      <systemitem class="groupname"><replaceable>usb</replaceable></systemitem>:</para>
 
     <screen>&prompt.root; <userinput>pw groupadd usb</userinput></screen>
 
       <para>Then, make the <filename>/dev/ugen0.2</filename> symlink
 	and the <filename>/dev/usb/0.2.0</filename> device node
 	accessible to the <systemitem class="groupname">usb</systemitem> group with write
-	permissions of (<literal>0660</literal> or
-	<literal>0664</literal>.  All of this is done by adding the
+	permissions of <literal>0660</literal> or
+	<literal>0664</literal> by adding the
 	following lines to
 	<filename>/etc/devfs.rules</filename>:</para>
 



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404211554.s3LFsH42002420>