Overhauled description of media types, states and expansion methods

libisoburn/trunk/test/xorriso.1

@@ -61,6 +61,8 @@ Provides navigation commands for interactive ISO image manipulation.
 .br
 Session model
 .br
+Media types and states
+.br
 Creating, Growing, Modifying
 .br
 Libburn drives
@@ -97,26 +99,25 @@ This session usually contains an updated directory tree for the whole media
 which governs the data contents in all recorded sessions.
 So in the view of the mount program all sessions of a particular media
 together form a single filesystem image.
+.br
+Adding a session to an existing ISO image is in this text referred as
+\fBgrowing\fR.
+.br
+The multi-session model of the MMC standard does not apply to all all media
+types. But program growisofs by Andy Polyakov showed how to extend this
+functionality to overwriteable media or disk files which carry valid ISO 9660
+filesystems. This expansion method is referred as as emulated growing.
 .PP
-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 named
 \fBmodifying\fR which produces a completely new ISO image from the old
-one and the modifications. See next paragraph for details.
+one and the modifications. See paragraph Creating, Growing, Modifying below.
 .PP
 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 or by the definition of an output file.
+drive with the eventual ISO image or by the definition of an output drive.
 The session ends by command -commit which triggers writing. A -commit is
 done automatically when the program ends regularly.
 .PP
@@ -132,14 +133,58 @@ session.
 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
+.B Media types and states:
+There are two families of media in the MMC standard:
+.br
+\fBMulti-session\fR media are CD-R, CD-RW, DVD-R, DVD+R, and
+unformatted DVD-RW. These media provide a table of content which
+describes their existing sessions.
+.br
+\fBOverwriteable\fR media are DVD-RAM, DVD+RW, and formatted DVD-RW.
+They allow random write access but do not provide information about their
+session history.
+.br
+DVD-RW media can be formatted by -format full. 
+They can be made unformatted by -blank deformat.
+.br
+Emulated drives are handled as overwriteable media if they are random
+read-write accessible. If they are only sequentially writeable then
+they are handled as blank multi-session media.
+.PP
+These media can assume several states in which they offer different
+capabilities.
+.br
+\fBBlank\fR media can be written from scratch. They contain no ISO image
+suitable for xorriso.
+.br
+Blank is the state of newly purchased optical media.
+With used CD-RW and DVD-RW it can be achieved by action -blank fast.
+Overwriteable media are considered blank unless they contain an ISO image
+suitable for xorriso.
+.br
+\fBAppendable\fR media accept further sessions. Either they are MMC
+multi-session media in appendable state, or they are overwriteable media
+which contain an ISO image suitable for xorriso.
+.br
+Appendable is the state after writing a session with option -close off.
+.br
+\fBClosed\fR media cannot be written. They may contain an ISO image suitable
+for xorriso.
+.br
+Closed is the state of DVD-ROM media and of multi-session media which were
+written with option -close on. If the drive is incapable of writing it will
+probably show any media as closed CD-ROM resp. DVD-ROM.
+.br
+Overwriteable media assume this state only in such read-only drives.
+.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.
+The new empty 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
@@ -171,9 +216,9 @@ filesystem objects as source and/or target media.
 .SS
 .B Libburn drives:
 .br
-Input drive, i.e. source of an existing ISO image, can be any random access
+Input drive, i.e. source of an existing or empty ISO image, can be any random
-readable libburn drive: optical media with readable data, regular files,
+access readable libburn drive: optical media with readable data or blank,
-block devices.
+regular files, block devices.
 .br
 Rock Ridge info must be present in existing ISO images and it will be generated
 by the program unconditionally.
@@ -259,7 +304,8 @@ Be aware that the interaction of quotation marks and pattern symbols like "*"
 differs from the usual shell parsers. In xorriso, a quotation mark does not
 make a pattern symbol literal.
 .PP
-When the program begins then it first looks for its startup files and
+When the program begins then it first looks for argument -no_rc. If this is
+not present then it 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 "on" was executed up to then.
@@ -273,6 +319,11 @@ event which triggers the threshold of command -abort_on.
 Options marked with prefix '>' are not implemented yet.
 .br
 Options with prefix '?' are not tested yet.
+.br
+All command words are shown with a leading dash although this dash is not
+mandatory for the option to be recognized. There may be future emulation
+modes, where dashes may become mandatory in order to distinguish options
+from file addresses.
 .TP
 .B Aquiring source and target drive:
 .TP
@@ -290,7 +341,7 @@ without aquiring a new one.
 .TP
 \fB\-indev\fR address
 Set input drive and load eventual ISO image. If the new input drive differs
-from outdev then switch from growing to modifying. The same rules and
+from -outdev then switch from growing to modifying. The same rules and
 restrictions apply as with -dev.
 .TP
 \fB\-outdev\fR address
@@ -307,7 +358,7 @@ An empty address string gives up the current output drive
 without aquiring a new one. No writing is possible without an output drive.
 .TP
 \fB\-ban_stdio_write\fR
-Allow for writing only the usage of optical drives. Disallow
+Allow for writing only the usage of MMC optical drives. Disallow
 to write the result into files of nearly arbitrary type.
 Once set, this command cannot be revoked.
 .TP
@@ -930,7 +981,7 @@ made ready for being overwritten and the loaded ISO image is made empty.
 In order to be able to eject the media, the session needs to be committed
 explicitely.
 .br
-\fB$\fR xorriso -graft-points -dialog on -page 20 80
+.B $ xorriso -graft-points -dialog on -page 20 80
 .br
 enter option and arguments :
 .br
@@ -966,7 +1017,7 @@ 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 DVD and eject.
+Add new directory trees /sounds and /movies. Burn to the same media and eject.
 .br
 \fB$\fR xorriso -dev /dev/sr2 \\
  -rm_r /sounds -- \\