From 87321c252d4e6cb39706792f8d28299554ed1439 Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Fri, 13 May 2011 17:49:28 +0000 Subject: [PATCH] Added a rule to the conversion prescription for man pages --- xorriso/xorrisofs.1 | 444 ++++++++++++++++++++--------------------- xorriso/xorrisofs.texi | 2 + 2 files changed, 224 insertions(+), 222 deletions(-) diff --git a/xorriso/xorrisofs.1 b/xorriso/xorrisofs.1 index d335d25e..6f8185fa 100644 --- a/xorriso/xorrisofs.1 +++ b/xorriso/xorrisofs.1 @@ -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 ...] @@ -32,7 +32,7 @@ xorrisofs - Emulation of ISO 9660 program mkisofs by program xorriso .SH DESCRIPTION .PP \fBxorrisofs\fR -produces Rock Ridge enhanced ISO 9660 filesystems and add-on sessions to +produces Rock Ridge enhanced ISO 9660 filesystems and add\-on sessions to such filesystems. Optionally it can produce Joliet directory trees too. .br .PP @@ -44,7 +44,7 @@ code with cdrtools. \fBISO 9660, Rock Ridge, Joliet:\fR .br \fBISO 9660\fR -(aka \fBECMA-119\fR) is a read-only filesystem that is mainly used for +(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. @@ -64,10 +64,10 @@ Rock Ridge information is produced unconditionally with any xorrisofs image. .br \fBJoliet\fR is the name of an additional directory tree which provides -filenames up to 64 characters encoded as UTF-16. +filenames up to 64 characters encoded as UTF\-16. A Joliet tree is mainly interesting for reading the ISO image by operating systems of Microsoft Corporation. -Production of this directory tree may be enabled by option -J. +Production of this directory tree may be enabled by option \-J. .br \fBISO 9660:1999\fR is the name of an additional directory tree which provides longer @@ -75,7 +75,7 @@ filenames. It allows single file names to have up to 207 characters. It might be of use with some older computer system boot facilities which read neither Rock Ridge nor Joliet but need longer filenames nevertheless. -Production of this directory tree may be enabled by option -iso-level 4. +Production of this directory tree may be enabled by option \-iso\-level 4. .SS .B Inserting files into the ISO image: .PP @@ -92,39 +92,39 @@ confuse with the lowlevel ISO 9660 names visible if Rock Ridge gets ignored.) A program argument is handled as a \fBpathspec\fR, if it is not recognized as original mkisofs option or additional xorrisofs option. A pathspec depicts an input file object by a disk_path. -If option -graft-points is not present, then the behavior depends on the -file type of disk_path. Directories get merged with the /-directory of the -ISO image. Files of other types get copied into the /-directory. +If option \-graft\-points is not present, then the behavior depends on the +file type of disk_path. Directories get merged with the /\-directory of the +ISO image. Files of other types get copied into the /\-directory. .br -If -graft-points is present then each pathspec gets split at the first -occurence of the =-character. +If \-graft\-points is present then each pathspec gets split at the first +occurence of the =\-character. The part before the = is taken as \fBtarget\fR, i.e. the iso_rr_path for the file object in the ISO image. The part after the first = is taken as \fBsource\fR, i.e. the disk_path of the input object. .br -It is possible to make =-characters part of the iso_rr_path by preceeding -them with a \\-character. The same must be done for \\-characters which +It is possible to make =\-characters part of the iso_rr_path by preceding +them with a \\\-character. The same must be done for \\\-characters which shall be part of the iso_rr_path. .br .PP If the source part of the pathspec leads to a directory, then all files underneath this directory get inserted into the image, too. It is possible to exclude particular files from being inserted -by help of option -m. +by help of option \-m. .br In case that target already exists, the following rules apply: -Directories and other files may overwrite existing non-directories. +Directories and other files may overwrite existing non\-directories. Directories get merged with existing directories. -Non-directories may not overwrite existing directories. +Non\-directories may not overwrite existing directories. .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 +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 +This command mode can be left by argument "\-\-" which leads to generic xorriso command mode. See \fBman xorriso\fR for its description. .br .PP @@ -138,7 +138,7 @@ 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) +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 @@ -150,13 +150,13 @@ See EXAMPLES. .B Image loading: .PP The following options control loading of an existing ISO image for the purpose -of preparing a suitable add-on session. +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 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. @@ -166,48 +166,48 @@ 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. +Alias of \-M. .TP \fB\-dev\fR disk_path -Alias of -M. +Alias of \-M. .TP \fB\-C\fR last_session_start,next_writeable_address Set the 2 KiB block address last_session_start from where to read the -ISO image out of the file given by option -M. +ISO image out of the file given by option \-M. .br Separated by a comma, set the next_writeable_address to which the -add-on session will finally be written. Decisive is actually the block +add\-on session will finally be written. Decisive is actually the block address which the intended readers will have to use as superblock address on the intended media. .br Both values can be inquired from optical media by help of burn programs -and cdrecord option -msinfo. xorriso itself can obtain it in its +and cdrecord option \-msinfo. xorriso itself can obtain it in its cdrecord emulation. Do not let it load the drive, but rather do this manually or by a program like dd which reads a few bytes. Only then it is sure that the device driver knows the true readable size of the media. .br dd if=/dev/... count=1 >/dev/null 2>&1 .br - values=$(xorriso -as cdrecord dev=/dev/... -msinfo) + values=$(xorriso \-as cdrecord dev=/dev/... \-msinfo) .br echo $values .br -Option -C may be used without option -M to create an ISO image from +Option \-C may be used without option \-M to create an ISO image from scratch and prepare it for being finally written to a block address other than 0. Parameter last_session_start must then be set to 0. .TP \fB\-cdrecord-params\fR last_session_start,next_writeable_address -Alias of -C. +Alias of \-C. .TP .B Settings for file insertion: .TP \fB\-path-list\fR disk_path -Read pathspecs line-by-line from disk_file and insert the depicted file -objects into the ISO image. If disk_path is "-" then read the pathspecs +Read pathspecs line\-by\-line from disk_file and insert the depicted file +objects into the ISO image. If disk_path is "\-" then read the pathspecs from standard input. .TP \fB--quoted_path_list\fR disk_path -Like option -path-list but reading quoted words rather than plain lines. +Like option \-path\-list but reading quoted words rather than plain lines. Whitespace outside of quotes will be discarded. On the other hand it is possible to represent pathspecs which contain newline characters. .br @@ -222,32 +222,32 @@ Resolve symbolic links on disk rather than storing them as symbolic links in the ISO image. .TP \fB\-follow-links\fR -Alias of -f. +Alias of \-f. .TP \fB\-graft-points\fR Enable interpretation of input file pathspecs as combination of iso_rr_path -and disk_path, separated by a =-character. +and disk_path, separated by a =\-character. .TP \fB\-m\fR disk_pattern Exclude files from being inserted into the image. Silently ignored are those files of which the disk_path matches the given shell parser pattern. -If no /-character is part of the pattern, then it gets matched against +If no /\-character is part of the pattern, then it gets matched against the leaf name of the disk file. .br -It is possible to give more than one -m option. +It is possible to give more than one \-m option. .TP \fB\-exclude\fR -Alias of -m. +Alias of \-m. .TP \fB\-x\fR .br -Alias of -m. +Alias of \-m. .TP \fB\-old-exclude\fR -Alias of -m. +Alias of \-m. .TP \fB\-exclude-list\fR disk_path -Perform -m using each line out of file disk_path as argument disk_pattern. +Perform \-m using each line out of file disk_path as argument disk_pattern. .TP \fB\-z\fR .br @@ -257,13 +257,13 @@ necessary meta data so that a Linux kernel will recognize them and deliver their content in uncompressed form. .TP \fB\-transparent-compression\fR -Alias of -z. +Alias of \-z. .TP \fB\-root\fR iso_rr_path -Insert all files under the given iso_rr_path. If option -graft-points is given, +Insert all files under the given iso_rr_path. If option \-graft\-points is given, then iso_rr_path is prepended to each target part of a pathspec. .br -The default for -root is "/". +The default for \-root is "/". .TP \fB\-old-root\fR iso_rr_path Enable incremental insertion of files into the loaded image. @@ -274,13 +274,13 @@ New files and files with changed content will get newly added. Target files which do not exist in any of the according pathspec sources will get removed from the ISO directory tree. .br -If the effective setting of -root differs from the iso_rr_path given -with -old-root, then the files underneath the -old-root directory get cloned -underneath the -root directory. Cloning happens before file comparison. +If the effective setting of \-root differs from the iso_rr_path given +with \-old\-root, then the files underneath the \-old\-root directory get cloned +underneath the \-root directory. Cloning happens before file comparison. .TP \fB--old-root-no-ino\fR Disable recording and use of disk inode numbers. -If no disk inode numbers are recorded, then option -old-root will have +If no disk inode numbers are recorded, then option \-old\-root will have to read disk file content and compare it with the MD5 checksum that is recorded in the ISO image. .br @@ -289,8 +289,8 @@ it is possible to detect potential changes in the content without actually reading it. A loophole remains if multiple different filesystems may get mounted at the same directory, like it is habit with /mnt. -In this case one has to use option --old-root-devno -or disable the inode number shortcut by --old-root-no-ino. +In this case one has to use option \-\-old\-root\-devno +or disable the inode number shortcut by \-\-old\-root\-no\-ino. .TP \fB--old-root-devno\fR Enable comparison of recorded device numbers together with recorded @@ -302,7 +302,7 @@ files as changed and thus prevent any incremental size saving. \fB--old-root-no-md5\fR Disable recording and eventual use of MD5 checksums for data file content. If neither checksums and nor disk inode numbers are recorded, then -option -old-root will have to read ISO image file content when comparing +option \-old\-root will have to read ISO image file content when comparing it with disk file content. .TP .B Settings for image production: @@ -320,10 +320,10 @@ 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 "-". +Default is standard output (/dev/fd/1) which may also be set by disk_path "\-". .TP \fB\-output\fR disk_path -Alias of -o. +Alias of \-o. .TP \fB--stdio_sync\fR "on"|"off"|number Set the number of bytes after which to force output to disk @@ -336,16 +336,16 @@ the operating system i/o cache to disk does not necessarily block the simultaneous production of more image content. .TP \fB--emul-toc\fR -Write a second superblock with the first session into random-access +Write a second superblock with the first session into random\-access files. If further sessions get appended and the first superblock gets updated, then the second superblock will not be overwritten. This allows to still mount the first session and to find the start blocks of the further sessions. .br -The price is 64 KiB extra space consumption. If -partition_offset is non-zero, +The price is 64 KiB extra space consumption. If \-partition_offset is non\-zero, then it is 128 KiB plus twice the partition setup. .TP \fB--no-emul-toc\fR -Do not write a second superblock with the first session into random-access +Do not write a second superblock with the first session into random\-access files. .br This is the default. @@ -354,7 +354,7 @@ This is the default. Attribute a LBA weight number to regular files. If iso_rr_path leads to a directory then all regular files underneath will get the weight_number. .br -The weight_number may range from -2147483648 to 2147483647. +The weight_number may range from \-2147483648 to 2147483647. The higher it is, the lower will be the block address of the file data in the emerging ISO image. Currently the El Torito boot catalog has a hardcoded weight of 1 billion. @@ -364,19 +364,19 @@ Data files get added or loaded with initial weight 0. \fB\-dir-mode\fR mode Set the access permissions for all directories in the image to the given mode which is either an octal number beginning with "0" or a comma separated -list of statements of the form [ugoa]*[+-=][rwxst]* . E.g. ug=rx,a-rwx +list of statements of the form [ugoa]*[+\-=][rwxst]* . E.g. ug=rx,a\-rwx .TP \fB\-file-mode\fR mode -Like -dir-mode but for all regular data files in the image. +Like \-dir\-mode but for all regular data files in the image. .TP \fB\-pad\fR .br Add 300 KiB to the end of the produced ISO image. This circumvents possible read errors from ISO images which have been written to CD media in TAO mode. -The additional bytes are claimed as part of the ISO image if not --emul-toc +The additional bytes are claimed as part of the ISO image if not \-\-emul\-toc is given. .br -Option -pad is the default. +Option \-pad is the default. .TP \fB\-no-pad\fR Disable padding of 300 KiB to the end of the produced ISO image. @@ -393,20 +393,20 @@ a dedicated block to which all such files will point. \fB\-iso-level\fR number Specify the ISO 9660 version which defines the limitations of file naming and data file size. The naming restrictions do not apply to the -Rock Ridge names but only to the low-level ISO 9660 names. +Rock Ridge names but only to the low\-level ISO 9660 names. There are three conformance levels: .br -Level 1 allows ISO names of the form 8.3 and file size up to 4 GiB - 1. +Level 1 allows ISO names of the form 8.3 and file size up to 4 GiB \- 1. .br Level 2 allows ISO names with up to 32 characters -and file size up to 4 GiB - 1. +and file size up to 4 GiB \- 1. .br Level 3 allows ISO names with up to 32 characters -and file size of up to 400 GiB - 200 KiB. (This size limitation is +and file size of up to 400 GiB \- 200 KiB. (This size limitation is set by the xorriso implementation and not by ISO 9660 which would allow nearly 8 TiB.) .br -Pseudo-level 4 enables production of an additional ISO 9660:1999 +Pseudo\-level 4 enables production of an additional ISO 9660:1999 directory tree. .TP \fB\-disallow_dir_id_ext\fR @@ -424,7 +424,7 @@ of ISO names. This all violates ISO 9660 specs. .TP \fB\-untranslated-filenames\fR -Alias of -U. +Alias of \-U. \fB\-untranslated_name_len\fR number Allow ISO file names up to the given number of characters without any character conversion. The maximum number is 96. @@ -445,7 +445,7 @@ Do not add trailing dot to ISO file names without dot. This violates ISO 9660 specs. .TP \fB\-omit-period\fR -Alias of -d. +Alias of \-d. .TP \fB\-l\fR .br @@ -454,10 +454,10 @@ Allow up to 37 characters in ISO file names. This violates ISO 9660 specs. .TP \fB\-full-iso9660-filenames\fR -Alias of -l. +Alias of \-l. .TP \fB\-max-iso9660-filenames\fR -Alias of -l. +Alias of \-l. .TP \fB\-N\fR .br @@ -466,7 +466,7 @@ Omit the semicolon and the version numbers at the end of ISO names. This violates ISO 9660 specs. .TP \fB\-omit-version-number\fR -Alias of -N. +Alias of \-N. .TP .B Settings for standards extensions: .TP @@ -477,22 +477,22 @@ them unconditionally. .TP \fB\-rock\fR .br -Alias of -R. +Alias of \-R. .TP \fB\-r\fR .br Set Rock Ridge user and group id of all files in the ISO image to 0. -Grant r-permissions to all. Deny all w-permissions. -If any x-permission is set, grant x-permission to all. -Remove s-bit and t-bit. +Grant r\-permissions to all. Deny all w\-permissions. +If any x\-permission is set, grant x\-permission to all. +Remove s\-bit and t\-bit. .TP \fB\-rational-rock\fR -Alias of -r. +Alias of \-r. .TP \fB--for_backup\fR Enable options which improve backup fidelity: ---acl, --xattr, --md5, ---hardlinks. +\-\-acl, \-\-xattr, \-\-md5, +\-\-hardlinks. .TP \fB--acl\fR .br @@ -512,10 +512,10 @@ restore them when extracting files from the ISO image. Enable recording of MD5 checksums for the overall ISO image and for each single data file in the image. xorriso can check the content of an ISO image with these sums and eventually raise alert on mismatch. -See man xorriso, options -check_media, check_md5_r. +See man xorriso, options \-check_media, check_md5_r. xorriso can print recorded MD5 checksums. E.g. by: .br - -find / -exec get_md5 + \-find / \-exec get_md5 .TP \fB--hardlinks\fR Enable loading and recording of hardlink relations. @@ -529,7 +529,7 @@ the ISO image. .TP \fB--scdbackup_tag\fR disk_path record_name Append a scdbackup checksum record to the image. This works only if the -parameter next_writeable_address of option -C is 0. +parameter next_writeable_address of option \-C is 0. If disk_path is not an empty string, then append a scdbackup checksum record to the end of this file. record_name is a word that gets part of tag and record. @@ -542,7 +542,7 @@ Enable the production of an additional Joliet directory tree along with the ISO 9660 Rock Ridge tree. .TP \fB\-joliet\fR -Alias of -J. +Alias of \-J. .TP \fB\-joliet-long\fR Allow 103 characters in Joliet file names rather than 64 as is prescribed @@ -564,15 +564,15 @@ But you will need own means to find nameless data in the image. This command does not apply to the boot catalog. .TP \fB\-hide-list\fR disk_path -Perform -hide using each line out of file disk_path as argument +Perform \-hide using each line out of file disk_path as argument disk_path_pattern. .TP \fB\-hide-joliet\fR disk_path_pattern -Like option -hide but making files invisible in the directory tree of Joliet, +Like option \-hide but making files invisible in the directory tree of Joliet, if their disk_path matches the given shell parser pattern. .TP \fB\-hide-joliet-list\fR disk_path -Perform -hide-joliet using each line out of file disk_path as argument +Perform \-hide\-joliet using each line out of file disk_path as argument disk_path_pattern. .TP .B ISO image ID strings: @@ -580,7 +580,7 @@ disk_path_pattern. The following strings and file addresses get stored in the Primary Volume Descriptor of the ISO9660 image. The file addresses are ISO 9660 paths. These files should have iso_rr_paths which consist only of -the characters [A-Z0-9_] and exactly one dot which separates +the characters [A\-Z0\-9_] and exactly one dot which separates at most 8 characters from at most 3 characters. .TP \fB\-V\fR text @@ -588,15 +588,15 @@ Set the Volume Id of the ISO image. xorriso accepts any text up to 32 characters, but according to rarely obeyed specs stricter rules apply: .br -Conformant are ASCII characters out of [A-Z0-9_]. Like: "IMAGE_23" +Conformant are ASCII characters out of [A\-Z0\-9_]. Like: "IMAGE_23" .br -Joliet allows 16 UCS-2 characters. Like: "Windows name" +Joliet allows 16 UCS\-2 characters. Like: "Windows name" .br Be aware that the volume id might get used automatically as name of the mount point when the media is inserted into a playful computer system. .TP \fB\-volid\fR text -Alias of -V. +Alias of \-V. .TP \fB\-volset\fR text Set the Volume Set Id of the ISO image. @@ -608,7 +608,7 @@ organisation who specified what shall be recorded. Permissible are up to 128 characters. .TP \fB\-publisher\fR text -Alias of -p. +Alias of \-p. .TP \fB\-A\fR text Set the Application Id of the ISO image. @@ -620,7 +620,7 @@ which is normally written as Preparer Id. It is a wrong tradition to write the program id as Application Id. .TP \fB\-appid\fR text -Alias of -A. +Alias of \-A. .TP \fB\-sysid\fR text Set the System Id of the ISO image. This may @@ -639,7 +639,7 @@ The special text "@xorriso@" gets converted to the id string of xorriso which is default at program startup. .TP \fB\-preparer\fR text -Alias of -p. +Alias of \-p. .TP \fB\-abstract\fR iso_path Set the address of the Abstract File of the ISO image. This should @@ -666,7 +666,7 @@ It must consist of 16 decimal digits which form YYYYMMDDhhmmsscc, with YYYY between 1970 and 2999. Time zone is GMT. It is supposed to match this GRUB line: .br - search --fs-uuid --set YYYY-MM-DD-hh-mm-ss-cc + search \-\-fs\-uuid \-\-set YYYY\-MM\-DD\-hh\-mm\-ss\-cc .br E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds). .TP @@ -688,19 +688,19 @@ the ISO image. The content of the boot image files is not in the scope of El Torito. .br xorriso composes the boot catalog according to the boot image -files given and structured by options -b, -e, -el-torito-alt-boot, -and --efi-boot. Often it contains only one entry. +files given and structured by options \-b, \-e, \-el\-torito\-alt\-boot, +and \-\-efi\-boot. Often it contains only one entry. .br -El Torito gets interpreted by boot facilities PC-BIOS and EFI. +El Torito gets interpreted by boot facilities PC\-BIOS and EFI. Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images -for PC-BIOS. +for PC\-BIOS. .br xorrisofs supports the example options out of the ISOLINUX wiki, -the options used in GRUB script grub-mkrescue, and the example in the +the options used in GRUB script grub\-mkrescue, and the example in the FreeBSD AvgLiveCD wiki. .br .PP -For CD booting via boot facilities other than PC-BIOS and EFI, and +For CD booting via boot facilities other than PC\-BIOS and EFI, and for booting from USB sticks or hard disks, see the next section about the Sytem Area. .br @@ -708,18 +708,18 @@ about the Sytem Area. \fB\-b\fR iso_rr_path Specify the boot image file which shall be mentioned in the current entry of the El Torito boot catalog. It will be marked as suitable for -PC-BIOS. +PC\-BIOS. .br With boot images from ISOLINUX and GRUB this option should be accompanied by -options -c , -no-emul-boot , -boot-load-size 4 , -boot-info-table. +options \-c , \-no\-emul\-boot , \-boot\-load\-size 4 , \-boot\-info\-table. .TP \fB\-eltorito-boot\fR iso_rr_path -Alias of -b. +Alias of \-b. .TP \fB\-eltorito-alt-boot\fR Finalize the current El Torito boot catalog entry and begin a new one. A boot image file and all its necessary options shall be specified before -option -eltorito-alt-boot. +option \-eltorito\-alt\-boot. All further El Torito boot options apply to the new catalog entry. Up to 32 catalog entries are possible. .TP @@ -729,16 +729,16 @@ entry of the El Torito boot catalog. It will be marked as suitable for EFI. .br Normally no other El Torito options should be used with the catalog entry that points to an EFI image. -Consider to use --efi-boot rather than -e. +Consider to use \-\-efi\-boot rather than \-e. .TP \fB--efi-boot\fR iso_rr_path -Perform eventual necessary -eltorito-alt-boot, option -e with the given -iso_rr_path, and again -eltorito-alt-boot. This gesture is -used for achieving EFI-bootability of the GRUB2 rescue CD. +Perform eventual necessary \-eltorito\-alt\-boot, option \-e with the given +iso_rr_path, and again \-eltorito\-alt\-boot. This gesture is +used for achieving EFI\-bootability of the GRUB2 rescue CD. .TP \fB\-boot-load-size\fR number -Set the number of 512-byte blocks for boot images which emulate -a floppy or a hard disk. A safe default for non-emulating boot images is 4. +Set the number of 512\-byte blocks for boot images which emulate +a floppy or a hard disk. A safe default for non\-emulating boot images is 4. .TP \fB\-hard-disk-boot\fR Mark the boot image in the current catalog entry as emulated hard disk. @@ -748,7 +748,7 @@ Mark the boot image in the current catalog entry as emulated hard disk. Mark the boot image in the current catalog entry as not emulating floppy or hard disk. (This is to be used with all known boot loaders.) .br -If neither -hard-disk-boot nor -no-emul-boot is given, then the +If neither \-hard\-disk\-boot nor \-no\-emul\-boot is given, then the boot image will be marked as emulating a floppy. (Not suitable for any known boot loader.) .TP @@ -760,12 +760,12 @@ size of the boot image file. .TP \fB\-c\fR iso_rr_path Set the address of the El Torito boot catalog file within the image. -This file address is not significant for the booting PC-BIOS or EFI, +This file address is not significant for the booting PC\-BIOS or EFI, but it may later be read by other programs in order to learn about the available boot images. .TP \fB\-eltorito-catalog\fR iso_rr_path -Alias of -c. +Alias of \-c. .TP \fB--boot-catalog-hide\fR Prevent the El Torito boot catalog from appearing as file @@ -776,12 +776,12 @@ in the directory trees of the image. The first 16 blocks of an ISO image are the System Area. It is reserved for system dependent boot software. This may be the CD boot facilities of exotic hardware architectures or it may be -a MBR for booting via PC-BIOS from USB stick or hard disk. +a MBR for booting via PC\-BIOS from USB stick or hard disk. .br A \fBMBR\fR (Master Boot Record) contains boot code and a partition table. It does not hamper El Torito booting from CDROM. .br -xorrisofs supports boot facilities other than PC-BIOS: +xorrisofs supports boot facilities other than PC\-BIOS: MIPS Big Endian (SGI), MIPS Little Endian (DEC), SUN SPARC. Those are mutually not combinable and also not combinable with MBR. .br @@ -794,32 +794,32 @@ Other than a El Torito boot image, the file disk_path needs not to be added to the ISO image. It will not show up as file in the directory trees. .TP \fB\-generic-boot\fR disk_path -Alias of -G. +Alias of \-G. .TP \fB--embedded-boot\fR disk_path -Alias of -G. +Alias of \-G. .TP \fB\-isohybrid-mbr\fR disk_path Install disk_path as ISOLINUX isohybrid MBR which makes the boot image -given by option -b bootable from USB sticks and hard disks via PC-BIOS. +given by option \-b bootable from USB sticks and hard disks via PC\-BIOS. This preparation is normally done by ISOLINUX program isohybrid on the already produced ISO image. .br The disk path should lead to one of the Syslinux files isohdp[fp]x*.bin . The MBR gets patched according to isohybrid needs. The first partition describes the range of the ISO image. Its start is at block 0 by default, -but may be set to 64 disk blocks by option -partition_offset 16. +but may be set to 64 disk blocks by option \-partition_offset 16. .TP \fB--protective-msdos-label\fR -Patch the System Area by a simple PC-DOS partition table where partition 1 +Patch the System Area by a simple PC\-DOS partition table where partition 1 claims the range of the ISO image but leaves the first block unclaimed. .TP \fB\-partition_offset\fR 2kb_block_adr Cause a partition table with a single partition that begins at the given block address. This is counted in 2048 byte -blocks, not in 512 byte blocks. If the block address is non-zero then it must +blocks, not in 512 byte blocks. If the block address is non\-zero then it must be at least 16. Values larger than 16 are hardly of use. -A non-zero partition offset causes two superblocks to be +A non\-zero partition offset causes two superblocks to be generated and two sets of directory trees. The image is then mountable from its absolute start as well as from the partition start. .br @@ -850,10 +850,10 @@ Cylinder size must be divisible by 2048. Images larger than 8,323,596,288 bytes cannot be aligned. .br Mode "auto" is default. Alignment by padding happens only if -option -isohybrid-mbr is given. +option \-isohybrid\-mbr is given. .br Mode "on" causes alignment by padding with option ---protective-msdos-label too. +\-\-protective\-msdos\-label too. Mode "off" disables alignment unconditionally. .TP \fB\-append_partition\fR partition_number type_code disk_path @@ -862,7 +862,7 @@ described by a partition table entry in a boot block at the start of the emerging ISO image. The partition entry will bear the size of the submitted file rounded up to the next multiple of 2048 bytes. .br -Beware of subsequent multi-session runs. The appended partition will get +Beware of subsequent multi\-session runs. The appended partition will get overwritten. .br partition_number may be 1 to 4. Number 1 will put the whole ISO image into @@ -879,16 +879,16 @@ Declare a data file in the image to be a MIPS Big Endian boot file and cause production of a MIPS Big Endian Volume Header. This is mutually exclusive with production of other boot blocks like MBR. -It will overwrite the first 512 bytes of any data eventually provided by -G. -Up to 15 boot files can be declared by multiple -mips-boot options. +It will overwrite the first 512 bytes of any data eventually provided by \-G. +Up to 15 boot files can be declared by multiple \-mips\-boot options. .TP \fB\-mipsel-boot\fR iso_rr_path Declare a data file in the image to be the MIPS Little Endian boot file. This is mutually exclusive with other boot blocks. It will overwrite the first 512 bytes of any data eventually -provided by -G. -Only a single boot file can be declared by -mipsel-boot. +provided by \-G. +Only a single boot file can be declared by \-mipsel\-boot. .TP \fB\-B\fR disk_path[,disk_path ...] Cause one or more data files on disk to be written after the end of the @@ -899,12 +899,12 @@ partition 2 up to 8. The disk files should contain suitable boot images for SUN SPARC systems. .br The pseudo disk_path "..." causes that all empty partition entries become -copies of the last non-empty entry. If no other disk_path is given before +copies of the last non\-empty entry. If no other disk_path is given before "..." then all partitions describe the ISO image. In this case, the boot -loader code has to be imported by option -G. +loader code has to be imported by option \-G. .TP \fB\-sparc-boot\fR disk_path[,disk_path ...] -Alias of -B. +Alias of \-B. .TP \fB\-sparc-label\fR text Set the ASCII label text of a SUN Disk Label. @@ -921,7 +921,7 @@ A conversion from input character set to the output character set is performed when an ISO image gets written. Vice versa there is a conversion from output character set to the input character set when an ISO image gets loaded. -The sets can be defined by options -input-charset and -output-charset, +The sets can be defined by options \-input\-charset and \-output\-charset, if needed. .br .TP @@ -943,12 +943,12 @@ end users to download them more efficiently." .br If the use of libjte was enabled at compile time of xorriso, then xorrisofs can produce a .jigdo and a .template file together with a -single-session ISO image. If not, then Jigdo options will cause a +single\-session ISO image. If not, then Jigdo options will cause a FAILURE event, which normally leads to program abort. .br One may determine the ability for Jigdo by: .br - $ xorrisofs -version 2>&1 | grep '^libjte' && echo YES + $ xorrisofs \-version 2>&1 | grep '^libjte' && echo YES .br .PP The .jigdo file contains checksums and symbolic file addresses. @@ -993,7 +993,7 @@ GiB (1024 MiB). adds a regular expression pattern which will get compared with the absolute disk_path of any data file that was not found in the .md5 list. A match causes a MISHAP event, which normally does not abort the -program run but finally causes a non-zero exit value of the program. +program run but finally causes a non\-zero exit value of the program. .TP \fB\-jigdo-exclude\fR disk_path_pattern Add a regular expression pattern which will get compared @@ -1024,7 +1024,7 @@ Note that MD5 stays always enabled. .TP \fB\-checksum_algorithm_template\fR list_of_names Choose the algorithms for the "# Template Hex" checksums in the .jigdo file. -The rules for list_of_names are the same as with -checksum_algorithm_iso. +The rules for list_of_names are the same as with \-checksum_algorithm_iso. .TP .B Miscellaneous options: .TP @@ -1034,8 +1034,8 @@ the emerging ISO image. Do not produce this image. .br The result depends on several settings. .br -If option --emul-toc is given, then padding (see -pad) is not -counted as part of the image size. In this case either use -no-pad or +If option \-\-emul\-toc is given, then padding (see \-pad) is not +counted as part of the image size. In this case either use \-no\-pad or add 150 (= 300 KiB) to the resulting number. .TP \fB--no_rc\fR @@ -1058,12 +1058,12 @@ problems or errors. Enable the output of informational program messages. .TP \fB\-verbose\fR -Alias of -v. +Alias of \-v. .TP \fB\-version\fR Print to standard output a text that begins with .br - "mkisofs 2.01-Emulation Copyright (C)" + "mkisofs 2.01\-Emulation Copyright (C)" .br and to standard error the version information of xorriso. .br @@ -1087,17 +1087,17 @@ Create bootable images for PC-BIOS .SS .B A simple image production run A prepared file tree in directory ./for_iso gets copied into the root -directory of the ISO image. File permissions get set to read-only for +directory of the ISO image. File permissions get set to read\-only for everybody. Joliet attributes for Microsoft systems get added. The resulting image gets written as data file ./image.iso on disk. .br - $ xorrisofs -r -J -o ./image.iso ./for_iso + $ xorrisofs \-r \-J \-o ./image.iso ./for_iso .SS .B Set ISO image paths by -graft-points -Without option -graft-points each given disk file is copied into the root +Without option \-graft\-points each given disk file is copied into the root directory of the ISO image, maintaining its name. If a directory is given, -then its files and sub-directories are copied into the root directory, +then its files and sub\-directories are copied into the root directory, maintaining their names. .br $ xorrisofs ... /home/me/datafile /tmp/directory @@ -1113,10 +1113,10 @@ yields in the ISO image root directory: /file_N_from_directory .br .sp 1 -With option -graft-points it is possible to put files and directories to +With option \-graft\-points it is possible to put files and directories to arbitrary paths in the ISO image. .br - $ xorrisofs ... -graft-points /home/me/datafile /dir=/tmp/directory + $ xorrisofs ... \-graft\-points /home/me/datafile /dir=/tmp/directory .br yields in the ISO image root directory: .br @@ -1146,31 +1146,31 @@ yields in the ISO image: /with_=_and_\\/file .SS .B Perform multi-session runs -This example works for multi-session media only: -CD-R[W], DVD-R[W], DVD+R, BD-R. -Add cdrskin option --grow_overwriteable_iso -to all -as cdrecord runs -in order to enable multi-session emulation on overwriteable media. +This example works for multi\-session media only: +CD\-R[W], DVD\-R[W], DVD+R, BD\-R. +Add cdrskin option \-\-grow_overwriteable_iso +to all \-as cdrecord runs +in order to enable multi\-session emulation on overwriteable media. .br The first session is written like this: .br - $ xorrisofs -graft-points \\ + $ xorrisofs \-graft\-points \\ .br /tree1=prepared_for_iso/tree1 \\ .br - | xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject - + | xorriso \-as cdrecord \-v dev=/dev/sr0 blank=fast \-multi \-eject \- .br -Follow-up sessions are written like this: +Follow\-up sessions are written like this: .br $ dd if=/dev/sr0 count=1 >/dev/null 2>&1 .br - $ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo) + $ m=$(xorriso \-as cdrecord dev=/dev/sr0 \-msinfo) .br - $ xorrisofs -M /dev/sr0 -C $m -graft-points \\ + $ xorrisofs \-M /dev/sr0 \-C $m \-graft\-points \\ .br /tree2=prepared_for_iso/tree2 \\ .br - | xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject - + | xorriso \-as cdrecord \-v dev=/dev/sr0 \-waiti \-multi \-eject \- .br Always eject the drive tray between sessions. The old sessions get read via /dev/sr0. Its device driver might not be aware @@ -1178,40 +1178,40 @@ of the changed content before it loads the media again. In this case the previous session would not be loaded and the new session would contain only the newly added files. .br -For the same reason do not let xorriso -as cdrecord load the media, +For the same reason do not let xorriso \-as cdrecord load the media, but rather do this manually or by a program that reads from /dev/sr0. .SS .B Let xorrisofs work underneath growisofs -growisofs expects an ISO formatter program which understands options -C and --M. A variable is defined to override the hardcoded default name. +growisofs expects an ISO formatter program which understands options \-C and +\-M. A variable is defined to override the hardcoded default name. .br $ export MKISOFS="xorrisofs" .br - $ growisofs -Z /dev/dvd /some/files + $ growisofs \-Z /dev/dvd /some/files .br - $ growisofs -M /dev/dvd /more/files + $ growisofs \-M /dev/dvd /more/files .br If no "xorrisofs" is available on your system, then you will have to create a link pointing to the xorriso binary and tell growisofs to use it. E.g. by: .br - $ ln -s $(which xorriso) "$HOME/xorrisofs" + $ ln \-s $(which xorriso) "$HOME/xorrisofs" .br $ export MKISOFS="$HOME/xorrisofs" .br -One may quit mkisofs emulation by argument "--" and make +One may quit mkisofs emulation by argument "\-\-" and make use of all xorriso commands. growisofs dislikes options which -start with "-o" but -outdev must be set to "-". +start with "\-o" but \-outdev must be set to "\-". So use "outdev" instead: .br - $ growisofs -Z /dev/dvd --for_backup -- \\ + $ growisofs \-Z /dev/dvd \-\-for_backup \-\- \\ .br - outdev - -update_r /my/files /files + outdev \- \-update_r /my/files /files .br - $ growisofs -M /dev/dvd --for_backup -- \\ + $ growisofs \-M /dev/dvd \-\-for_backup \-\- \\ .br - outdev - -update_r /my/files /files + outdev \- \-update_r /my/files /files .br -Note that --for_backup is given in the mkisofs emulation. +Note that \-\-for_backup is given in the mkisofs emulation. To preserve the recorded extra data it must already be in effect, when the emulation loads the image. .SS @@ -1232,35 +1232,35 @@ the two disk trees to the media is desired. Begin with blank media and start a new blank media when the run fails due to lack of remaining space on the old one. .br -Do not let xorriso -as cdrecord load the media, +Do not let xorriso \-as cdrecord load the media, but rather do this manually or by a program that reads from /dev/sr0. .br $ dd if=/dev/sr0 count=1 >/dev/null 2>&1 .br - $ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo) + $ msinfo=$(xorriso \-as cdrecord dev=/dev/sr0 \-msinfo) .br $ load_opts= .br - $ test -n "$msinfo" && load_opts="-M /dev/sr0 -C $msinfo" + $ test \-n "$msinfo" && load_opts="\-M /dev/sr0 \-C $msinfo" .br - $ xorrisofs $load_opts -o - --for_backup -m '*.o' -m '*.swp' \\ + $ xorrisofs $load_opts \-o \- \-\-for_backup \-m '*.o' \-m '*.swp' \\ .br - -V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \\ + \-V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \-graft\-points \\ .br - -old-root / \\ + \-old\-root / \\ .br /projects=/home/thomas/projects \\ .br /personal_mail=/home/thomas/personal_mail \\ .br - | xorriso -as cdrecord dev=/dev/sr0 -v -multi -waiti -eject - + | xorriso \-as cdrecord dev=/dev/sr0 \-v \-multi \-waiti \-eject \- .br .sp 1 This makes sense if the full backup leaves substantial remaining capacity on media and if the expected changes are much smaller than the full backup. .br .sp 1 -\fBBetter do not use your youngest backup for -old-root\fR. +\fBBetter do not use your youngest backup for \-old\-root\fR. Have at least two media which you use alternatingly. So only older backups get endangered by the new write operation, while the newest backup is stored safely on a different media. @@ -1269,7 +1269,7 @@ attempt fails due to insufficient remaining capacity. .br .sp 1 If inode numbers on disk are not persistent, then use -option --old-root-no-ino . +option \-\-old\-root\-no\-ino . In this case an update run will compare recorded MD5 sums against the current file content on hard disk. .br @@ -1280,81 +1280,81 @@ it is possible to access the session trees which represent the older backup versions. With CD media, GNU/Linux mount accepts session numbers directly by its option "session=". .br -Multi-session media and most overwriteable media written by xorriso can tell -the sbsectors of their sessions by xorriso option -toc: +Multi\-session media and most overwriteable media written by xorriso can tell +the sbsectors of their sessions by xorriso option \-toc: .br - $ xorriso -dev /dev/sr0 -toc + $ xorriso \-dev /dev/sr0 \-toc .br xorriso can print the matching mount command for a session number: .br - $ xorriso -mount_cmd /dev/sr0 session 12 /mnt + $ xorriso \-mount_cmd /dev/sr0 session 12 /mnt .br or for a volume id that matches a search expression: .br - $ xorriso -mount_cmd /dev/sr0 volid '*2008_12_05*' /mnt + $ xorriso \-mount_cmd /dev/sr0 volid '*2008_12_05*' /mnt .br Both yield on standard output something like: .br - mount -t iso9660 -o nodev,noexec,nosuid,ro,sbsector=1460256 '/dev/sr0' '/mnt' + mount \-t iso9660 \-o nodev,noexec,nosuid,ro,sbsector=1460256 '/dev/sr0' '/mnt' .br The superuser may let xorriso execute the mount command directly: .br - # osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt + # osirrox \-mount /dev/sr0 "volid" '*2008_12_05*' /mnt .SS .B Incremental backup with accumulated trees Solaris does not offer the option to mount older sessions. In order to keep them accessible, one may map all files to a file tree under a session directory and accumulate those directories from session to session. -The -root tree is cloned from the -old-root tree before it gets +The \-root tree is cloned from the \-old\-root tree before it gets compared with the appropriate trees on disk. .br This demands to know the previously used session directory name. .br With the first session: .br - $ xorrisofs -root /session1 \\ + $ xorrisofs \-root /session1 \\ .br - -o - --for_backup -m '*.o' -m '*.swp' \\ + \-o \- \-\-for_backup \-m '*.o' \-m '*.swp' \\ .br - -V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \\ + \-V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \-graft\-points \\ .br /projects=/home/thomas/projects \\ .br /personal_mail=/home/thomas/personal_mail \\ .br - | xorriso -as cdrecord dev=/dev/sr0 -v blank=as_needed \\ + | xorriso \-as cdrecord dev=/dev/sr0 \-v blank=as_needed \\ .br - -multi -waiti -eject - + \-multi \-waiti \-eject \- .br .sp 1 -With the second session, option -old-root refers to /session1 and the -new -root is /session2. +With the second session, option \-old\-root refers to /session1 and the +new \-root is /session2. .br -Do not let xorriso -as cdrecord load the media, +Do not let xorriso \-as cdrecord load the media, but rather do this manually or by a program that reads from /dev/sr0. .br $ dd if=/dev/sr0 count=1 >/dev/null 2>&1 .br - $ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo) + $ msinfo=$(xorriso \-as cdrecord dev=/dev/sr0 \-msinfo) .br $ load_opts= .br - $ test -n "$msinfo" && load_opts="-M /dev/sr0 -C $msinfo" + $ test \-n "$msinfo" && load_opts="\-M /dev/sr0 \-C $msinfo" .br - $ xorrisofs $load_opts -root /session2 -old-root /session1 \\ + $ xorrisofs $load_opts \-root /session2 \-old\-root /session1 \\ .br - -o - --for_backup -m '*.o' -m '*.swp' \\ + \-o \- \-\-for_backup \-m '*.o' \-m '*.swp' \\ .br - -V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \\ + \-V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \-graft\-points \\ .br /projects=/home/thomas/projects \\ .br /personal_mail=/home/thomas/personal_mail \\ .br - | xorriso -as cdrecord dev=/dev/sr0 -v -multi -waiti -eject - + | xorriso \-as cdrecord dev=/dev/sr0 \-v \-multi \-waiti \-eject \- .br -With the third session, option -old-root refers to /session2. -The new -root is /session3. And so on. +With the third session, option \-old\-root refers to /session2. +The new \-root is /session3. And so on. .SS .B Create bootable images for PC-BIOS The ISOLINUX wiki prescribes to create on disk a directory ./CD_root and @@ -1364,25 +1364,25 @@ This is the boot image file. .br The prescribed mkisofs options can be used unchanged with xorrisofs: .br - $ xorrisofs -o output.iso \\ + $ xorrisofs \-o output.iso \\ .br - -b isolinux/isolinux.bin -c isolinux/boot.cat \\ + \-b isolinux/isolinux.bin \-c isolinux/boot.cat \\ .br - -no-emul-boot -boot-load-size 4 -boot-info-table \\ + \-no\-emul\-boot \-boot\-load\-size 4 \-boot\-info\-table \\ .br ./CD_root .br Put it on CD by a burn program. E.g.: .br - $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed output.iso + $ xorriso \-as cdrecord \-v dev=/dev/sr0 blank=as_needed output.iso .br .sp 1 The image from above example will boot from CD, DVD or BD, but not from -USB stick or other hard-disk-like devices. This can be done by help of an +USB stick or other hard\-disk\-like devices. This can be done by help of an isohybrid MBR. Syslinux provides matching template files as isohdp[fp]x*.bin . E.g. /usr/lib/syslinux/isohdpfx.bin . .br -If a few hundred KB of size do not matter, then option -partition_offset +If a few hundred KB of size do not matter, then option \-partition_offset can be used to create a partition table where partition 1 starts not at block 0. This facilitates later manipulations of the USB stick by tools for partitioning and formatting. @@ -1392,13 +1392,13 @@ and its first parttion will start at hard disk block 64. .br It will also boot from optical media. .br - $ xorrisofs -o output.iso \\ - -b isolinux/isolinux.bin -c isolinux/boot.cat \\ - -no-emul-boot -boot-load-size 4 -boot-info-table \\ + $ xorrisofs \-o output.iso \\ + \-b isolinux/isolinux.bin \-c isolinux/boot.cat \\ + \-no\-emul\-boot \-boot\-load\-size 4 \-boot\-info\-table \\ .br - -isohybrid-mbr /usr/lib/syslinux/isohdpfx.bin \\ + \-isohybrid\-mbr /usr/lib/syslinux/isohdpfx.bin \\ .br - -partition_offset 16 \\ + \-partition_offset 16 \\ .br ./CD_root .br @@ -1422,7 +1422,7 @@ Now copy the image onto it .SS .B Startup files: .br -If not --no_rc is given as the first argument then xorrisofs +If not \-\-no_rc is given as the first argument then xorrisofs attempts on startup to read and execute lines from the following files: .br /etc/default/xorriso @@ -1449,19 +1449,19 @@ reading: $(dirname $0)/.mkisofsrc .br On success it interprets the file content and does not try further files. -The last address is used only if start argument 0 has a non-trivial dirname. +The last address is used only if start argument 0 has a non\-trivial dirname. .br The reader currently interprets the following NAME=VALUE pairs: .br - APPI default for -A + APPI default for \-A .br - PUBL default for -publisher + PUBL default for \-publisher .br - SYSI default for -sysid + SYSI default for \-sysid .br - VOLI default for -V + VOLI default for \-V .br - VOLS default for -volset + VOLS default for \-volset .br Any other lines will be silently ignored. .br @@ -1495,7 +1495,7 @@ MD5 checksums .SH AUTHOR Thomas Schmitt .br -for libburnia-project.org +for libburnia\-project.org .SH COPYRIGHT Copyright (c) 2011 Thomas Schmitt .br diff --git a/xorriso/xorrisofs.texi b/xorriso/xorrisofs.texi index 4e4387da..9d2c0068 100644 --- a/xorriso/xorrisofs.texi +++ b/xorriso/xorrisofs.texi @@ -31,6 +31,8 @@ @c @@ , @{, @} will get stripped of their first @. @c Other lines which begin by "@" will be discarded. @c In lines not stemming from "@c man", "\" becomes "\\" +@c "-" which are not preceded by an uneven number of "\" will get +@c prepended one "\". @c @c @c man .\" Hey, EMACS: -*- nroff -*-