Adjustments of xorriso man page

libisoburn/trunk/xorriso/xorriso.1

@@ -2,7 +2,7 @@
 .\" First parameter, NAME, should be all caps
 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
 .\" other parameters are allowed: see man(7), man(1)
-.TH XORRISO 1 "Oct 10, 2009"
+.TH XORRISO 1 "Oct 27, 2009"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
@@ -26,13 +26,13 @@ with Rock Ridge extensions.
 .SH DESCRIPTION
 .PP
 .B xorriso
-is a program which maps file objects from POSIX compliant
+is a program which copies file objects from POSIX compliant
 filesystems into Rock Ridge enhanced ISO 9660 filesystems and allows
 session-wise manipulation of such filesystems. It can load the management
 information of existing ISO images and it writes the session results to
 optical media or to filesystem objects.
 .br
-Vice versa xorriso is able to restore file objects from ISO 9660 filesystems.
+Vice versa xorriso is able to copy file objects out of ISO 9660 filesystems.
 .PP
 A special property of xorriso is that it needs neither an external ISO 9660
 formatter program nor an external burn program for CD, DVD or BD but rather
@@ -168,8 +168,8 @@ session history. If they contain one or more ISO 9660 sessions and if the
 first session was written by xorriso, then a table of content can
 be emulated. Else only a single overall session will be visible.
 .br
-DVD-RW media can be formatted by -format full. 
-They can be made unformatted by -blank deformat.
+DVD-RW media can be formatted by -format "full". 
+They can be made unformatted by -blank "deformat".
 .br
 Regular files and block devices are handled as overwriteable media.
 Pipes and other writeable file types are handled as blank multi-session media.
@@ -331,7 +331,7 @@ among the start arguments. Do not try to fool this ban via backdoor addresses
 to stdout.
 .br
 If stdout is used as drive, then -use_readline is permanently disabled.
-Use of backdoors will cause severe memory and/or tty corruption.
+Use of backdoors can cause severe memory and/or tty corruption.
 .PP
 Be aware that especially the superuser can write into any accessible file or
 device by using its path with the "stdio:" prefix. By default any address
@@ -353,7 +353,7 @@ prefix "stdio:" to other paths.
 is the name of a set of additional informations which enhance
 an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem
 with ownership, access permissions, symbolic links, and other attributes.
-.PP
+.br
 This is what xorriso uses for a decent representation of the disk files
 within the ISO image. Rock Ridge information is produced with any xorriso
 image.
@@ -520,8 +520,8 @@ try to abort as soon as possible.
 .SH OPTIONS
 .br
 All command words are shown with a leading dash although this dash is not
-mandatory for the option to be recognized. Note that with emulation modes the
-dashes of the emulated options are mandatory.
+mandatory for the option to be recognized. Nevertheless within option -as
+the dashes of the emulated options are mandatory.
 .br
 Normally any number of leading dashes is ignored with command words and
 inner dashes are interpreted as underscores.
@@ -652,7 +652,8 @@ have to deny its rw-permissions in the filesystem.
 \fB\-assert_volid\fR pattern severity
 Refuse to load ISO images with volume ids which do not match the given
 search pattern. When refusing an image, give up the input drive and issue
-an event of the given severity. An empty search pattern accepts any image.
+an event of the given severity (like FAILURE, see -abort_on). An empty search
+pattern accepts any image.
 .br
 This option does not hamper the creation of an empty image from blank
 input media and does not discard an already loaded image.
@@ -945,10 +946,10 @@ composed from disk_path by replacing disk_prefix by iso_rr_prefix.
 \fB\-update\fR disk_path iso_rr_path
 Compare file object disk_path with file object iso_rr_path. If they do not
 match, then perform the necessary image manipulations to make iso_rr_path
-a matching copy of disk_path. This comparison will imply lengthy content
-reading before a decision is made. On the other hand it strives for the
-smallest possible amount of add-on data which is needed to achieve the
-matching copy.
+a matching copy of disk_path. By default this comparison will imply lengthy
+content reading before a decision is made. Options -disk_dev_ino or -md5 may
+accelerate comparison if they were already in effect when the loaded session
+was recorded.
 .br
 If disk_path is a directory and iso_rr_path does not exist yet, then the
 whole subtree will be inserted. Else only directory attributes will be
@@ -1303,7 +1304,7 @@ Matches if pattern matches the file path as it would be printed by action
 "echo". Character '/' is not special but can be matched by wildcards.
 .br
 \fB\-type\fR type_letter :
-Matches files files of the given type:
+Matches files of the given type:
 "block", "char", "dir", "pipe", "file", "link", "socket", "eltorito",
 "Xotic" which eventually matches what is not matched by the other types.
 .br
@@ -1363,7 +1364,7 @@ Matches if the next test or sub expression does not match.
 Several tests do this specifically:
 .br
 -undamaged, -lba_range with negative start_lba, -has_no_acl, -has_no_xattr,
--has_no_aaip, -has_no_filter
+-has_no_aaip, -has_no_filter .
 .br
 \fB\-and\fR :
 Matches if both neighboring tests or expressions match.
@@ -1397,7 +1398,7 @@ may have specific parameters. See also their particular descriptions.
 as parameter. E.g.: -exec chown thomas --
 .br
 \fBchgrp\fR and \fBchgrp_r\fR change the group attribute and get the group id
-as paramieter. E.g.: -exec chgrp_r staff --
+as parameter. E.g.: -exec chgrp_r staff --
 .br
 \fBchmod\fR and \fBchmod_r\fR change access permissions and get a mode string
 as parameter.  E.g.: -exec chmod a-w,a+r --
@@ -1504,10 +1505,13 @@ Switch to growing mode.
 (A subsequent -outdev will activate modification mode or blind growing.)
 -commit is performed automatically at end of program if there
 are uncommitted manipulations pending.
+.br
 So, to perform a final write operation with no new -dev
 and no new loading of image, rather execute option -end.
+If you want to go on without image loading, execute -commit_eject "none".
+To eject after write without image loading, use -commit_eject "all".
+.br
 To suppress a final write, execute -rollback_end.
-To eject outdev after write without new loading of image, use -commit_eject.
 .br
 
 Writing can last quite a while. It is not unnormal with several
@@ -1518,8 +1522,7 @@ xorriso and the drives are in a client-server relationship.
 The drives have much freedom about what to do with the media.
 Some combinations of drives and media simply do not work,
 despite the promises by their vendors.
-If writing fails - or even the drive gets stuck and you need
-to reboot - then try other media or another drive. The reason
+If writing fails then try other media or another drive. The reason
 for such failure is hardly ever in the code of the various
 burn programs but you may well try some of those listed below
 under SEE ALSO.
@@ -1548,8 +1551,8 @@ DVD-RAM and BD-RE. Other media in blank state are gracefully ignored.
 Media which cannot be made ready for writing from scratch cause a FAILURE
 event.
 .br
-"fast" and "all" make CD-RW and unformatted DVD-RW re-usable,
-or invalidate overwriteable ISO images.
+"fast" makes CD-RW and unformatted DVD-RW re-usable, or invalidates
+overwriteable ISO images. "all" might work more thoroughly and need more time.
 .br
 "deformat" converts overwriteable DVD-RW into unformatted ones.
 .br
@@ -1775,7 +1778,7 @@ and eventually enables -disk_pattern expansion.
 .TP                
 \fB\-overwrite\fR "on"|"nondir"|"off"
 Allow or disallow to overwrite existing files in the
-ISO image by files with the same user defined name.
+ISO image by files with the same name.
 .br
 With setting "off", name collisions cause FAILURE events.
 With setting "nondir", only directories are protected by such events, other
@@ -1823,7 +1826,7 @@ their numbers have to be plausible. E.g. byte_count must be valid as -cut_out
 argument and their contents may not overlap.
 .TP                
 .B Settings for result writing:
-.TP
+.PP
 Rock Ridge info will be generated by the program unconditionally.
 ACLs will be written according to the setting of option -acl.
 .TP
@@ -2037,7 +2040,7 @@ can assume overwriteable media.
      "discard"|"keep"|"patch"|"show_status"|bootspec
 .br
 Define the handling of an eventual El Torito object which has
-been read from an existing ISO image or defines how to make a prepared
+been read from an existing ISO image or define how to make a prepared
 ISOLINUX file set bootable.
 .br
 
@@ -2342,9 +2345,9 @@ Drives which are occupied by other processes get not shown.
 Show media specific table of content. This is the media session history,
 not the ISO image directory tree.
 .br
-In case of overwriteable media holding a valid ISO image, a single session
-gets fabricated from the ISO image size info. But if the first session on the
-overwriteable media was written by xorriso then in most cases a complete
+In case of overwriteable media holding a valid ISO image, it may happen that
+only a single session gets shown. But if the first session on the
+overwriteable media was written by xorriso then a complete
 session history can be emulated.
 .br
 A drive which is incapable of writing may show any media as CD-ROM or DVD-ROM
@@ -2363,13 +2366,12 @@ drive can be "indev" or "outdev" to indicate already aquired drives,
 or it can be the path of a not yet acquired drive.
 Prefix "stdio:" for non-MMC drives is not mandatory.
 .br
-entity must be either "sbsector" , "track" , "session" , "volid" 
-or "auto". See also option -load.
+entity must be either "sbsector" with the superblock sector address as id,
+or "track" with a track number as id, or "session" with a session number,
+or "volid" with a search pattern for the volume id, or "auto" with any text
+as id. 
 .br
-id gives the superblock sector address, the track number, the session number,
-or a search pattern for the volume id respectively.
-.br
-path will be used as mount point and must already exist as a directory.
+path will be used as mount point and must already exist as a directory on disk.
 .br
 The command gets printed to the result channel. See option -mount
 for direct execution of this command.
@@ -2417,9 +2419,8 @@ ids -pvd_info reports what would be written with the next -commit.
 .B Navigation in ISO image and disk filesystem:
 .TP
 \fB\-cd\fR iso_rr_path
-Change the current working directory in the emerging ISO
-image as it is at the moment. This is prepended to iso_rr_paths
-which do not begin with '/'.
+Change the current working directory in the ISO image.
+This is prepended to iso_rr_paths which do not begin with '/'.
 .br
 It is possible to set the working directory to a path which does not exist
 yet in the ISO image. The necessary parent directories will be created when
@@ -2428,7 +2429,7 @@ Use -mkdir if you want to enforce the existence of the directory already at
 first insertion.
 .TP
 \fB\-cdx\fR disk_path
-Change the current working directory on filesystem.
+Change the current working directory in the local filesystem.
 To be prepended to disk_paths which do not begin with '/'.
 .TP
 \fB\-pwd\fR
@@ -2437,13 +2438,13 @@ Tell the current working directory in the ISO image.
 .TP
 \fB\-pwdx\fR
 .br
-Tell the current working directory on local filesystem.
+Tell the current working directory in the local filesystem.
 .TP
 \fB\-ls\fR iso_rr_pattern [***]
 List files in the ISO image which match shell patterns
 (i.e. with wildcards '*' '?' '[a-z]').
 If a pattern does not begin with '/' then it is compared with addresses
-relative to -cd, the current working directory in the ISO image.
+relative to -cd.
 .br
 Directories are listed by their content rather than as single file item.
 .br
@@ -2462,9 +2463,8 @@ Like -lsd but also list some of the file attributes.
 The output format resembles shell command ls -dln.
 .TP
 \fB\-lsx\fR disk_pattern [***]
-List files on local filesystem which match shell patterns. Patterns which do
-not begin with '/' are used relative to -cdx, the current working directory in
-the local filesystem.
+List files in the local filesystem which match shell patterns. Patterns which
+do not begin with '/' are used relative to -cdx.
 .br
 Directories are listed by their content rather than as single file item.
 .br
@@ -2512,7 +2512,7 @@ Similar to shell command du -sk.
 .TP
 \fB\-dux\fR disk_pattern [***]
 Recursively list size of directories and files in the local filesystem
-which match one of the patterns, similar to shell command du -k.
+which match one of the patterns. Similar to shell command du -k.
 .TP
 \fB\-dusx\fR disk_pattern [***]
 List size of directories and files in the local filesystem
@@ -2529,7 +2529,7 @@ different device than their parent. It never matches the disk_path
 given as start address for -findx.
 .br
 -findx accepts the -exec actions as does -find. But except the following few
-actions it will allways perform action "echo".
+actions it will always perform action "echo".
 .br
 \fBin_iso\fR reports the path if its counterpart exist in the ISO image.
 For this the disk_path of the -findx command gets replaced
@@ -2627,12 +2627,12 @@ of blocks and quality. Qualities which begin with "+" are
 supposed to be valid readable data. Qualities with "-" are unreadable or
 corrupted data.
 "0" indicates qualities which are not covered by the check run or are regularly
-allowed to to be unreadable (e.g. gaps between tracks).
+allowed to be unreadable (e.g. gaps between tracks).
 .br
 Alternatively it is possible to report damaged files rather than blocks.
 .br
-If -md5 is on then the default mode what=tracks looks out for libisofs
-checksum tags for the ISO session data and and eventually checks them
+If -md5 is "on" then the default mode what=tracks looks out for libisofs
+checksum tags for the ISO session data and eventually checks them
 against the checksums computed from the data stream.
 .TP
 \fB\-check_media_defaults\fR [option [option ...]] --
@@ -2654,6 +2654,7 @@ abort_file=/var/opt/xorriso/do_abort_check_media
 sector_map='' map_with_volid=off patch_lba0=off report=blocks
 .br
 bad_limit=valid slow_limit=1.0 chunk_size=0s
+.br
 Option "reset=now" restores these startup defaults.
 .br
 Non-default options are:
@@ -2729,7 +2730,7 @@ sector_map= and processes this virtual outcome.
 Choose one of "good", "md5_match", "slow", "partial", "valid", "untested",
 "invalid", "tao_end", "off_track", "md5_mismatch", "unreadable".
 .br
-"slow_limit=" sets the time threshold for a single read chunk to considered
+"slow_limit=" sets the time threshold for a single read chunk to be considered
 slow. This may be a fractional number like 0.1 or 1.5.
 .br
 "chunk_size=" sets the number of bytes to be read in one read operation.
@@ -2758,7 +2759,7 @@ Only mismatching data files will be reported.
 .PP
 Normally xorriso only writes to disk files which were given as stdio:
 pseudo-drives or as log files.
-But its alter ego, osirrox, is able to extract file objects
+But its alter ego osirrox is able to extract file objects
 from ISO images and to create, overwrite, or delete file objects on disk.
 .br
 Disk file exclusions by -not_mgt, -not_leaf, -not_paths apply.
@@ -2811,13 +2812,13 @@ written, or ejected. But be aware that even harmless inquiries can spoil
 ongoing burns of CD-R[W] and DVD-R[W].
 .TP
 \fB\-extract\fR iso_rr_path disk_path
-Restore the file objects at and underneath iso_rr_path to their corresponding
+Copy the file objects at and underneath iso_rr_path to their corresponding
 addresses at and underneath disk_path.
 This is the inverse of -map or -update_r.
 .br
 If iso_rr_path is a directory and disk_path is an existing directory then
 both trees will be merged. Directory attributes get extracted only if the disk
-directory is newly created by the restore operation.
+directory is newly created by the copy operation.
 Disk files get removed only if they are to be replaced
 by file objects from the ISO image.
 .br
@@ -2846,8 +2847,8 @@ is performed. It may be quicker and more rugged than the general reading
 method.
 .TP
 \fB\-cpx\fR iso_rr_path [***] disk_path
-Extract single leaf file objects from the ISO image and store them under
-the address given by disk_path. If more then one iso_rr_path is given then
+Copy single leaf file objects from the ISO image to the address given by
+disk_path. If more then one iso_rr_path is given then
 disk_path must be a directory or non-existent. In the latter case it gets
 created and the extracted files get installed in it with the same leafnames.
 .br
@@ -2925,7 +2926,7 @@ If pathspecs are given and if no output file was chosen before or during the
 "mkisofs" option list, then standard output (-outdev "-") will get into effect.
 If -o points to a regular file, then it will be truncated to 0 bytes
 when finally writing begins. This truncation does not happen if the drive
-is chosen by xorriso options before or after -as mkisofs.
+is chosen by xorriso options before -as mkisofs or after its list delimiter.
 Directories and symbolic links are no valid -o targets.
 .br
 Writing to stdout is possible only if -as "mkisofs" was among the start
@@ -3036,7 +3037,7 @@ Print program name and version.
 \fB\-history\fR textline
 Copy textline into libreadline history.
 .TP
-\fB\-status\fR [mode|filter]
+\fB\-status\fR mode|filter
 Print the current settings of xorriso.
 Modes:
 .br
@@ -3147,7 +3148,7 @@ The first three items are single words, the rest of the line is the volume id.
 End program immediately
 .TP
 \fB#\fR any text
-In dialog or file execution mode only and only as first
+Only in dialog or file execution mode, and only as first
 non-whitespace in line:
 Do not execute the line but eventually store it in history.
 .TP
@@ -3173,17 +3174,18 @@ Example:
  I:1: enter option and arguments :
 .TP
 \fB\-logfile\fR channel fileaddress
-Copy output of a channel to the given file.
+Copy output of a channel to the given file. Channel may be one of: "." for all
+channels, "I" for info messages, "R" for result lines, "M" for -mark texts.
 .TP
 \fB\-mark\fR text
-If text is not empty it will get put out each time an
-action has been completed.
+If text is not empty it will get put out each time after a dialog line has been
+processed.
 .TP
 \fB\-prog\fR text
-Use text as this program's name in subsequent messages
+Use text as name of this program in subsequent messages
 .TP
 \fB\-prog_help\fR text
-Use text as this program's name and perform -help.
+Use text as name of this program and perform -help.
 .br
 .SH EXAMPLES
 .SS
@@ -3194,7 +3196,7 @@ Blank media and compose a new ISO image as batch run
 .br
 A dialog session doing about the same
 .br
-Manipulating an existing ISO image on the same media
+Manipulate an existing ISO image on the same media
 .br
 Copy modified ISO image from one media to another
 .br
@@ -3252,7 +3254,7 @@ session to media.
 .br
 The ISO image may be shaped in a more elaborate way like the following:
 Omit some unwanted stuff by removing it from the image directory tree.
-Re-add some wanted stuff.
+Reintroduce some wanted stuff.
 .br
 \fB$\fR cd /home/me
 .br
@@ -3276,15 +3278,16 @@ Re-add some wanted stuff.
 .br
  -cd / \\
 .br
- -add pictures/confidential/work*
+ -add pictures/confidential/work* --
 .br
 Note that '/pictures/*private*' is a pattern for iso_rr_paths
 while pictures/confidential/work* gets expanded by the shell
-with addresses from the hard disk.
+with addresses from the hard disk. Options -add and -map have different
+argument rules but finally the same effect: they put files into the image.
 .SS
 .B A dialog session doing about the same
 .br
--pathspecs is already given as start argument. The other activities
+Some settings are already given as start argument. The other activities
 are done as dialog input. The pager gets set to 20 lines of 80 characters.
 .br
 The drive is aquired by option -dev rather than -outdev in order to see
@@ -3326,15 +3329,16 @@ enter option and arguments :
 .br
 enter option and arguments :
 .br
-.B \-commit -eject all -end
+.B \-commit_eject all -end
 .br
 .SS
-.B Manipulating an existing ISO image on the same media
+.B Manipulate an existing ISO image on the same media
 Load image from drive.
 Remove (i.e. hide) directory /sounds and its subordinates.
 Rename directory /pictures/confidential to /pictures/restricted.
 Change access permissions of directory /pictures/restricted.
-Add new directory trees /sounds and /movies. Burn to the same media and eject.
+Add new directory trees /sounds and /movies.
+Burn to the same media, check whether the tree can be loaded, and eject.
 .br
 \fB$\fR xorriso -dev /dev/sr2 \\
 .br
@@ -3408,7 +3412,8 @@ Paths underneath /dev normally need prefix "stdio:"
 .br
 If /dev/sdb is to be used frequently and /dev/sda is the system disk,
 then consider to place the following lines in a xorriso Startup File.
-They allow to use /dev/sdb without prefix and protect your disk from xorriso:
+They allow to use /dev/sdb without prefix and protect disk /dev/sda
+from xorriso:
 .br
   -drive_class banned   /dev/sda*
   -drive_class harmless /dev/sdb
@@ -3628,6 +3633,9 @@ Avoid to eventually create /home/thomas/restored without rwx-permission.
  -extract /personal_mail /home/thomas/restored/personal_mail \\
 .br
  -rollback_end
+.br
+The final command -rollback_end prevents an error message about the altered
+image being discarded.
 .SS
 .B Try to retrieve as many blocks as possible from a damaged media
 .br
@@ -3641,9 +3649,6 @@ This can be repeated several times, eventually with -eject or with other
 -indev drives. See the human readable part of "$HOME"/dvd_copy.map for
 addresses which can be used on "$HOME"/dvd_copy with mount option -o sbsector=
 resp. -s.
-.br
-If you want to make the newest session the default mount session, you
-may add option "patch_lba0=on" to the final -check_media run.
 .SH FILES
 .SS 
 .B Startup files: