Polished xorrisofs documentation

libisoburn/trunk/xorriso/xorrisofs.1

@@ -9,7 +9,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 XORRISOFS 1 "Mar 05, 2011"
+.TH XORRISOFS 1 "Mar 06, 2011"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
@@ -24,7 +24,7 @@
 .\" for manpage-specific macros, see man(7)
 .nh
 .SH NAME
-xorrisofs -  Emulation of ISO 9660 program mkisofs by program xorriso,
+xorrisofs -  Emulation of ISO 9660 program mkisofs by program xorriso
 .SH SYNOPSIS
 .B xorrisofs
 [ options ] [-o filename ] pathspec [pathspecs ...]
@@ -34,41 +34,22 @@ xorrisofs -  Emulation of ISO 9660 program mkisofs by program xorriso,
 \fBxorrisofs\fR
 produces Rock Ridge enhanced ISO 9660 filesystems and add-on sessions to
 such filesystems. Optionally it can produce Joliet directory trees too.
+.br
 .PP
 xorrisofs understands options of program mkisofs from cdrtools by
 Joerg Schilling.
 Its implementation is part of program xorriso which shares no source
 code with cdrtools.
 .SS
-\fBRelation to program xorriso:\fR
-.br
-xorrisofs is actually a command mode of program \fBxorriso\fR,
-which gets entered either by xorriso command "-as mkisofs" or by
-starting the program by one of the names "xorrisofs", "mkisofs",
-"genisoimage", or "genisofs".
-.br
-This command mode can be left by argument "--" which leads
-to generic xorriso command mode. See \fBman xorriso\fR for its description.
-.br
-.PP
-xorriso performs image reading and writing by help of libburn, which is
-mainly intended for optical drives, but also operates on all POSIX
-file types except directories.
-.br
-The program messages call any file a "drive". File types which are not
-supported for reading are reported as "blank". The reported free media
-space may be quite fictional.
-.br
-Nevertheless xorrisofs does not operate directly on optical drives,
-but rather forces libburn to regard them as general device files.
-So for writing of sequential optical media (CD, DVD-R, DVD+R, BD-R)
-one will have to use a burn program. E.g the cdrecord emulation of xorriso.
-See EXAMPLES.
-.SS
 \fBISO 9660, Rock Ridge, Joliet:\fR
 .br
 \fBISO 9660\fR
-(aka \fBECMA-119\fR) describes directories and data files with
+(aka \fBECMA-119\fR) is a read-only filesystem that is mainly used for
+optical media CD, DVD, BD, but may also reside on other storage devices like
+disk files, USB sticks or disk partitions. It is widely readable by many
+operating systems and by boot facilities of personal computers.
+.br
+ISO 9660 describes directories and data files by
 very restricted filenames with no distinction of upper case and lower case. 
 Its metadata do not comply to fundamental POSIX specifications.
 .br
@@ -130,6 +111,31 @@ underneath this directory get inserted into the image, too.
 It is possible to exclude particular files from being inserted
 by help of option -m.
 .SS
+\fBRelation to program xorriso:\fR
+.br
+xorrisofs is actually a command mode of program \fBxorriso\fR,
+which gets entered either by xorriso command "-as mkisofs" or by
+starting the program by one of the names "xorrisofs", "mkisofs",
+"genisoimage", or "genisofs".
+.br
+This command mode can be left by argument "--" which leads
+to generic xorriso command mode. See \fBman xorriso\fR for its description.
+.br
+.PP
+xorriso performs image reading and writing by help of libburn, which is
+mainly intended for optical drives, but also operates on all POSIX
+file types except directories.
+.br
+The program messages call any image file a "drive". File types which are not
+supported for reading are reported as "blank". The reported free media
+space may be quite fictional.
+.br
+Nevertheless xorrisofs does not operate directly on optical drives,
+but rather forces libburn to regard them as general device files.
+So for writing of sequential optical media (CD, DVD-R, DVD+R, BD-R)
+one will have to use a burn program. E.g the cdrecord emulation of xorriso.
+See EXAMPLES.
+.SS
 .br
 .SH OPTIONS
 .br
@@ -139,12 +145,19 @@ by help of option -m.
 .PP
 The following options control loading of an existing ISO image for the purpose
 of preparing a suitable add-on session.
+If they are missing then a new image is composed from scratch.
 .TP
 \fB\-M\fR disk_path
 Set the path from which to load the existing ISO image directory tree
 on which to base the upcomming directory tree as add-on session.
 The path must lead to a random-access readable file object.
 On GNU/Linux: regular data files or block device files.
+.br
+A special kind of pseudo disk_path has the form "/dev/fd/"number.
+It depicts the open file descriptor with the given number, regardless whether
+the operating system supports this feature by file nodes in /dev/fd or not.
+E.g. /dev/fd/3 is file descriptor 3 which was opened by the program that
+later started xorriso.
 .TP
 \fB\-prev-session\fR disk_path
 Alias of -M.
@@ -287,7 +300,13 @@ when image production begins. It may not already exist as directory.
 If it does not exist yet then its parent directory must exist and
 a regular file will get created.
 .br
-Default is stdout which may also be set by disk_path "-".
+A special kind of pseudo disk_path has the form "/dev/fd/"number.
+It depicts the open file descriptor with the given number, regardless whether
+the operating system supports this feature by file nodes in /dev/fd or not.
+E.g. /dev/fd/4 is file descriptor 4 which was opened by the program that
+later started xorriso.
+.br
+Default is standard output (/dev/fd/1) which may also be set by disk_path "-".
 .TP
 \fB\-output\fR disk_path
 Alias of -o.
@@ -1078,7 +1097,7 @@ the image will be created automatically:
 .br
   /datafiles/file1=/home/me/datafile
 .br
-yields in the ISO image
+yields in the ISO image:
 .br
   /datafiles/file1
 .br
@@ -1090,7 +1109,7 @@ But if it must be, one may escape them:
 .br
   /with_\\=_and_\\\\/file=/tmp/directory/file
 .br
-yields in the ISO image
+yields in the ISO image:
 .br
   /with_=_and_\\/file
 .SS