rbcdio 0.02 → 0.03

data/install-sh

@@ -1,7 +1,7 @@
 #!/bin/sh
 # install - install a program, script, or datafile
 
-scriptversion=2006-10-14.15
+scriptversion=2005-05-14.22
 
 # This originates from X11R5 (mit/util/scripts/install.sh), which was
 # later released in X11R6 (xc/config/util/install.sh) with the
@@ -39,24 +39,15 @@ scriptversion=2006-10-14.15
 # when there is no Makefile.
 #
 # This script is compatible with the BSD install script, but was written
-# from scratch.
-
-nl='
-'
-IFS=" ""	$nl"
+# from scratch.  It can only install one file at a time, a restriction
+# shared with many OS's install programs.
 
 # set DOITPROG to echo to test this script
 
 # Don't use :- since 4.3BSD and earlier shells don't like it.
 doit="${DOITPROG-}"
-if test -z "$doit"; then
-  doit_exec=exec
-else
-  doit_exec=$doit
-fi
 
-# Put in absolute file names if you don't have them in your path;
-# or use environment vars.
+# put in absolute paths if you don't have them in your path; or use env. vars.
 
 mvprog="${MVPROG-mv}"
 cpprog="${CPPROG-cp}"
@@ -67,13 +58,7 @@ stripprog="${STRIPPROG-strip}"
 rmprog="${RMPROG-rm}"
 mkdirprog="${MKDIRPROG-mkdir}"
 
-posix_glob=
-posix_mkdir=
-
-# Desired mode of installed file.
-mode=0755
-
-chmodcmd=$chmodprog
+chmodcmd="$chmodprog 0755"
 chowncmd=
 chgrpcmd=
 stripcmd=
@@ -110,7 +95,7 @@ Environment variables override the default commands:
   CHGRPPROG CHMODPROG CHOWNPROG CPPROG MKDIRPROG MVPROG RMPROG STRIPPROG
 "
 
-while test $# -ne 0; do
+while test -n "$1"; do
   case $1 in
     -c) shift
         continue;;
@@ -126,15 +111,9 @@ while test $# -ne 0; do
 
     --help) echo "$usage"; exit $?;;
 
-    -m) mode=$2
+    -m) chmodcmd="$chmodprog $2"
         shift
         shift
-	case $mode in
-	  *' '* | *'	'* | *'
-'*	  | *'*'* | *'?'* | *'['*)
-	    echo "$0: invalid mode: $mode" >&2
-	    exit 1;;
-	esac
         continue;;
 
     -o) chowncmd="$chownprog $2"
@@ -157,33 +136,25 @@ while test $# -ne 0; do
 
     --version) echo "$0 $scriptversion"; exit $?;;
 
-    --)	shift
+    *)  # When -d is used, all remaining arguments are directories to create.
+	# When -t is used, the destination is already specified.
+	test -n "$dir_arg$dstarg" && break
+        # Otherwise, the last argument is the destination.  Remove it from $@.
+	for arg
+	do
+          if test -n "$dstarg"; then
+	    # $@ is not empty: it contains at least $arg.
+	    set fnord "$@" "$dstarg"
+	    shift # fnord
+	  fi
+	  shift # arg
+	  dstarg=$arg
+	done
 	break;;
-
-    -*)	echo "$0: invalid option: $1" >&2
-	exit 1;;
-
-    *)  break;;
   esac
 done
 
-if test $# -ne 0 && test -z "$dir_arg$dstarg"; then
-  # When -d is used, all remaining arguments are directories to create.
-  # When -t is used, the destination is already specified.
-  # Otherwise, the last argument is the destination.  Remove it from $@.
-  for arg
-  do
-    if test -n "$dstarg"; then
-      # $@ is not empty: it contains at least $arg.
-      set fnord "$@" "$dstarg"
-      shift # fnord
-    fi
-    shift # arg
-    dstarg=$arg
-  done
-fi
-
-if test $# -eq 0; then
+if test -z "$1"; then
   if test -z "$dir_arg"; then
     echo "$0: no input file specified." >&2
     exit 1
@@ -193,33 +164,6 @@ if test $# -eq 0; then
   exit 0
 fi
 
-if test -z "$dir_arg"; then
-  trap '(exit $?); exit' 1 2 13 15
-
-  # Set umask so as not to create temps with too-generous modes.
-  # However, 'strip' requires both read and write access to temps.
-  case $mode in
-    # Optimize common cases.
-    *644) cp_umask=133;;
-    *755) cp_umask=22;;
-
-    *[0-7])
-      if test -z "$stripcmd"; then
-	u_plus_rw=
-      else
-	u_plus_rw='% 200'
-      fi
-      cp_umask=`expr '(' 777 - $mode % 1000 ')' $u_plus_rw`;;
-    *)
-      if test -z "$stripcmd"; then
-	u_plus_rw=
-      else
-	u_plus_rw=,u+rw
-      fi
-      cp_umask=$mode$u_plus_rw;;
-  esac
-fi
-
 for src
 do
   # Protect names starting with `-'.
@@ -229,11 +173,15 @@ do
 
   if test -n "$dir_arg"; then
     dst=$src
-    dstdir=$dst
-    test -d "$dstdir"
-    dstdir_status=$?
-  else
+    src=
 
+    if test -d "$dst"; then
+      mkdircmd=:
+      chmodcmd=
+    else
+      mkdircmd=$mkdirprog
+    fi
+  else
     # Waiting for this to be detected by the "$cpprog $src $dsttmp" command
     # might cause directories to be created, which would be especially bad
     # if $src (and thus $dsttmp) contains '*'.
@@ -260,188 +208,53 @@ do
 	echo "$0: $dstarg: Is a directory" >&2
 	exit 1
       fi
-      dstdir=$dst
-      dst=$dstdir/`basename "$src"`
-      dstdir_status=0
-    else
-      # Prefer dirname, but fall back on a substitute if dirname fails.
-      dstdir=`
-	(dirname "$dst") 2>/dev/null ||
-	expr X"$dst" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \
-	     X"$dst" : 'X\(//\)[^/]' \| \
-	     X"$dst" : 'X\(//\)$' \| \
-	     X"$dst" : 'X\(/\)' \| . 2>/dev/null ||
-	echo X"$dst" |
-	    sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{
-		   s//\1/
-		   q
-		 }
-		 /^X\(\/\/\)[^/].*/{
-		   s//\1/
-		   q
-		 }
-		 /^X\(\/\/\)$/{
-		   s//\1/
-		   q
-		 }
-		 /^X\(\/\).*/{
-		   s//\1/
-		   q
-		 }
-		 s/.*/./; q'
-      `
-
-      test -d "$dstdir"
-      dstdir_status=$?
+      dst=$dst/`basename "$src"`
     fi
   fi
 
-  obsolete_mkdir_used=false
-
-  if test $dstdir_status != 0; then
-    case $posix_mkdir in
-      '')
-	# Create intermediate dirs using mode 755 as modified by the umask.
-	# This is like FreeBSD 'install' as of 1997-10-28.
-	umask=`umask`
-	case $stripcmd.$umask in
-	  # Optimize common cases.
-	  *[2367][2367]) mkdir_umask=$umask;;
-	  .*0[02][02] | .[02][02] | .[02]) mkdir_umask=22;;
-
-	  *[0-7])
-	    mkdir_umask=`expr $umask + 22 \
-	      - $umask % 100 % 40 + $umask % 20 \
-	      - $umask % 10 % 4 + $umask % 2
-	    `;;
-	  *) mkdir_umask=$umask,go-w;;
-	esac
-
-	# With -d, create the new directory with the user-specified mode.
-	# Otherwise, rely on $mkdir_umask.
-	if test -n "$dir_arg"; then
-	  mkdir_mode=-m$mode
-	else
-	  mkdir_mode=
-	fi
-
-	posix_mkdir=false
-	case $umask in
-	  *[123567][0-7][0-7])
-	    # POSIX mkdir -p sets u+wx bits regardless of umask, which
-	    # is incompatible with FreeBSD 'install' when (umask & 300) != 0.
-	    ;;
-	  *)
-	    tmpdir=${TMPDIR-/tmp}/ins$RANDOM-$$
-	    trap 'ret=$?; rmdir "$tmpdir/d" "$tmpdir" 2>/dev/null; exit $ret' 0
-
-	    if (umask $mkdir_umask &&
-		exec $mkdirprog $mkdir_mode -p -- "$tmpdir/d") >/dev/null 2>&1
-	    then
-	      if test -z "$dir_arg" || {
-		   # Check for POSIX incompatibilities with -m.
-		   # HP-UX 11.23 and IRIX 6.5 mkdir -m -p sets group- or
-		   # other-writeable bit of parent directory when it shouldn't.
-		   # FreeBSD 6.1 mkdir -m -p sets mode of existing directory.
-		   ls_ld_tmpdir=`ls -ld "$tmpdir"`
-		   case $ls_ld_tmpdir in
-		     d????-?r-*) different_mode=700;;
-		     d????-?--*) different_mode=755;;
-		     *) false;;
-		   esac &&
-		   $mkdirprog -m$different_mode -p -- "$tmpdir" && {
-		     ls_ld_tmpdir_1=`ls -ld "$tmpdir"`
-		     test "$ls_ld_tmpdir" = "$ls_ld_tmpdir_1"
-		   }
-		 }
-	      then posix_mkdir=:
-	      fi
-	      rmdir "$tmpdir/d" "$tmpdir"
-	    else
-	      # Remove any dirs left behind by ancient mkdir implementations.
-	      rmdir ./$mkdir_mode ./-p ./-- 2>/dev/null
-	    fi
-	    trap '' 0;;
-	esac;;
-    esac
+  # This sed command emulates the dirname command.
+  dstdir=`echo "$dst" | sed -e 's,/*$,,;s,[^/]*$,,;s,/*$,,;s,^$,.,'`
 
-    if
-      $posix_mkdir && (
-	umask $mkdir_umask &&
-	$doit_exec $mkdirprog $mkdir_mode -p -- "$dstdir"
-      )
-    then :
-    else
+  # Make sure that the destination directory exists.
+
+  # Skip lots of stat calls in the usual case.
+  if test ! -d "$dstdir"; then
+    defaultIFS='
+	 '
+    IFS="${IFS-$defaultIFS}"
 
-      # The umask is ridiculous, or mkdir does not conform to POSIX,
-      # or it failed possibly due to a race condition.  Create the
-      # directory the slow way, step by step, checking for races as we go.
-
-      case $dstdir in
-	/*) prefix=/ ;;
-	-*) prefix=./ ;;
-	*)  prefix= ;;
-      esac
-
-      case $posix_glob in
-        '')
-	  if (set -f) 2>/dev/null; then
-	    posix_glob=true
-	  else
-	    posix_glob=false
-	  fi ;;
-      esac
-
-      oIFS=$IFS
-      IFS=/
-      $posix_glob && set -f
-      set fnord $dstdir
+    oIFS=$IFS
+    # Some sh's can't handle IFS=/ for some reason.
+    IFS='%'
+    set x `echo "$dstdir" | sed -e 's@/@%@g' -e 's@^%@/@'`
+    shift
+    IFS=$oIFS
+
+    pathcomp=
+
+    while test $# -ne 0 ; do
+      pathcomp=$pathcomp$1
       shift
-      $posix_glob && set +f
-      IFS=$oIFS
-
-      prefixes=
-
-      for d
-      do
-	test -z "$d" && continue
-
-	prefix=$prefix$d
-	if test -d "$prefix"; then
-	  prefixes=
-	else
-	  if $posix_mkdir; then
-	    (umask=$mkdir_umask &&
-	     $doit_exec $mkdirprog $mkdir_mode -p -- "$dstdir") && break
-	    # Don't fail if two instances are running concurrently.
-	    test -d "$prefix" || exit 1
-	  else
-	    case $prefix in
-	      *\'*) qprefix=`echo "$prefix" | sed "s/'/'\\\\\\\\''/g"`;;
-	      *) qprefix=$prefix;;
-	    esac
-	    prefixes="$prefixes '$qprefix'"
-	  fi
-	fi
-	prefix=$prefix/
-      done
-
-      if test -n "$prefixes"; then
-	# Don't fail if two instances are running concurrently.
-	(umask $mkdir_umask &&
-	 eval "\$doit_exec \$mkdirprog $prefixes") ||
-	  test -d "$dstdir" || exit 1
-	obsolete_mkdir_used=true
+      if test ! -d "$pathcomp"; then
+        $mkdirprog "$pathcomp"
+	# mkdir can fail with a `File exist' error in case several
+	# install-sh are creating the directory concurrently.  This
+	# is OK.
+	test -d "$pathcomp" || exit
       fi
-    fi
+      pathcomp=$pathcomp/
+    done
   fi
 
   if test -n "$dir_arg"; then
-    { test -z "$chowncmd" || $doit $chowncmd "$dst"; } &&
-    { test -z "$chgrpcmd" || $doit $chgrpcmd "$dst"; } &&
-    { test "$obsolete_mkdir_used$chowncmd$chgrpcmd" = false ||
-      test -z "$chmodcmd" || $doit $chmodcmd $mode "$dst"; } || exit 1
+    $doit $mkdircmd "$dst" \
+      && { test -z "$chowncmd" || $doit $chowncmd "$dst"; } \
+      && { test -z "$chgrpcmd" || $doit $chgrpcmd "$dst"; } \
+      && { test -z "$stripcmd" || $doit $stripcmd "$dst"; } \
+      && { test -z "$chmodcmd" || $doit $chmodcmd "$dst"; }
+
   else
+    dstfile=`basename "$dst"`
 
     # Make a couple of temp file names in the proper directory.
     dsttmp=$dstdir/_inst.$$_
@@ -449,9 +262,10 @@ do
 
     # Trap to clean up those temp files at exit.
     trap 'ret=$?; rm -f "$dsttmp" "$rmtmp" && exit $ret' 0
+    trap '(exit $?); exit' 1 2 13 15
 
     # Copy the file name to the temp name.
-    (umask $cp_umask && $doit_exec $cpprog "$src" "$dsttmp") &&
+    $doit $cpprog "$src" "$dsttmp" &&
 
     # and set any options; do chmod last to preserve setuid bits.
     #
@@ -462,10 +276,10 @@ do
     { test -z "$chowncmd" || $doit $chowncmd "$dsttmp"; } \
       && { test -z "$chgrpcmd" || $doit $chgrpcmd "$dsttmp"; } \
       && { test -z "$stripcmd" || $doit $stripcmd "$dsttmp"; } \
-      && { test -z "$chmodcmd" || $doit $chmodcmd $mode "$dsttmp"; } &&
+      && { test -z "$chmodcmd" || $doit $chmodcmd "$dsttmp"; } &&
 
     # Now rename the file to the real destination.
-    { $doit $mvcmd -f "$dsttmp" "$dst" 2>/dev/null \
+    { $doit $mvcmd -f "$dsttmp" "$dstdir/$dstfile" 2>/dev/null \
       || {
 	   # The rename failed, perhaps because mv can't rename something else
 	   # to itself, or perhaps because mv is so ancient that it does not
@@ -477,12 +291,11 @@ do
 	   # reasons.  In this case, the final cleanup might fail but the new
 	   # file should still install successfully.
 	   {
-	     if test -f "$dst"; then
-	       $doit $rmcmd -f "$dst" 2>/dev/null \
-	       || { $doit $mvcmd -f "$dst" "$rmtmp" 2>/dev/null \
-		     && { $doit $rmcmd -f "$rmtmp" 2>/dev/null; :; }; }\
+	     if test -f "$dstdir/$dstfile"; then
+	       $doit $rmcmd -f "$dstdir/$dstfile" 2>/dev/null \
+	       || $doit $mvcmd -f "$dstdir/$dstfile" "$rmtmp" 2>/dev/null \
 	       || {
-		 echo "$0: cannot unlink or rename $dst" >&2
+		 echo "$0: cannot unlink or rename $dstdir/$dstfile" >&2
 		 (exit 1); exit 1
 	       }
 	     else
@@ -491,14 +304,17 @@ do
 	   } &&
 
 	   # Now rename the file to the real destination.
-	   $doit $mvcmd "$dsttmp" "$dst"
+	   $doit $mvcmd "$dsttmp" "$dstdir/$dstfile"
 	 }
-    } || exit 1
-
-    trap '' 0
-  fi
+    }
+  fi || { (exit 1); exit 1; }
 done
 
+# The final little trick to "correctly" pass the exit status to the exit trap.
+{
+  (exit 0); exit 0
+}
+
 # Local variables:
 # eval: (add-hook 'write-file-hooks 'time-stamp)
 # time-stamp-start: "scriptversion="

data/lib/cdio.rb

@@ -1,23 +1,21 @@
 #!/usr/bin/env ruby
-# $Id: cdio.rb,v 1.19 2007/10/13 23:00:18 rocky Exp $
+# $Id: cdio.rb,v 1.21 2008/05/02 13:05:40 karl Exp $
 #
-#    Copyright (C) 2006 Rocky Bernstein <rocky@gnu.org>
+#  Copyright (C) 2006, 2007, 2008 Rocky Bernstein <rocky@gnu.org>
 #
-#    This program is free software; you can redistribute it and/or modify
-#    it under the terms of the GNU General Public License as published by
-#    the Free Software Foundation; either version 2 of the License, or
-#    (at your option) any later version.
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
 #
-#    This program is distributed in the hope that it will be useful,
-#    but WITHOUT ANY WARRANTY; without even the implied warranty of
-#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-#    GNU General Public License for more details.
-#
-#    You should have received a copy of the GNU General Public License
-#    along with this program; if not, write to the Free Software
-#    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
-#    02110-1301 USA.
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
 #
+#  You should have received a copy of the GNU General Public License
+#  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
 # Author::    Rocky Bernstein  (mailto:rocky@gnu.org)
 #
 # = cdio
@@ -146,7 +144,7 @@ end
 
 
 #    close media tray in CD drive if there is a routine to do so. 
-#    The driver id is returned. A DeviceException is thrown on error.
+#    The +driver id +is returned. A DeviceException is thrown on error.
 def close_tray(drive=nil, driver_id=Rubycdio::DRIVER_UNKNOWN)
     drc, found_driver_id = Rubycdio::close_tray(drive, driver_id)
   possibly_raise_exception__(drc)
@@ -156,7 +154,7 @@ end
 #    Returns: [device, driver]
 #
 #    Return a string containing the default CD device if none is
-#    specified.  if driver_id is DRIVER_UNKNOWN or DRIVER_DEVICE
+#    specified.  if +driver_id+ is DRIVER_UNKNOWN or DRIVER_DEVICE
 #    then one set the default device for that.
 #    
 #    nil is returned as the device if we couldn't get a default
@@ -174,9 +172,9 @@ end
 
 #    Returns: [device1, device2, ... driver_id]
 #
-#    Like get_devices, but return the p_driver_id which may be different
+#    Like get_devices, but return the driver_id which may be different
 #    from the passed-in driver_id if it was Rubycdio::DRIVER_DEVICE or
-#    Rubycdio::DRIVER_UNKNOWN. The return driver_id may be useful because
+#    Rubycdio::DRIVER_UNKNOWN. The return +driver_id+ may be useful because
 #    often one wants to get a drive name and then *open* it
 #    afterwards. Giving the driver back facilitates this, and speeds things
 #    up for libcdio as well.
@@ -194,9 +192,9 @@ end
 #
 #    To find a CD-drive of any type, use the mask Rubycdio::CDIO_FS_MATCH_ALL.
 #
-#    The array of device names is returned or NULL if we couldn't get a
-#    default device.  It is also possible to return a non NULL but after
-#    dereferencing the the value is NULL. This also means nothing was
+#    The array of device names is returned or nil if we couldn't get a
+#    default device.  It is also possible to return a non nil but after
+#    dereferencing the the value is nil. This also means nothing was
 #    found.
 def devices_with_cap(capabilities, any=false)
   return Rubycdio::get_devices_with_cap(capabilities, any)
@@ -233,7 +231,7 @@ end
 #    binfile?(binfile_name)->cue_name
 #++
 #    
-#    Determine if binfile_name is the BIN file part of a CDRWIN CD
+#    Determine if +binfile_name+ is the BIN file part of a CDRWIN CD
 #    disk image.
 #    
 #    Return the corresponding CUE file if bin_name is a BIN file or
@@ -245,7 +243,7 @@ end
 #--
 #   FIXME ? is not quite right
 #++
-#    return bin_name
+#    return bin_name for a corresponding CUE file
 #    
 #    Determine if cuefile_name is the CUE file part of a CDRWIN CD
 #    disk image.
@@ -273,12 +271,12 @@ end
 
 #    tocfile?(tocfile_name)->bool
 #    
-#    Determine if tocfile_name is a cdrdao CD disc image
+#    Determine if +tocfile_name+ is a cdrdao CD disc image
 def tocfile?(tocfile_name)
   return Rubycdio::tocfile?(tocfile_name)
 end
 
-#    Convert bit mask for miscellaneous drive properties
+#    Convert +bitmask+ for miscellaneous drive properties
 #    into a dictionary of drive capabilities
 def convert_drive_cap_misc(bitmask)
   result={}
@@ -373,7 +371,7 @@ def convert_drive_cap_read(bitmask)
   return result
 end
 
-#    Convert bit mask for drive write properties
+#    Convert +bitmask+ for drive write properties
 #    into a dictionary of drive capabilities
 def convert_drive_cap_write(bitmask)
   result={}
@@ -458,7 +456,7 @@ class Device
   
   # Returns: status
   # 
-  # Playing CD through analog output at the given lsn to the ending lsn
+  # Playing CD through analog output from +start_lsn+ to +ending_lsn+
   # A DeviceError exception may be raised.
   def audio_play_lsn(start_lsn, end_lsn)
     drc=Rubycdio::audio_play_lsn(@cd, start_lsn, end_lsn)
@@ -483,8 +481,9 @@ class Device
     possibly_raise_exception__(drc)
   end
   
-  # Free resources associated with p_cdio.  Call this when done using
-  # using CD reading/control operations for the current device.
+  # Free (C memory) resources associated with the object.  Call this when
+  # done using using CD reading/control operations for the current
+  # device.
   def close()
     if @cd 
       Rubycdio::close(@cd)
@@ -696,13 +695,13 @@ class Device
   
   # Returns: track
   #    
-  # Find the track which contains lsn.
+  # Find the track which contains +lsn+.
   # nil is returned if the lsn outside of the CD or
   # if there was some error. 
   #    
-  # If the lsn is before the pregap of the first track,
+  # If +lsn+ is before the pregap of the first track,
   # A track object with a 0 track is returned.
-  # Otherwise we return the track that spans the lsn.
+  # Otherwise we return the track that spans the LSN.
   def track_for_lsn(lsn)
     track = Rubycdio::get_last_track_num(@cd)
     if track == Rubycdio::INVALID_TRACK:
@@ -715,8 +714,8 @@ class Device
   # Reposition read offset
   # Similar to (if not the same as) libc's fseek()
   #    
-  # cdio is object to get adjested, offset is amount to seek and 
-  # whence is like corresponding parameter in libc's lseek, e.g. 
+  # +offset+ is amount to seek and 
+  # +whence+ is like corresponding parameter in libc's lseek, e.g. 
   # it should be SEEK_SET or SEEK_END.
   #    
   # the offset is returned or -1 on error.
@@ -724,12 +723,12 @@ class Device
     return Rubycdio::lseek(@cd, offset, whence)
   end
   
-  # Sets up to read from place specified by source, driver_id and
-  # access mode. This should be called before using any other routine
+  # Sets up to read from place specified by +source+, +driver_id+ and
+  # +access_mode+. This should be called before using any other routine
   # except those that act on a CD-ROM drive by name. 
   #        
-  # If nil is given as the source, we'll use the default driver device.
-  # If nil is given as the driver_id, we'll find a suitable device driver.
+  # If nil is the value of +source+, we'll use the default driver device.
+  # If nil is the value of +driver_id+, we'll find a suitable device driver.
   #
   # If device object was, previously opened it is closed first.
   #        
@@ -753,7 +752,7 @@ class Device
   
   # Returns: [size, data]
   #        
-  # Reads the next size bytes.
+  # Reads the next +size+ bytes.
   # Similar to (if not the same as) libc's read()
   #        
   # The number of bytes read and the data is returned. 
@@ -768,7 +767,7 @@ class Device
   #        
   # Reads a number of data sectors (AKA blocks).
   #      
-  # lsn is sector to read, bytes is the number of bytes.
+  # +lsn+ is the sector to read; +bytes+ is the number of bytes to read.
   # A DeviceError exception may be raised.
   def read_data_blocks(lsn, blocks=1)
     size = Rubycdio::ISO_BLOCKSIZE*blocks
@@ -786,19 +785,19 @@ class Device
   #
   # Reads a number of sectors (AKA blocks).
   # 
-  # lsn is sector to read, bytes is the number of bytes.
+  # +lsn+ is the sector to read, +bytes+ is the number of bytes to read.
   #        
-  # If read_mode is Rubycdio::MODE_AUDIO, the return buffer size will be
+  # If +read_mode+ is Rubycdio::MODE_AUDIO, the return buffer size will be
   # truncated to multiple of Rubycdio::CDIO_FRAMESIZE_RAW i_blocks bytes.
   #        
-  # If read_mode is Rubycdio::MODE_DATA, buffer will be truncated to a
+  # If +read_mode+ is Rubycdio::MODE_DATA, buffer will be truncated to a
   # multiple of Rubycdio::ISO_BLOCKSIZE, Rubycdio::M1RAW_SECTOR_SIZE or
   # Rubycdio::M2F2_SECTOR_SIZE bytes depending on what mode the data is in.
   #
-  # If read_mode is Rubycdio::MODE_M2F1, buffer will be truncated to a 
+  # If +read_mode+ is Rubycdio::MODE_M2F1, buffer will be truncated to a 
   # multiple of Rubycdio::M2RAW_SECTOR_SIZE bytes.
   #        
-  # If read_mode is Rubycdio::MODE_M2F2, the return buffer size will be
+  # If +read_mode+ is Rubycdio::MODE_M2F2, the return buffer size will be
   # truncated to a multiple of Rubycdio::CD_FRAMESIZE bytes.
   #        
   # The number of bytes read and the data is returned.