Updated description of -cut_out

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 "February 21, 2008"
+.TH XORRISO 1 "March, 11, 2008"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
@@ -587,16 +587,13 @@ addressing: Its semantics is similar to -add and thus avoids the pitfalls
 inherited from cp -r behavior. Its syntax resembles cp, though.
 .TP
 \fB\-cut_out\fR disk_path byte_offset byte_count iso_rr_path
-WARNING: This option is fewly tested.
-Especially it is not coordinated with -compare_r and -update_r.
-.br
 Map a byte interval of a regular disk file into a regular file in the ISO
 image.
 This may be necessary if the disk file is larger than a single media, or if
 it exceeds the traditional limit of 2 GiB - 2 kiB for old operating systems,
 or the limit of 4 GiB - 2 kiB for newer ones.
 .br
-The clumsy remedy for this limit is to backup file pieces and to concatenate
+A clumsy remedy for this limit is to backup file pieces and to concatenate
 them at restore time. A well tested chopping size is 2047m.
 It is permissible to request a higher byte_count than available. The
 resulting file will be truncated to the correct size of a final piece.
@@ -604,11 +601,37 @@ To request a byte_offset higher than available yields no file in
 the ISO image but a SORRY event.
 E.g:
 .br
--cut_out disk_file 0 2047m iso_rr_part1
+ -cut_out /my/disk/file 0 2047m \\
 .br
--cut_out disk_file 2047m 2047m iso_rr_part2
+ /file/part_1_of_3_at_0_with_2047m_of_5753194821 \\
 .br
--cut_out disk_file 4094m 2047m iso_rr_part3
+ -cut_out /my/disk/file 2047m 2047m \\
+.br
+ /file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \\
+.br
+ -cut_out /my/disk/file 4094m 2047m \\
+.br
+ /file/part_3_of_3_at_4094m_with_2047m_of_5753194821
+.br
+-cut_out is not yet coordinated with -compare_r and -update_r.
+But the names of the part files in this example already follow a
+future convention by which xorriso will be able to recognize
+file parts and process them accordingly:
+.br
+A disk file gets mapped to a ISO directory. Its split parts
+have names which describe the splitting by 5 numbers which are separated
+by some text:
+.br
+part_number, total_parts, byte_offset, byte_count, disk_path_size
+.br
+Scaling characters like "m" or "k" are taken into respect and may
+serve as separators as well. All digits are interpreted as decimal,
+even if leading zeros are present.
+.br
+Not all parts have to be present on the same media. But those parts
+which are present have to sit in the same directory. No other files
+are allowed in there. Parts have to be disjoint. Their numbers have
+to be plausible. byte_count must be valid as -cut_out argument.
 .TP
 \fB\-rm\fR iso_rr_path [***]
 Delete the given files from the ISO image.
@@ -1820,7 +1843,7 @@ versions.
 Theoretical limits are higher but in practice the media deteriorate more early.
 It might also be that your operating system has a session limit with mount.
 Always have a blank media ready to perform a full backup in case the update
-attempt fails.
+attempt fails. An overview of sessions is given by option -toc.
 .br 
 If you have enough re-useable media for a round-robin scheme then better do
 full backups with blank media each time. Blanking can be achieved by