Polished xorriso man page

libisoburn/trunk/test/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 "November 11, 2007"
+.TH XORRISO 1 "November 14, 2007"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
@@ -61,11 +61,16 @@ Provides navigation commands for interactive ISO image manipulation.
 .br
 Session model
 .br
+Creating, Growing, Modifying
+.br
 Libburn drives
 .br
 Rock Ridge, POSIX, X/Open
 .br
 Command processing
+.sp 1
+Maybe you first want to have a look at section EXAMPLES near the end of
+this text before reading the next few hundred lines of background information.
 .SS
 .B Session model:
 .br
@@ -79,7 +84,7 @@ The data content of the session is called filesystem
 The written image in its session can then be mounted by the operating system
 for being used read-only. Linux is able to mount ISO images from block devices,
 which may represent optical media, other media or via a loop device even
-regular disk files.
+from regular disk files.
 .PP
 This session usage model has been extended on CD media by the concept of
 .B multi-session ,
@@ -97,25 +102,27 @@ The multi-session model of the MMC standard applies to CD-R[W], to DVD-R, to
 certain states of DVD-RW, and to DVD+R. But it does not apply to overwriteable
 MMC media like DVD-RAM, DVD+RW, formatted DVD-RW, and of course not to disk
 files or non-CD/DVD block devices.
+.br
 Program growisofs by Andy Polyakov showed how to extend this functionality
 to overwriteable media or disk files which carry valid ISO 9660 filesystems.
 These two expansion methods are referred as \fBgrowing\fR in this text.
 .br
-xorriso provides both ways of growing as well as an own method which produces
-a completely new ISO image from the old one and the modifications.
-See below.
+xorriso provides both ways of growing as well as an own method named
+\fBmodifying\fR which produces a completely new ISO image from the old
+one and the modifications. See next paragraph for details.
 .PP
-xorriso adopts the concept of session by loading an eventual image directory
-tree, allowing to manipulate it by several actions, and to write the new
-image to the target media.
+xorriso adopts the concept of multi-session by loading an eventual image
+directory tree, allowing to manipulate it by several actions, and to write
+the new image to the target media.
 .br
 The first session of a xorriso run begins by the definition of the input
-drive with the eventual ISO image and ends by command -commit which triggers
-writing. A -commit is done automatically when the program ends regularly.
+drive with the eventual ISO image or by the definition of an output file.
+The session ends by command -commit which triggers writing. A -commit is
+done automatically when the program ends regularly.
 .PP
-After -commit a new session begins. A new input drive can only be chosen
-as long as the loaded ISO image was not altered.
-Pending alteration can be revoked by command -rollback.
+After -commit a new session begins with the freshly written one as input.
+A new input drive can only be chosen as long as the loaded ISO image was
+not altered. Pending alteration can be revoked by command -rollback.
 .PP
 Writing a session to the target is supposed to be very expensive in terms of
 time and of consumed space on appendable or write-once media. Therefore all
@@ -124,30 +131,56 @@ session.
 .br
 In some special situations (e.g. in a file-to-file situation) it can be
 useful to store intermediate states and to continue with image manipulations.
+.SS
+.B Creating, Growing, Modifying
+.br
+A new empty ISO image gets created if there is no input drive with a valid
+ISO 9660 image plus Rock Ridge extensions when the first time an output drive
+is defined. This is achieved by option -dev on blank media or by option -outdev
+on media in any state.
+.br
+The new image can be populated with directories and files.
+Before it can be written, the media in the output drive must get into
+blank state if it was not blank already.
 .PP
-The unique xorriso method of \fBmodifying\fR produces compact filesystem
-images with no waste by outdated data blocks and it can write modified images
-to target media which are completely unsuitable for multi-session operations.
-E.g. fast blanked DVD-RW, named pipes, character devices, sockets.
-It is important to note that modified sessions can be written to blank
-media only.
+If there is a input drive with a valid ISO image, then this image gets loaded
+as foundation for manipulations and extension. The constellation of input
+and output drive determines which of two write methods will be used.
+They have quite different capabilities and constraints.
+.PP
+The method of \fBgrowing\fR adds new data to the existing media. These
+data comprise of eventual new file content and they override the existing
+ISO 9660 + Rock Ridge directory tree. It is possible to hide files from
+previous sessions but they still exist on media and with many types of
+optical media it is quite easy to recover them by mounting older sessions.
+.br
+Growing is achieved by option -dev.
+.PP
+The write method of \fBmodifying\fR produces compact filesystem
+images with no outdated files or directory trees. Modifying can write its
+images to target media which are completely unsuitable for multi-session
+operations. E.g. fast blanked DVD-RW, named pipes, character devices, sockets.
+On the other hand modified sessions cannot be written to appendable media
+but to blank media only.
 .br
 Modifying takes place whenever input drive and output drive are not the same.
-See options -dev, -indev, -outdev.
+This is achieved by options -indev and -outdev.
+.br
 So for this method one needs either two optical drives or has to work with
 filesystem objects as source and/or target media.
 .SS
 .B Libburn drives:
 .br
-Source of an existing ISO image can be any random access readable libburn
-drive: optical media with readable data, regular files, block devices.
+Input drive, i.e. source of an existing ISO image, can be any random access
+readable libburn drive: optical media with readable data, regular files,
+block devices.
 .br
 Rock Ridge info must be present in existing ISO images and it will be generated
 by the program unconditionally.
 .PP
-Target for writing can be any libburn drive.
+Output drive, i.e. target for writing, can be any libburn drive.
 Some drive types do not support the method of growing but only the method
-of modifying.
+of modifying. They all are suitable for newly created images.
 .br
 All drive file objects have to offer rw-permission to the user of xorriso.
 Even those which will not be useable for reading an ISO image.
@@ -229,7 +262,7 @@ make a pattern symbol literal.
 When the program begins then it first looks for its startup files and
 eventually reads their content as command input lines. Then it interprets
 the program arguments as commands and parameters and finally it enters
-dialog mode if command -dialog was executed up to then.
+dialog mode if command -dialog "on" was executed up to then.
 .PP
 The program ends either by command -end, or by the end of program arguments
 if not command -dialog was encountered up to that moment, or by a problem
@@ -479,11 +512,10 @@ Defined modes are:
 "fast" and "all" make CD-RW and unformatted DVD-RW re-usable,
 or invalidate overwriteable ISO images.
 "deformat" converts overwriteable DVD-RW into unformatted ones.
-"deformat_quickest" is faster but produces media which are
-only suitable for a single session. xorriso will write onto
-them only if option -close is set to "on".
+"deformat_quickest" is a faster way to deformat or blank DVD-RW
+but produces media which are only suitable for a single session.
+xorriso will write onto them only if option -close is set to "on".
 .br
-
 The progress reports issued by some drives while blanking are
 quite unrealistic. Do not conclude success or failure from the
 reported percentages. Blanking was successful if no FATAL or
@@ -807,10 +839,10 @@ Add the files from hard disk directories /home/me/sounds and /pictures.
 Omit some unwanted stuff by removing it from the image directory tree.
 Re-add some wanted stuff.
 .br
-Because no -dialog "on" is given the program will then end by committing the
+Because no -dialog "on" is given, the program will then end by committing the
 session to media.
 .br
-\fB$\fR xorriso -dev /dev/sr2 \\
+\fB$\fR xorriso -outdev /dev/sr2 \\
  -blank fast \\
  -graft-points \\
  -add \\
@@ -834,6 +866,10 @@ with addresses from the hard disk.
 -graft-points is already given as start argument. The other activities
 are done as dialog input. The pager gets set to 20 lines of 80 chracters.
 .br
+The drive is aquired by option -dev rather than -outdev in order to see
+the message about its current content. By option -blank this content is
+made ready for being overwritten and the loaded ISO image is made empty.
+.br
 In order to be able to eject the media, the session needs to be committed
 explicitely.
 .br
@@ -868,12 +904,13 @@ enter option and arguments :
 .B \-commit -eject all -end
 .br
 .SS
-.B Modifying an existing ISO image
+.B Manipulating 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 dummy as replacement of /pictures/confidential.
-Add new directory tree /movies. Burn to DVD and eject.
+Add new directory tree /movies. Burn to the same DVD and eject.
 .br
 \fB$\fR xorriso -dev /dev/sr2 \\
  -rm_r /sounds -- \\
@@ -887,8 +924,21 @@ Add new directory tree /movies. Burn to DVD and eject.
  /sounds=/home/me/prepared_for_dvd/sounds_dummy \\
  /movies=/home/me/prepared_for_dvd/movies \\
  -- \\
- -commit \\
- -eject all
+ -commit -eject all
+.SS
+.B Copy modified ISO image from one media to another
+Load image from input drive. Do the same manipulations as in the previous
+example. Aquire output drive and blank it. Burn the modified image as
+first and only session to the output drive.
+.br
+\fB$\fR xorriso -indev /dev/sr2 \\
+ -rm_r /sounds -- \\
+ ...
+ /movies=/home/me/prepared_for_dvd/movies \\
+ -- \\
+ -outdev /dev/sr0 \\
+ -blank fast \\
+ -commit -eject all
 .SS
 .B Examples of input timestrings
 .br
@@ -938,7 +988,7 @@ Other programs which produce ISO 9660 images
 .BR mkisofs(8),
 .BR genisoimage(8)
 .TP
-Other programs which burn images to optical media
+Other programs which burn sessions to optical media
 .BR growisofs(1),
 .BR cdrecord(1),
 .BR wodim(1),