[Debburn-devel] [PATCH] genisoimage documentation updates
Lorenz Minder
lminder at gmx.net
Tue Dec 12 00:47:04 CET 2006
Hi,
Below are some documentation updates to genisoimage. Specifically,
* .mkisofsrc --> .genisoimagerc, as this is the name of the config file
now.
* Remove some of the discussion of bugs in outdated versions and
kernels. I feel they do not belong here, as the manpage is not a
discussion forum. The description of options should limit itself to
describe the option and in what context it might be useful, in my
opinion.
* Some changes in phrasing for sentences I found hard to read.
* Other updates (e.g. the remark that "genisoimage" is a misnomer is
wrong, since it isn't.)
Since my mother tongue is not english, it would be good if some native
english speaker reviewed this.
This is work in progress, but I figured small bits are easier to review
than one large patch bomb.
Best,
--Lorenz
Index: genisoimage/genisoimage.1
===================================================================
--- genisoimage/genisoimage.1 (revision 611)
+++ genisoimage/genisoimage.1 (working copy)
@@ -118,7 +118,7 @@
is available from
http://alioth.debian.org/projects/debburn/
.PP
-Also you should know that most cd writers are very particular about timing.
+Also you should know that most CD writers are very particular about timing.
Once you start to burn a disc, you cannot let their buffer empty before you
are done, or you will end up with a corrupt disc. Thus it is critical
that you be able to maintain an uninterrupted data stream to the writer
@@ -127,8 +127,7 @@
.B pathspec
is the path of the directory tree to be copied into the ISO9660 filesystem.
Multiple paths can be specified, and
-.B
-genisoimage
+.B genisoimage
will merge the files found in all of the specified path components to form the cdrom
image.
.PP
@@ -173,7 +172,7 @@
Specifies the abstract file name.
There is space on the disc for 37 characters of information.
This parameter can also be set in the file
-.B \&.m\&kisofsrc
+.B \&.genisoimagerc
with ABST=filename.
If specified in both places, the command line version is used.
.TP
@@ -182,7 +181,7 @@
This should describe the application that will be on the disc. There
is space on the disc for 128 characters of information. This parameter can
also be set in the file
-.B \&.m\&kisofsrc
+.B \&.genisoimagerc
with APPI=id.
If specified in both places, the command line version is used.
.TP
@@ -215,7 +214,7 @@
Specifies the bibliographic file name.
There is space on the disc for 37 characters of information.
This parameter can also be set in the file
-.B \&.m\&kisofsrc
+.B \&.genisoimagerc
with BIBLO=filename.
If specified in both places, the command line version is used.
.TP
@@ -245,8 +244,8 @@
.B genisoimage
would cache inodes on Cygwin, it would believe that some files are
identical although they are not. The result in this case are files
-that contain the wrong content if a significant amount of different
-files (> ~5000) is in inside the tree that is to be archived.
+that contain the wrong content if a significant number of different
+files (> ~5000) are to be archived.
This does not happen when the
.B \-no\-cache\-inodes is used, but the disadvantage is that
.B genisoimage
@@ -344,7 +343,7 @@
have been specified with this option. Byte offset 512 .\|.\|. 8191
within each of the additional boot images must contain a primary boot
that works for the appropriate sparc architecture. The rest of each
-of the images usually contains an ufs filesystem that is used primary
+of the images usually contains an ufs filesystem that is used in the primary
kernel boot stage.
.sp
The implemented boot method is the boot method found with SunOS 4.x and SunOS 5.x.
@@ -419,7 +418,7 @@
have been specified with this option. Byte offset 512 .\|.\|. 8191
within each of the additional boot images must contain a primary boot
that works for the appropriate sparc architecture. The rest of each
-of the images usually contains an ufs filesystem that is used primary
+of the images usually contains an ufs filesystem that is used in the primary
kernel boot stage.
.sp
The implemented boot method is the boot method found with SunOS 4.x and SunOS 5.x.
@@ -498,7 +497,7 @@
sector number of the first sector in the last session of the disk
that should be appended to.
The second number is the starting sector number of the new session.
-The expected pair of numbers may be retrieved by calling
+The right numbers may be retrieved by calling
.B "wodim \-msinfo ...
If the
.B \-C
@@ -516,7 +515,7 @@
.B genisoimage
will create a filesystem image that is intended to be used for a second
session on a CD Extra. This is a multi session CD that holds audio data
-in the first session and a ISO9660 filesystem in the second session.
+in the first session and an ISO9660 filesystem in the second session.
.TP
.BI \-c " boot_catalog
Specifies the path and filename of the boot catalog to be used when making
@@ -527,7 +526,7 @@
This file will be inserted into the output tree and not created
in the source filesystem, so be
sure the specified filename does not conflict with an existing file, as
-it will be excluded. Usually a name like "boot.catalog" is
+it will be excluded otherwise. Usually a name like "boot.catalog" is
chosen.
.sp
If the
@@ -537,12 +536,11 @@
If you don't like this, you need to specify a sort weight of 0 for the boot catalog.
.TP
.B \-check\-oldnames
-Check all filenames imported from old session for compliance with
-actual
-.B genisoimage
+Check all filenames imported from the old session for compliance with
+the
ISO9660 file naming rules.
-It his option is not present, only names with a length > 31 are checked
-as these files are a hard violation of the ISO9660 standard.
+Even if this option is not present, names with a length > 31 are checked,
+as such filenames are a serious violation of the ISO9660 standard.
.TP
.BI \-check\-session " FILE
Check all old sessions for compliance with
@@ -553,7 +551,7 @@
.BI \-M " FILE " "\-C 0,0 \-check\-oldnames
For the parameter
.I FILE
-see description of
+see the description of the
.B \-M
option.
.TP
@@ -561,12 +559,12 @@
Specifies the copyright file name.
There is space on the disc for 37 characters of information.
This parameter can also be set in the file
-.B \&.m\&kisofsrc
+.B \&.genisoimagerc
with COPY=filename.
If specified in both places, the command line version is used.
.TP
.B \-d
-Omit trailing period from files that do not have a period.
+Omit the trailing period from files that do not have a period.
.br
This violates the ISO9660 standard, but it happens to work on many systems.
Use with caution.
@@ -631,7 +629,7 @@
.I glob
from being seen on the ISO9660 or Rock Ridge directory.
.I glob
-is a shell wild-card-style pattern that must match any part of the filename
+is a shell wild-card-style pattern that can match any part of the filename
or path.
Multiple globs may be hidden.
If
@@ -656,7 +654,7 @@
.I glob
from being listed on DOS based systems if the /A flag is not used for the listing.
.I glob
-is a shell wild-card-style pattern that must match any part of the filename
+is a shell wild-card-style pattern that can match any part of the filename
or path.
In order to match a directory name, make sure the pathname does not include
a trailing '/' character.
@@ -672,7 +670,7 @@
.I glob
from being seen on the Joliet directory.
.I glob
-is a shell wild-card-style pattern that must match any part of the filename
+is a shell wild-card-style pattern that can match any part of the filename
or path.
Multiple globs may be hidden.
If
@@ -772,7 +770,7 @@
.\" (f XXX ??? The character used for filling byte positions which are
.\" specified to be characters is subject to agreement between the
.\" originator and the recipient of the volume),
-the maximum length for files and directory is raised to 207.
+the maximum length for file- and directory-names is raised to 207.
If Rock Ridge is used, the maximum ISO9660 name length is reduced to 197.
.sp
When creating Version 2 images,
@@ -787,17 +785,15 @@
names. This is primarily useful when the discs are to be used on Windows
machines. The Joliet filenames are specified in Unicode and
each path component can be up to 64 Unicode characters long.
-Note that Joliet is not a standard - CDs that use only Joliet extensions but no
-standard Rock Ridge extensions may usually only be used on Microsoft Win32
-systems. Furthermore, the fact that the filenames are limited to 64 characters
-and the fact that Joliet uses the UTF-16 coding for Unicode characters causes
-interoperability problems.
+Note that Joliet is not a standard.
+Furthermore, Joliet filenames are limited to 64 characters and UTF-16
+encoded, which causes interoperability issues.
.TP
.B \-joliet\-long
-Allow Joliet filenames to be up to 103 Unicode characters. This breaks the
-Joliet specification - but appears to work. Use with caution. The number
-103 is derived from: the maximum Directory Record Length (254), minus the
-length of Directory Record (33), minus CD-ROM XA System Use Extension
+Allow Joliet filenames to be up to 103 Unicode characters long. This breaks the
+Joliet specification, but appears to work. Use with caution. The number
+103 is derived from: the maximum Directory Record Length (254) minus the
+length of Directory Record (33) minus CD-ROM XA System Use Extension
Information (14), divided by the UTF-16 character size (2).
.TP
.BI \-jcharset " charset
@@ -806,7 +802,7 @@
.I charset
and
.B \-J
-options. See
+options. See the
.B "CHARACTER SETS
section below for more details.
.TP
@@ -819,10 +815,9 @@
Use with caution.
.TP
.B \-L
-Outdated option reserved by POSIX.1-2001, use
+Outdated option; use
.B \-allow\-leading\-dots
instead.
-This option will get POSIX.1-2001 semantics with genisoimage-2.02.
.TP
.BI \-jigdo\-jigdo " jigdo_file
Produce a jigdo .jigdo file as well as the .iso. See the
@@ -874,7 +869,7 @@
.I glob
from being written to CD-ROM.
.I glob
-is a shell wild-card-style pattern that must match part of the filename (not
+is a shell wild-card-style pattern that can match part of the filename (not
the path as with option
.BR \-x ).
Technically
@@ -888,8 +883,8 @@
genisoimage \-o rom \-m '*.o' \-m core \-m foobar
would exclude all files ending in ".o", called "core" or "foobar" to be
-copied to CD-ROM. Note that if you had a directory called "foobar" it too (and
-of course all its descendants) would be excluded.
+copied to CD-ROM. Note that if you had a directory called "foobar", it
+(and its descendants) would also be excluded.
.sp
NOTE: The
.B \-m
@@ -927,7 +922,7 @@
takes a SCSI device specifier that uses the same syntax as the
.B "dev=
parameter of
-.B wodim.
+.BR wodim .
The output of
.B genisoimage
will be a new session which should get written to the end of the
@@ -970,36 +965,19 @@
finds illegal Rock Ridge signatures on an old session.
.TP
.B \-no\-split\-symlink\-components
-Don't split the SL components, but begin a new Continuation Area (CE)
+Do not split the symlink components, but begin a new Continuation Area (CE)
instead. This may waste some space, but the SunOS 4.1.4 cdrom driver
-has a bug in reading split SL components (link_size = component_size
-instead of link_size += component_size).
+has a bug in reading split symlink components.
.sp
-Note that this option has been introduced by Eric Youngdale in 1997.
-It is questionable whether it makes sense at all.
-When it has been introduced,
-.B genisoimage
-did have a serious bug that did create defective CE signatures if
-a symlink contained `/../'.
-This CE signature bug in
-.B genisoimage
-has been fixed in May 2003.
+It is questionable whether this option is useful nowadays.
.TP
.B \-no\-split\-symlink\-fields
-Don't split the SL fields, but begin a new Continuation Area (CE)
+Do not split the symlink fields, but begin a new Continuation Area (CE)
instead. This may waste some space, but the SunOS 4.1.4 and
-Solaris 2.5.1 cdrom driver have a bug in reading split SL fields
+Solaris 2.5.1 cdrom driver have a bug in reading split symlink fields
(a `/' can be dropped).
.sp
-Note that this option has been introduced by Eric Youngdale in 1997.
-It is questionable whether it makes sense at all.
-When it has been introduced,
-.B genisoimage
-did have a serious bug that did create defective CE signatures if
-a symlink contained `/../'.
-This CE signature bug in
-.B genisoimage
-has been fixed in May 2003.
+It is questionable whether this option is useful nowadays.
.TP
.BI \-o " filename
is the name of the file to which the ISO9660 filesystem image should be
@@ -1029,6 +1007,8 @@
the
.B \-pad
option has been made the default.
+.\" XXX: Are those bugs still there on recent Linux versions? If no,
+.\" those comments should probably be changed.
.TP
.B \-no\-pad
Do not Pad the end by 150 sectors (300 kB) and do not make the the boot partitions
@@ -1044,17 +1024,16 @@
then the list is read from the standard input.
.TP
.B \-P
-Outdated option reserved by POSIX.1-2001, use
+Outdated option; use
.B \-publisher
instead.
-This option will get POSIX.1-2001 semantics with genisoimage-2.02.
.TP
.BI \-publisher " publisher_id
Specifies a text string that will be written into the volume header.
This should describe the publisher of the CD-ROM, usually with a
mailing address and phone number. There is space on the disc for 128
characters of information. This parameter can also be set in the file
-.B \&.m\&kisofsrc
+.B \&.genisoimagerc
with PUBL=.
If specified in both places, the command line version is used.
.TP
@@ -1063,7 +1042,7 @@
This should describe the preparer of the CD-ROM, usually with a mailing
address and phone number. There is space on the disc for 128
characters of information. This parameter can also be set in the file
-.B \&.m\&kisofsrc
+.B \&.genisoimagerc
with PREP=.
If specified in both places, the command line version is used.
.TP
@@ -1071,14 +1050,14 @@
Print estimated filesystem size in multiples of the sector size (2048 bytes)
and exit. This option is needed for
Disk At Once mode and with some CD-R drives when piping directly into
-.B wodim.
+.BR wodim .
In this case it is needed to know the size of the filesystem before the
actual CD creation is done.
The option \-print\-size allows to get this size from a "dry-run" before
the CD is actually written.
Old versions of
.B genisoimage
-did write this information (among other information) to
+wrote this information (among other information) to
.IR stderr .
As this turns out to be hard to parse, the number without any other information
is now printed on
@@ -1120,7 +1099,7 @@
When used on Win32, the execute bit is set on
.I all
files. This is a result of the lack of file permissions on Win32 and the
-Cygwin POSIX emulation layer. See also \-uid \-gid, \-dir\-mode, \-file\-mode
+Cygwin POSIX emulation layer. See also \-uid, \-gid, \-dir\-mode, \-file\-mode
and \-new\-dir\-mode.
.TP
.B \-relaxed\-filenames
@@ -1166,9 +1145,10 @@
.B \-old-root
are meant to be used together to do incremental backups.
The initial session would e.g. use:
-.BI "genisoimage \-root backup_1 " dirs\f0.
+.B genisoimage \-root backup_1
+.IR dirs .
The next incremental backup with
-.BI "genisoimage \-root backup_2 \-old-root backup_1 " dirs\f0.
+.BI "genisoimage \-root backup_2 \-old-root backup_1 " dirs
would take another snapshot of these directories. The first
snapshot would be found in
.BR backup_1 ,
@@ -1185,7 +1165,7 @@
support by the operating system to choose which sessions are to be
mounted.
.TP
-.BI \-sort " sort file
+.BI \-sort " sort-file
Sort file locations on the media. Sorting is controlled by a file that
contains pairs of filenames and sorting offset weighting.
If the weighting is higher, the file will be located closer to the
@@ -1200,11 +1180,11 @@
.B not
sort the order of the file names that appear
in the ISO9660 directory. It sorts the order in which the file data is
-written to the CD image - which may be useful in order to optimize the
+written to the CD image; this is useful in order to optimize the
data layout on a CD. See README.sort for more details.
.TP
.BI \-sparc\-boot " img_sun4,img_sun4c,img_sun4m,img_sun4d,img_sun4e
-See
+See the
.B \-B
option above.
.TP
@@ -1214,10 +1194,11 @@
option.
.TP
.B \-split\-output
-Split the output image into several files of approximately 1 GB.
+Split the output image into several files of approximately 1 GB each.
This helps to create DVD sized ISO9660 images on operating systems without
large file support.
-Wodim will concatenate more than one file into a single track if writing
+.B wodim
+will concatenate more than one file into a single track if writing
to a DVD.
To make
.B \-split\-output
@@ -1228,7 +1209,9 @@
.TP
.BI \-stream\-media\-size " #
Select streaming operation and set the media size to # sectors.
-This allows you to pipe the output of the tar program into genisoimage
+This allows you to pipe the output of the
+.BR tar (1)
+program into genisoimage
and to create a ISO9660 filesystem without the need of an intermediate
tar archive file.
If this option has been specified,
@@ -1296,7 +1279,7 @@
Specifies the system ID.
There is space on the disc for 32 characters of information.
This parameter can also be set in the file
-.B \&.m\&kisofsrc
+.B \&.genisoimagerc
with SYSI=system_id.
If specified in both places, the command line version is used.
.TP
@@ -1344,7 +1327,9 @@
.B \-use\-fileversion
The option
.B \-use\-fileversion
-allows genisoimage to use file version numbers from the filesystem.
+allows
+.B genisoimage
+to use file version numbers from the filesystem.
If the option is not specified,
.B genisoimage
creates a version number of 1 for all files.
@@ -1366,7 +1351,7 @@
.TP
.B \-no\-iso\-translate
Do not translate the characters '#' and '~' which are invalid for ISO9660 filenames.
-These characters are though invalid often used by Microsoft systems.
+Although invalid, these characters are often used by Microsoft systems.
.br
This violates the ISO9660 standard, but it happens to work on many systems.
Use with caution.
@@ -1376,7 +1361,7 @@
master block.
There is space on the disc for 32 characters of information.
This parameter can also be set in the file
-.B \&.m\&kisofsrc
+.B \&.genisoimagerc
with VOLI=id.
If specified in both places, the command line version is used. Note that
if you assign a volume ID, this is the name that will be used as the mount
@@ -1387,7 +1372,7 @@
Specifies the volset ID.
There is space on the disc for 128 characters of information.
This parameter can also be set in the file
-.B \&.m\&kisofsrc
+.B \&.genisoimagerc
with VOLS=volset_id.
If specified in both places, the command line version is used.
.TP
@@ -1584,15 +1569,15 @@
from the HFS volume. The file or directory will still exist in the
ISO9660 and/or Joliet directory.
.I glob
-is a shell wild-card-style pattern that must match any part of the filename
-Multiple globs may be excluded.
+is a shell wild-card-style pattern that can match any part of the filename.
+Multiple globs can be excluded by specifying \-hide\-hfs more than once.
Example:
genisoimage \-o rom \-hfs \-hide\-hfs '*.o' \-hide\-hfs foobar
would exclude all files ending in ".o" or called "foobar"
from the HFS volume. Note that if you had a directory called
-"foobar" it too (and of course all its descendants) would be excluded.
+"foobar", it (and its descendants) would also be excluded.
The
.I glob
can also be a path name relative to the source directories given on the
@@ -1622,14 +1607,14 @@
.I volid
used with the
.B \-V
-option
+option.
.TP
.B \-icon\-position
Use the icon position information, if it exists, from the Apple/Unix file.
The icons will appear in the same position as they would on a Macintosh
desktop. Folder location and size on screen, its scroll positions, folder
View (view as Icons, Small Icons, etc.) are also preserved.
-This option may become set by default in the future.
+.\" This option may become set by default in the future.
(Alpha).
.TP
.BI \-root\-info " file
@@ -1645,10 +1630,10 @@
used with the
.I \-mac\-name
option.
-The default charset is cp10000 (Mac Roman)
+The default charset is
.I cp10000
-(Mac Roman)
-See
+(Mac Roman).
+See the
.B "CHARACTER SETS
and
.B "HFS MACINTOSH FILE NAMES
@@ -1656,7 +1641,7 @@
.TP
.BI \-output\-hfs\-charset " charset
Output charset that defines the characters that will be used in the HFS
-file names. Defaults to the input charset. See
+file names. Defaults to the input charset. See the
.B "CHARACTER SETS
section below for more details.
.TP
@@ -1680,7 +1665,7 @@
called System Folder, then the whole path name is "./cddata/System Folder"
(remember to use quotes if the name contains spaces).
.TP
-.BI \-hfs\-parms " PARAMETERS
+.BI \-hfs\-parms " parameters
Override certain parameters used to create the HFS file system. Unlikely to
be used in normal circumstances. See the libhfs_iso/hybrid.h source file for
details.
@@ -1939,7 +1924,7 @@
.PP
If a mapping or magic file is not used, or no match is found then the default
CREATOR and TYPE for all regular files can be set by using entries in the
-.B \&.m\&kisofsrc
+.B \&.genisoimagerc
file or using the
.B \-hfs\-creator
and/or
@@ -2072,7 +2057,7 @@
.PP
In summary, for all files, the default CREATOR is 'Unix' and the default
TYPE is 'TEXT'. These can be changed by using entries in the
-.I \&.m\&kisofsrc
+.I \&.genisoimagerc
file or by using the
.B \-hfs\-creator
and/or
@@ -2369,7 +2354,7 @@
will be seen as
.I ABCDEFGHI.
i.e. with a '.' at the end - don't know if this is a Macintosh
-problem or m\&kisofs/mkhybrid problem. All filenames will be in upper case
+problem or genisoimage/mkhybrid problem. All filenames will be in upper case
when viewed on a Macintosh. Of course, DOS/Win3.X machines will not be able
to see Level 2 filenames...
@@ -2540,7 +2525,7 @@
.SH CONFIGURATION
.B genisoimage
looks for the
-.B \&.m\&kisofsrc
+.B \&.genisoimagerc
file,
first in the current working directory,
then in the user's home directory,
@@ -2744,22 +2729,30 @@
There are probably all sorts of strange results possible with
combinations of the hide options ...
-.SH AUTHOR
+.SH AUTHORS
.PP
+.B genisoimage
+is a fork of the m\&kisofs utility, now maintained independently by the
+cdrkit project. See the
+.B "MAINTAINER
+section for details.
+.PP
.br
Eric Youngdale <ericy at gnu.ai.mit.edu> or <eric at andante.org> wrote the
-first versions (1993 .\|.\|. 1998) of the m\&kisofs utility.
-The copyright for old versions of the m\&kisofs utility is held by
+first versions (1993 .\|.\|. 1998) of m\&kisofs.
+The copyright for old versions of m\&kisofs is held by
Yggdrasil Computing, Incorporated.
.PP
Major additional parts were written or contributed by the following authors. Also
-see the MAINTAINER section below for recent information.
+see the
+.B "MAINTAINER
+section below for recent information.
.PP
J\*org Schilling
wrote the SCSI transport library and its adaptation layer to
-.B genisoimage
+.B m\&kisofs
and newer parts (starting from 1999) of the utility, this makes
-.B genisoimage
+.B m\&kisofs
.br
Copyright (C) 1999, 2000, 2001 J\*org Schilling.
.PP
@@ -2771,18 +2764,12 @@
.PP
iconv code, Copyright (C) 2003 Jungshik Shin, (C) 2003 Jaakko Heinonen
.PP
-See MAINTAINER section for contact information.
+See the
+.B "MAINTAINER
+section for contact information.
.SH NOTES
.PP
.B genisoimage
-is not based on the standard mk*fs tools for Unix, because we must generate
-a complete copy of an existing filesystem on a disk in the ISO9660
-filesystem. The name genisoimage is probably a bit of a misnomer, since it
-not only creates the filesystem, but it also populates it.
-However, the appropriate tool name for a Unix tool that creates populated
-filesystems - mkproto - is not well known.
-.PP
-.B genisoimage
may safely be installed suid root. This may be needed to allow
.B genisoimage
to read the previous session when creating a multi session image.
@@ -2969,18 +2956,19 @@
.SH "FUTURE IMPROVEMENTS
Some sort of gui interface.
.SH AVAILABILITY
-.B m\&kisofs
+.B genisoimage
is available as part of the cdrkit package from
http://alioth.debian.org/projects/debburn/. For other implementations/spinoffs
of genisoimage, look at the homepage of the particular developers.
.B hfsutils
from ftp://ftp.mars.org/pub/hfs
.SH "MAILING LISTS
-If you want to actively take part on the development of m\&kisofs,
-you may join the Cdrkit developers mailing list by following the instructions on:
+If you want to actively take part on the development of genisoimage
+you may join the Cdrkit developers mailing list by following the
+instructions on:
.nf
.sp
-https://alioth.debian.org/mail/?group_id=31006
+http://alioth.debian.org/mail/?group_id=31006
.sp
.fi
and include the word
@@ -2999,10 +2987,16 @@
Joerg Jaspert
Eduard Bloch
Steve McIntyre
+Peter Samuelson
+Christian Fromme
Ben Hutchings
and other contributors
.PP
-Cdrkit implementation of genisoimage is derived from mkisofs in the Cdrtools
+Cdrkit implementation of
+.B genisoimage
+is derived from
+.B mkisofs
+in the Cdrtools
package [1] (however now developed independently), having previous maintainers:
.PP
.nf
More information about the Debburn-devel
mailing list