Corrections and updates of documentation

libisoburn/trunk/xorriso/xorrisofs.texi

@@ -44,7 +44,7 @@
 @c man .\" First parameter, NAME, should be all caps
 @c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
 @c man .\" other parameters are allowed: see man(7), man(1)
-@c man .TH XORRISOFS 1 "Mar 06, 2011"
+@c man .TH XORRISOFS 1 "Mar 09, 2011"
 @c man .\" Please adjust this date whenever revising the manpage.
 @c man .\"
 @c man .\" Some roff macros, for reference:
@@ -298,14 +298,21 @@ on the intended media.
 @*
 Both values can be inquired from optical media by help of burn programs
 and cdrecord option -msinfo. xorriso itself can obtain it in its
-cdrecord emulation:
+cdrecord emulation. Do not let it load the drive, but rather do this manually
+or by a program like dd which reads a few bytes. Only then it is sure that
+the device driver knows the true readable size of the media.
 @*
- values=$(xorriso -as cdrecord dev=/dev/... -msinfo)
- echo $values
+@sp 1
+  dd if=/dev/... count=1 >/dev/null 2>&1
 @*
+  values=$(xorriso -as cdrecord dev=/dev/... -msinfo)
+@*
+  echo $values
+@*
+@sp 1
 Option -C may be used without option -M to create an ISO image from
 scratch and prepare it for being finally written to a block address
-other than 0. Parameter last_session_start should then be set to 0.
+other than 0. Parameter last_session_start must then be set to 0.
 @c man .TP
 @item -cdrecord-params last_session_start,next_writeable_address
 @kindex -cdrecord-params   set load address and write address offset
@@ -1552,6 +1559,12 @@ yields in the ISO image:
 @c man .B Perform multi-session runs
 @node ExMkisofs, ExGrowisofs, ExGraft, Examples
 @section Perform multi-session runs
+This example works for multi-session media only:
+CD-R[W], DVD-R[W], DVD+R, BD-R.
+Add cdrskin option @minus{}@minus{}grow_overwriteable_iso
+to all -as cdrecord runs
+in order to enable multi-session emulation on overwriteable media.
+@*
 The first session is written like this:
 @*
 @sp 1
@@ -1565,11 +1578,13 @@ The first session is written like this:
 Follow-up sessions are written like this:
 @*
 @sp 1
+  $ dd if=/dev/sr0 count=1 >/dev/null 2>&1
+@*
   $ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
 @*
   $ xorrisofs -M /dev/sr0 -C $m -graft-points \
 @*
-              /tree2/=prepared_for_iso/tree2 \
+              /tree2=prepared_for_iso/tree2 \
 @*
     | xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -
 @*
@@ -1577,12 +1592,11 @@ Follow-up sessions are written like this:
 Always eject the drive tray between sessions. The old sessions
 get read via /dev/sr0. Its device driver might not be aware
 of the changed content before it loads the media again.
+In this case the previous session would not be loaded and the
+new session would contain only the newly added files.
 @*
-@sp 1
-This example works for multi-session media only.
-Add cdrskin option @minus{}@minus{}grow_overwriteable_iso
-to all -as cdrecord runs
-in order to enable multi-session emulation on overwriteable media.
+For the same reason do not let xorriso -as cdrecord load the media,
+but rather do this manually or by a program that reads from /dev/sr0.
 @c man .SS
 @c man .B Let xorrisofs work underneath growisofs
 @node ExGrowisofs, ExIncBackup, ExMkisofs, Examples
@@ -1613,9 +1627,17 @@ start with "-o" but -outdev must be set to "-".
 So use "outdev" instead:
 @*
 @sp 1
-  $ growisofs -Z /dev/dvd @minus{}@minus{} outdev - -update_r /my/files /files
+  $ growisofs -Z /dev/dvd @minus{}@minus{}for_backup @minus{}@minus{} \
 @*
-  $ growisofs -M /dev/dvd @minus{}@minus{} outdev - -update_r /my/files /files
+              outdev - -update_r /my/files /files
+@*
+  $ growisofs -M /dev/dvd @minus{}@minus{}for_backup @minus{}@minus{} \
+@*
+              outdev - -update_r /my/files /files
+@*
+Note that @minus{}@minus{}for_backup is given in the mkisofs emulation.
+To preserve the recorded extra data it must already be in effect, when
+the emulation loads the image.
 @c man .SS
 @c man .B Incremental backup of a few directory trees
 @node ExIncBackup, ExIncBckAcc, ExGrowisofs, Examples
@@ -1637,7 +1659,12 @@ the two disk trees to the media is desired. Begin with blank media and start
 a new blank media when the run fails due to lack of remaining space on
 the old one.
 @*
+Do not let xorriso -as cdrecord load the media,
+but rather do this manually or by a program that reads from /dev/sr0.
+@*
 @sp 1
+  $ dd if=/dev/sr0 count=1 >/dev/null 2>&1
+@*
   $ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
 @*
   $ load_opts=
@@ -1745,9 +1772,14 @@ With the first session:
 @sp 1
 @c man .sp 1
 With the second session, option -old-root refers to /session1 and the
-new -root is /session2:
+new -root is /session2.
+@*
+Do not let xorriso -as cdrecord load the media,
+but rather do this manually or by a program that reads from /dev/sr0.
 @*
 @sp 1
+  $ dd if=/dev/sr0 count=1 >/dev/null 2>&1
+@*
   $ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
 @*
   $ load_opts=
@@ -1790,9 +1822,15 @@ The prescribed mkisofs options can be used unchanged with xorrisofs:
       ./CD_root
 @*
 @sp 1
+Put it on CD by a burn program. E.g.:
+@*
+@sp 1
+  $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed output.iso
+@*
+@sp 1
 @c man .sp 1
 The image from above example will boot from CD, DVD or BD, but not from
-USB stick or orther hard-disk-like devices. This can be done by help of an
+USB stick or other hard-disk-like devices. This can be done by help of an
 isohybrid MBR. Syslinux provides matching template files
 as isohdp[fp]x*.bin . E.g. /usr/lib/syslinux/isohdpfx.bin .
 @*
@@ -1804,6 +1842,8 @@ tools for partitioning and formatting.
 The image from the following example will be prepared for booting via MBR
 and its first parttion will start at hard disk block 64.
 @*
+It will also boot from optical media.
+@*
 @sp 1
   $ xorrisofs -o output.iso \
 @*