From fd195504ae397ea5f9c80b03033c7b88a4aeb112 Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Wed, 19 Oct 2022 13:23:47 +0200 Subject: [PATCH] Created manual pages for merge_debian_iso --- test/merge_debian_isos.1 | 283 +++++++++++++++++++++++ test/merge_debian_isos.info | 346 ++++++++++++++++++++++++++++ test/merge_debian_isos.texi | 434 ++++++++++++++++++++++++++++++++++++ 3 files changed, 1063 insertions(+) create mode 100644 test/merge_debian_isos.1 create mode 100644 test/merge_debian_isos.info create mode 100644 test/merge_debian_isos.texi diff --git a/test/merge_debian_isos.1 b/test/merge_debian_isos.1 new file mode 100644 index 00000000..c053da31 --- /dev/null +++ b/test/merge_debian_isos.1 @@ -0,0 +1,283 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" +.\" IMPORTANT NOTE: +.\" +.\" The original of this file is kept in test/merge_debian_isos.texi +.\" This here was generated by program xorriso/make_xorriso_1 +.\" +.\" +.\" 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 MERGE_DEBIAN_ISOS 1 "Version 1.5.5, Oct 19, 2022" +.\" Please adjust this date whenever revising the manpage. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp insert n+1 empty lines +.\" for manpage-specific macros, see man(7) +.nh +.SH NAME +merge_debian_isos \- Program to merge multiple debian\-cd ISO images +.SH SYNOPSIS +.B merge_debian_isos +result_iso mount_template iso1 iso2 [... isoN] +.br +.SH DESCRIPTION +.PP +\fBmerge_debian_isos\fR +mounts by \fBsudo\fR the ISO 9660 images iso1 to isoN at directories +mount_template1 to mount_templateN, if not already mounted that way. +Then the Debian pools and package lists get merged and a new +ISO 9660 image result_iso is produced by a run of \fBxorriso\fR. +If iso1 is bootable then +the new image will be bootable by the same means. +.br +.PP +The file depicted by result_iso must not yet exist or has to be a +device which is acceptable for Linux\-specific helper script +\fBxorriso\-dd\-target\fR. If xorriso\-dd\-target agrees and the user +confirms by input "yes" then xorriso will be run under sudo. +.br +Exempted from this evaluation are addresses which begin by "mmc:" +for an optical drive on Linux, BSDs, Solaris, or by "stdio:/dev/" +for which the user takes full and dangerous responsibility. +.br +Special result_iso path \fBxorriso\-dd\-target\-plug\-test\fR determines +on systems with Linux kernel the target USB stick by a dialog around plugging +it in. +xorriso will be run under sudo, if xorriso\-dd\-target agrees and +the user confirms by input "yes". +.br +.PP +At least the parent directory of argument \fBmount_template\fR must already +exist or has to be given by a plain name without "/" so that it can be +created in the current directory. (I.e. without even "./".) +.br +All arguments must be single words without using quotation marks. +None of the isoN must be equal to another isoM. +.br +.PP +This script creates and finally removes the following temporary tree +and files which must not yet exist in the current working directory: + ./merged_dists , ./merged_md5sum.txt , ./merged_REAMDE.txt + ./temp_file +.br +Further it creates and finally removes directories mount_template* +if they are needed and do not exist when the script starts. If the +parent directory in the mount_template path does not exist and +its path contains no "/" then it gets created and finally removed. +The script depends on the following programs: +.br + awk, basename, cat, chmod, cp, date, dirname, expr, fgrep, grep, + gunzip, gzip, head, ls, md5sum, mkdir, mount, mv, rm, rmdir, + sed, sh, sha256sum, sort, stat, sudo, umount, uniq, xorriso +.br +With device writing involving helper script xorriso\-dd\-target: +.br + dd, Linux kernel, lsblk, sleep, tr, uname, wc, whoami, + xorriso\-dd\-target +.br +Recommended are: sha1sum, sha512sum + +.SS +.br +.SH OPTIONS +.br +.PP +merge_debian_isos has no command line options besides the input words described +above, but it reacts on some environment variables. +.br +See section ENVIRONMENT. +.br +.PP +If less than 4 arguments are given, the script will print its help text to +standard error and exit with non\-zero value, indicating failure. +.SS +.SH EXAMPLES +.SS +.B Overview of examples: +Merge DVD images 1 to 5 +.br +Use GNU xorriso instead of installed xorriso +.br +Write result directly to an optical drive +.br +Write result directly and safely to USB stick (Linux only) +.br +Write result directly and unsafely to USB stick +.SS +.B Merge DVD images 1 to 5 +The resulting image will be named "merged.iso". +.br +Directory ./merge_mount/ will be created if not yet existing. +.br + +merge_debian_isos merged.iso merge_mount/iso \\ + debian\-11.2.0\-amd64\-DVD\-[12345].iso + +.SS +.B Use GNU xorriso instead of installed xorriso +merge_debian_isos will refuse to work if the installed version of xorriso +is older than 1.4.2. In this case consider to download and compile the +GNU xorriso tarball from +.br + https://www.gnu.org/software/xorriso/#download +.br +You may use it without installing it after compilation and thus without +disturbing your system's package management. Assumed that you unpacked the +xorriso\-1.5.4 tarball in your $HOME directory and have successfully compiled +it, do: +.br + +export XORRISO="$HOME"/xorriso\-1.5.4/xorriso/xorriso +.br + +merge_debian_isos merged.iso merge_mount/iso \\ + debian\-11.2.0\-amd64\-DVD\-[12345].iso + +.SS +.B Write result directly to an optical drive +xorriso is able to burn optical media on GNU/Linux (/dev/sr*), +Solaris (/dev/rdsk/*) , FreeBSD (/dev/cd*) , NetBSD (/dev/rcd*), +and OpenBSD (/dev/rcd*). Get a list of available optical drive devices by: +.br + +xorriso \-devices +.br + +It might be that you need superuser powers for this and then have to enable +access to the device file for the user who runs merge_debian_isos. +.br + +In order to directly write the merged ISO image to an optical medium, +use the desired device file path with prefix "mmc:": +.br + +merge_debian_isos mmc:/dev/sr0 merge_mount/iso \\ + debian\-11.2.0\-amd64\-DVD\-[12345].iso + +.SS +.B Write result directly and safely to USB stick (Linux only) +The Linux\-specific script \fBxorriso\-dd\-target\fR evaluates device files +whether they and their content look unimportant enough for being overwritten +by an image file. +.br +This mainly means that the storage device is attached to USB and contains +no filesystems which are not of type FAT or ISO 9660. +.br +You may get xorriso\-dd\-target by: +.br + +wget \\ + https://dev.lovelyhq.com/libburnia/libisoburn/raw/master/xorriso\-dd\-target/xorriso\-dd\-target +chmod u+x xorriso\-dd\-target +.br + +Consider to also download xorriso\-dd\-target.sig and to verify the script by +.br + +gpg \-\-verify xorriso\-dd\-target.sig xorriso\-dd\-target +.br + +Announce the storage location of the downloaded xorriso\-dd\-target: +.br + +export XORRISO_DD_TARGET_PATH="$(pwd)" +.br + +The prepared use case in merge_debian_isos uses the xorriso\-dd\-target +option \-plug_test under \fBsudo\fR, which asks the user for first having +the desired USB stick unplugged so that the unwanted devices can get +registered. Then it asks the user to plug in the USB stick, so that it gets +recognized as desired target. +.br +xorriso\-dd\-target evaluates the content and decides whether it looks +disposable enough. If so, then it allows merge_debian_isos to write its +result to the device. +.br + +merge_debian_isos xorriso\-dd\-target\-plug\-test merge_mount/iso \\ + debian\-11.2.0\-amd64\-DVD\-[12345].iso + +.SS +.B Write result directly and unsafely to USB stick +On operating systems other than GNU/Linux or with storage devices not +acceptable to xorriso\-dd\-target it is possible to remove all safety +precautions beyond those of xorriso, which can be overcome by "blanking" +the device. +.br +So after due evaluation of the device situation and on your very own risk +you may use the device path prefix "stdio:", possibly with superuser powers: +.br + +xorriso \-outdev stdio:/dev/sdd \-blank as_needed + +merge_debian_isos stdio:/dev/sdd merge_mount/iso \\ + debian\-11.2.0\-amd64\-DVD\-[12345].iso + +For details about "stdio:" and pseudo\-blanking non\-optical devices read +man xorriso. +.br +The xorriso run in merge_debian_isos ignores locally defined xorriso startup +files (by command \-no_rc). +.SH FILES +For now, no files are defined for configuration. +.SH ENVIRONMENT +The following environment variables influence the program behavior: +.br +Exported non\-empty variable MERGE_DATE enforces a particular +date string in the text which gets prepended to /README.txt . +.br +Exported non\-empty variable MERGE_FOR_DIST enforces the use of a +particular directory in /dists of iso1. Normally only one +such directory is found and thus no need to set MERGE_FOR_DIST. +.br +Exported non\-empty variable MERGE_KEEP_ISO prevents the removal +of result_iso after xorriso indicated failure of production. +.br +Exported non\-empty variable XORRISO gives the path to a xorriso binary, +which will be used instead of the system\-wide installed xorriso binary. +This may be needed if installed xorriso is older than 1.4.2. +.br +If XORRISO is set to "dummy" then no new ISO will emerge. +.br +Exported non\-empty variable XORRISO_DD_TARGET_PATH names the +directory where to find xorriso\-dd\-target, which evaluates the +suitability of result_iso devices or does the plug\-test dialog. +.br +.SH SEE ALSO +.BR xorriso(1), +.BR xorriso-dd-target(1), +.SH BUGS +To report bugs, request help, or suggest enhancements for +\fBxorriso\-dd\-target\fR, +please send electronic mail to the public list . +If more privacy is desired, mail to . +.br +Please describe what you expect the program to do, the program arguments +which you used, the messages of \fBxorriso\-dd\-target\fR, and the +undesirable outcome of your program run. +.br +Expect to get asked more questions before solutions can be proposed. +.SH AUTHOR +Thomas Schmitt +.br +for libburnia\-project.org +.SH COPYRIGHT +Copyright (c) 2022 Thomas Schmitt +.br +Permission is granted to distribute this text freely. It shall only be +modified in sync with the technical properties of merge_debian_isos. +If you make use of the license to derive modified versions of merge_debian_isos +then you are entitled to modify this text under that same license. +.SH CREDITS +\fBmerge_debian_isos\fR was originally developed with advise and testing +by Zhang Boyang in the course of Debian bug #1011343. Steve McIntyre provided +information about various file aspects of debian\-cd ISO images. diff --git a/test/merge_debian_isos.info b/test/merge_debian_isos.info new file mode 100644 index 00000000..5349afe8 --- /dev/null +++ b/test/merge_debian_isos.info @@ -0,0 +1,346 @@ +This is merge_debian_isos.info, produced by makeinfo version 5.2 from +merge_debian_isos.texi. + +merge_debian_isos - sh script to merge multiple debian-cd ISO images + + Copyright (C) 2022 Thomas Schmitt + + Permission is granted to distribute this text freely. +INFO-DIR-SECTION Archiving +START-INFO-DIR-ENTRY +* Merge_debian_isos: (merge_debian_isos). Merge debian-cd ISO images to a single image +END-INFO-DIR-ENTRY + + +File: merge_debian_isos.info, Node: Top, Next: Overview, Up: (dir) + +merge_debian_isos 1.5.5 +*********************** + +merge_debian_isos - Program to merge multiple debian-cd ISO images +* Menu: + +* Overview:: Overview +* Options:: Options +* Examples:: Examples +* Files:: Files +* Environ:: Environment +* Seealso:: See also +* Bugreport:: Reporting bugs +* Legal:: Author, Copyright, Credits +* CommandIdx:: Alphabetic Option List +* ConceptIdx:: Alphabetic List of Concepts and Objects + + +File: merge_debian_isos.info, Node: Overview, Next: Options, Prev: Top, Up: Top + +1 Overview +********** + +'merge_debian_isos' mounts by *sudo* the ISO 9660 images iso1 to isoN at +directories mount_template1 to mount_templateN, if not already mounted +that way. Then the Debian pools and package lists get merged and a new +ISO 9660 image result_iso is produced by a run of *xorriso*. If iso1 is +bootable then the new image will be bootable by the same means. + + The file depicted by result_iso must not yet exist or has to be a +device which is acceptable for Linux-specific helper script +*xorriso-dd-target*. If xorriso-dd-target agrees and the user confirms +by input "yes" then xorriso will be run under sudo. +Exempted from this evaluation are addresses which begin by "mmc:" for an +optical drive on Linux, BSDs, Solaris, or by "stdio:/dev/" for which the +user takes full and dangerous responsibility. +Special result_iso path *xorriso-dd-target-plug-test* determines on +systems with Linux kernel the target USB stick by a dialog around +plugging it in. xorriso will be run under sudo, if xorriso-dd-target +agrees and the user confirms by input "yes". + + At least the parent directory of argument *mount_template* must +already exist or has to be given by a plain name without "/" so that it +can be created in the current directory. (I.e. without even "./".) +All arguments must be single words without using quotation marks. None +of the isoN must be equal to another isoM. + + This script creates and finally removes the following temporary tree +and files which must not yet exist in the current working directory: +./merged_dists , ./merged_md5sum.txt , ./merged_REAMDE.txt ./temp_file +Further it creates and finally removes directories mount_template* if +they are needed and do not exist when the script starts. If the parent +directory in the mount_template path does not exist and its path +contains no "/" then it gets created and finally removed. The script +depends on the following programs: +awk, basename, cat, chmod, cp, date, dirname, expr, fgrep, grep, gunzip, +gzip, head, ls, md5sum, mkdir, mount, mv, rm, rmdir, sed, sh, sha256sum, +sort, stat, sudo, umount, uniq, xorriso +With device writing involving helper script xorriso-dd-target: +dd, Linux kernel, lsblk, sleep, tr, uname, wc, whoami, xorriso-dd-target + +Recommended are: sha1sum, sha512sum + + +File: merge_debian_isos.info, Node: Options, Next: Examples, Prev: Overview, Up: Top + +2 Options +********* + +merge_debian_isos has no command line options besides the input words +described above, but it reacts on some environment variables. + + If less than 4 arguments are given, the script will print its help +text to standard error and exit with non-zero value, indicating failure. + + +File: merge_debian_isos.info, Node: Examples, Next: Files, Prev: Options, Up: Top + +3 Examples +********** + +* Menu: + +* ExPlain:: Merge DVD images 1 to 5 +* ExXorriso:: Use GNU xorriso instead of installed xorriso +* ExOptical:: Write result directly to an optical drive +* ExDdTarget:: Write result directly and safely to USB stick (Linux only) +* ExStdio:: Write result directly and unsafely to USB stick + + +File: merge_debian_isos.info, Node: ExPlain, Next: ExXorriso, Prev: Options, Up: Examples + +3.1 Merge DVD images 1 to 5 +=========================== + +The resulting image will be named "merged.iso". +Directory ./merge_mount/ will be created if not yet existing. + + merge_debian_isos merged.iso merge_mount/iso \ +debian-11.2.0-amd64-DVD-[12345].iso + + +File: merge_debian_isos.info, Node: ExXorriso, Next: ExOptical, Prev: ExPlain, Up: Examples + +3.2 Use GNU xorriso instead of installed xorriso +================================================ + +merge_debian_isos will refuse to work if the installed version of +xorriso is older than 1.4.2. In this case consider to download and +compile the GNU xorriso tarball from +https://www.gnu.org/software/xorriso/#download +You may use it without installing it after compilation and thus without +disturbing your system's package management. Assumed that you unpacked +the xorriso-1.5.4 tarball in your $HOME directory and have successfully +compiled it, do: + + export XORRISO="$HOME"/xorriso-1.5.4/xorriso/xorriso + + merge_debian_isos merged.iso merge_mount/iso \ +debian-11.2.0-amd64-DVD-[12345].iso + + +File: merge_debian_isos.info, Node: ExOptical, Next: ExDdTarget, Prev: ExXorriso, Up: Examples + +3.3 Write result directly to an optical drive +============================================= + +xorriso is able to burn optical media on GNU/Linux (/dev/sr*), Solaris +(/dev/rdsk/*) , FreeBSD (/dev/cd*) , NetBSD (/dev/rcd*), and OpenBSD +(/dev/rcd*). Get a list of available optical drive devices by: + + xorriso -devices + + It might be that you need superuser powers for this and then have to +enable access to the device file for the user who runs +merge_debian_isos. + + In order to directly write the merged ISO image to an optical medium, +use the desired device file path with prefix "mmc:": + + merge_debian_isos mmc:/dev/sr0 merge_mount/iso \ +debian-11.2.0-amd64-DVD-[12345].iso + + +File: merge_debian_isos.info, Node: ExDdTarget, Next: ExStdio, Prev: ExOptical, Up: Examples + +3.4 Write result directly and safely to USB stick (Linux only) +============================================================== + +The Linux-specific script *xorriso-dd-target* evaluates device files +whether they and their content look unimportant enough for being +overwritten by an image file. +This mainly means that the storage device is attached to USB and +contains no filesystems which are not of type FAT or ISO 9660. +You may get xorriso-dd-target by: + + wget \ +https://dev.lovelyhq.com/libburnia/libisoburn/raw/master/xorriso-dd-target/xorriso-dd-target +chmod u+x xorriso-dd-target + + Consider to also download xorriso-dd-target.sig and to verify the +script by + + gpg -verify xorriso-dd-target.sig xorriso-dd-target + + Announce the storage location of the downloaded xorriso-dd-target: + + export XORRISO_DD_TARGET_PATH="$(pwd)" + + The prepared use case in merge_debian_isos uses the xorriso-dd-target +option -plug_test under *sudo*, which asks the user for first having the +desired USB stick unplugged so that the unwanted devices can get +registered. Then it asks the user to plug in the USB stick, so that it +gets recognized as desired target. +xorriso-dd-target evaluates the content and decides whether it looks +disposable enough. If so, then it allows merge_debian_isos to write its +result to the device. + + merge_debian_isos xorriso-dd-target-plug-test merge_mount/iso \ +debian-11.2.0-amd64-DVD-[12345].iso + + +File: merge_debian_isos.info, Node: ExStdio, Next: Files, Prev: ExDdTarget, Up: Examples + +3.5 Write result directly and unsafely to USB stick +=================================================== + +On operating systems other than GNU/Linux or with storage devices not +acceptable to xorriso-dd-target it is possible to remove all safety +precautions beyond those of xorriso, which can be overcome by "blanking" +the device. +So after due evaluation of the device situation and on your very own +risk you may use the device path prefix "stdio:", possibly with +superuser powers: + + xorriso -outdev stdio:/dev/sdd -blank as_needed + + merge_debian_isos stdio:/dev/sdd merge_mount/iso \ +debian-11.2.0-amd64-DVD-[12345].iso + + For details about "stdio:" and pseudo-blanking non-optical devices +read man xorriso. +The xorriso run in merge_debian_isos ignores locally defined xorriso +startup files (by command -no_rc). + + +File: merge_debian_isos.info, Node: Files, Next: Environ, Prev: Examples, Up: Top + +4 Files +******* + +For now, no files are defined for configuration. + + +File: merge_debian_isos.info, Node: Environ, Next: Seealso, Prev: Files, Up: Top + +5 Environ +********* + +The following environment variables influence the program behavior: +Exported non-empty variable MERGE_DATE enforces a particular date string +in the text which gets prepended to /README.txt . +Exported non-empty variable MERGE_FOR_DIST enforces the use of a +particular directory in /dists of iso1. Normally only one such +directory is found and thus no need to set MERGE_FOR_DIST. +Exported non-empty variable MERGE_KEEP_ISO prevents the removal of +result_iso after xorriso indicated failure of production. +Exported non-empty variable XORRISO gives the path to a xorriso binary, +which will be used instead of the system-wide installed xorriso binary. +This may be needed if installed xorriso is older than 1.4.2. +If XORRISO is set to "dummy" then no new ISO will emerge. +Exported non-empty variable XORRISO_DD_TARGET_PATH names the directory +where to find xorriso-dd-target, which evaluates the suitability of +result_iso devices or does the plug-test dialog. + + +File: merge_debian_isos.info, Node: Seealso, Next: Bugreport, Prev: Environ, Up: Top + +6 See also +********** + +xorriso(1), xorriso-dd-target(1) + + +File: merge_debian_isos.info, Node: Bugreport, Next: Legal, Prev: Seealso, Up: Top + +7 Reporting bugs +**************** + +To report bugs, request help, or suggest enhancements for +'xorriso-dd-target', please send electronic mail to the public list +. If more privacy is desired, mail to +. + + Please describe what you expect the program to do, the program +arguments which you used, the messages of 'xorriso-dd-target', and the +undesirable outcome of your program run. + + Expect to get asked more questions before solutions can be proposed. + + +File: merge_debian_isos.info, Node: Legal, Next: CommandIdx, Prev: Bugreport, Up: Top + +8 Author, Copyright, Credits +**************************** + +8.1 Author +========== + +Thomas Schmitt +for libburnia-project.org + +8.2 Copyright +============= + +Copyright (c) 2022 Thomas Schmitt +Permission is granted to distribute this text freely. It shall only be +modified in sync with the technical properties of merge_debian_isos. If +you make use of the license to derive modified versions of +merge_debian_isos then you are entitled to modify this text under that +same license. + +8.3 Credits +=========== + +'merge_debian_isos' was originally developed with advise and testing by +Zhang Boyang in the course of Debian bug #1011343. Steve McIntyre +provided information about various file aspects of debian-cd ISO images. + + +File: merge_debian_isos.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top + +9 Alphabetic Options List +************************* + + +File: merge_debian_isos.info, Node: ConceptIdx, Next: Top, Prev: CommandIdx, Up: Top + +10 Alphabetic List of Concepts and Objects +****************************************** + +[index] +* Menu: + +* Bugs, reporting: Bugreport. (line 6) +* Examples: Examples. (line 6) +* merge_debian_isos, options: Options. (line 6) +* Problems, reporting: Bugreport. (line 6) + + + +Tag Table: +Node: Top417 +Node: Overview1014 +Node: Options3381 +Node: Examples3771 +Node: ExPlain4196 +Node: ExXorriso4548 +Node: ExOptical5342 +Node: ExDdTarget6126 +Node: ExStdio7649 +Node: Files8561 +Node: Environ8717 +Node: Seealso9782 +Node: Bugreport9931 +Node: Legal10516 +Node: CommandIdx11344 +Node: ConceptIdx11491 + +End Tag Table diff --git a/test/merge_debian_isos.texi b/test/merge_debian_isos.texi new file mode 100644 index 00000000..6e43c033 --- /dev/null +++ b/test/merge_debian_isos.texi @@ -0,0 +1,434 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename merge_debian_isos.info +@settitle merge_debian_isos 1.5.5 +@c %**end of header +@c +@c man-ignore-lines begin +@dircategory Archiving +@direntry +* Merge_debian_isos: (merge_debian_isos). Merge debian-cd ISO images to a single image +@end direntry +@c man-ignore-lines end +@c +@c Notes about embedded man page: +@c This texinfo code contains the necessary info to produce a man page. +@c One can produce it by applying the following rules: +@c The first line gets discarded. +@c Line start "@c man " will become "", the remainder is put out unaltered. +@c Lines "@*" will be converted to ".br" +@c "@c man-ignore-lines N" will discard N following lines. +@c "@c man-ignore-lines begin" discards all following lines +@c up to "@c man-ignore-lines end". +@c Line blocks of "@menu" "@end menu" will be discarded. +@c "@item word words" becomes "\fBword\fR words". +@c @b{...}, @command{...}, @dfn{...}, @emph{...}, @strong{...} +@c get mapped to \fB...\fR . +@c @abbr{...}, @code{...}, @file{...}, @i{...}, @option{...}, @r{...}, +@c @ref{...}, @samp{...},@var{...}, get mapped to ... . +@c @ref{...}, @xref{...} get mapped to empty text. +@c @email{...} gets mapped to <...> . +@c Mapped {...} content is subject to the rules except {...} mapping. +@c @minus{} will become "-". +@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 -*- +@c man .\" +@c man .\" IMPORTANT NOTE: +@c man .\" +@c man .\" The original of this file is kept in test/merge_debian_isos.texi +@c man .\" This here was generated by program xorriso/make_xorriso_1 +@c man .\" +@c man .\" +@c man .\" First parameter, NAME, should be all caps +@c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +@c man .\" other parameters are allowed: see man(7), man(1) +@c man .TH MERGE_DEBIAN_ISOS 1 "Version 1.5.5, Oct 19, 2022" +@c man .\" Please adjust this date whenever revising the manpage. +@c man .\" +@c man .\" Some roff macros, for reference: +@c man .\" .nh disable hyphenation +@c man .\" .hy enable hyphenation +@c man .\" .ad l left justify +@c man .\" .ad b justify to both left and right margins +@c man .\" .nf disable filling +@c man .\" .fi enable filling +@c man .\" .br insert line break +@c man .\" .sp insert n+1 empty lines +@c man .\" for manpage-specific macros, see man(7) +@c man .nh +@c man-ignore-lines begin +@copying +merge_debian_isos - sh script to merge multiple debian-cd ISO images + +Copyright @copyright{} 2022 Thomas Schmitt + +@quotation +Permission is granted to distribute this text freely. +@end quotation +@end copying +@c man-ignore-lines end +@titlepage +@title Manual of GNU xorriso companion merge_debian_isos 1.5.5 +@author Thomas Schmitt +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage +@contents +@ifnottex +@node Top +@top merge_debian_isos 1.5.5 +@c man-ignore-lines 1 + +@c man .SH NAME +merge_debian_isos - Program to merge multiple debian-cd ISO images +@end ifnottex +@menu +* Overview:: Overview +* Options:: Options +* Examples:: Examples +* Files:: Files +* Environ:: Environment +* Seealso:: See also +* Bugreport:: Reporting bugs +* Legal:: Author, Copyright, Credits +* CommandIdx:: Alphabetic Option List +* ConceptIdx:: Alphabetic List of Concepts and Objects +@end menu +@node Overview, Options, Top, Top +@chapter Overview +@c man .SH SYNOPSIS +@c man .B merge_debian_isos +@c man result_iso mount_template iso1 iso2 [... isoN] +@c man .br +@c man .SH DESCRIPTION +@c man .PP +@command{merge_debian_isos} +mounts by @strong{sudo} the ISO 9660 images iso1 to isoN at directories +mount_template1 to mount_templateN, if not already mounted that way. +Then the Debian pools and package lists get merged and a new +ISO 9660 image result_iso is produced by a run of @strong{xorriso}. +If iso1 is bootable then +the new image will be bootable by the same means. +@* +@sp 1 +@c man .PP +The file depicted by result_iso must not yet exist or has to be a +device which is acceptable for Linux-specific helper script +@strong{xorriso-dd-target}. If xorriso-dd-target agrees and the user +confirms by input "yes" then xorriso will be run under sudo. +@* +Exempted from this evaluation are addresses which begin by "mmc:" +for an optical drive on Linux, BSDs, Solaris, or by "stdio:/dev/" +for which the user takes full and dangerous responsibility. +@* +Special result_iso path @strong{xorriso-dd-target-plug-test} determines +on systems with Linux kernel the target USB stick by a dialog around plugging +it in. +xorriso will be run under sudo, if xorriso-dd-target agrees and +the user confirms by input "yes". +@* +@sp 1 +@c man .PP +At least the parent directory of argument @strong{mount_template} must already +exist or has to be given by a plain name without "/" so that it can be +created in the current directory. (I.e. without even "./".) +@* +All arguments must be single words without using quotation marks. +None of the isoN must be equal to another isoM. +@* +@sp 1 +@c man .PP +This script creates and finally removes the following temporary tree +and files which must not yet exist in the current working directory: + ./merged_dists , ./merged_md5sum.txt , ./merged_REAMDE.txt + ./temp_file +@* +Further it creates and finally removes directories mount_template* +if they are needed and do not exist when the script starts. If the +parent directory in the mount_template path does not exist and +its path contains no "/" then it gets created and finally removed. +The script depends on the following programs: +@* + awk, basename, cat, chmod, cp, date, dirname, expr, fgrep, grep, + gunzip, gzip, head, ls, md5sum, mkdir, mount, mv, rm, rmdir, + sed, sh, sha256sum, sort, stat, sudo, umount, uniq, xorriso +@* +With device writing involving helper script xorriso-dd-target: +@* + dd, Linux kernel, lsblk, sleep, tr, uname, wc, whoami, + xorriso-dd-target +@* +Recommended are: sha1sum, sha512sum + +@c man .SS +@node Options, Examples, Overview, Top +@chapter Options +@cindex merge_debian_isos, options +@c man .br +@c man .SH OPTIONS +@c man .br +@c man .PP +merge_debian_isos has no command line options besides the input words described +above, but it reacts on some environment variables. +@c man .br +@c man See section ENVIRONMENT. +@* +@sp 1 +@c man .PP +If less than 4 arguments are given, the script will print its help text to +standard error and exit with non-zero value, indicating failure. +@c man .SS +@node Examples, Files, Options, Top +@chapter Examples +@c man .SH EXAMPLES +@c man .SS +@c man .B Overview of examples: +@c man Merge DVD images 1 to 5 +@c man .br +@c man Use GNU xorriso instead of installed xorriso +@c man .br +@c man Write result directly to an optical drive +@c man .br +@c man Write result directly and safely to USB stick (Linux only) +@c man .br +@c man Write result directly and unsafely to USB stick +@cindex Examples +@menu +* ExPlain:: Merge DVD images 1 to 5 +* ExXorriso:: Use GNU xorriso instead of installed xorriso +* ExOptical:: Write result directly to an optical drive +* ExDdTarget:: Write result directly and safely to USB stick (Linux only) +* ExStdio:: Write result directly and unsafely to USB stick +@end menu +@c man .SS +@c man .B Merge DVD images 1 to 5 +@node ExPlain, ExXorriso, Options, Examples +@section Merge DVD images 1 to 5 +The resulting image will be named "merged.iso". +@* +Directory ./merge_mount/ will be created if not yet existing. +@* +@sp 1 + +merge_debian_isos merged.iso merge_mount/iso \ + debian-11.2.0-amd64-DVD-[12345].iso + +@c man .SS +@c man .B Use GNU xorriso instead of installed xorriso +@node ExXorriso, ExOptical, ExPlain, Examples +@section Use GNU xorriso instead of installed xorriso +merge_debian_isos will refuse to work if the installed version of xorriso +is older than 1.4.2. In this case consider to download and compile the +GNU xorriso tarball from +@* + https://www.gnu.org/software/xorriso/#download +@* +You may use it without installing it after compilation and thus without +disturbing your system's package management. Assumed that you unpacked the +xorriso-1.5.4 tarball in your $HOME directory and have successfully compiled +it, do: +@* +@sp 1 + +export XORRISO="$HOME"/xorriso-1.5.4/xorriso/xorriso +@* +@sp 1 + +merge_debian_isos merged.iso merge_mount/iso \ + debian-11.2.0-amd64-DVD-[12345].iso + +@c man .SS +@c man .B Write result directly to an optical drive +@node ExOptical, ExDdTarget, ExXorriso, Examples +@section Write result directly to an optical drive +xorriso is able to burn optical media on GNU/Linux (/dev/sr*), +Solaris (/dev/rdsk/*) , FreeBSD (/dev/cd*) , NetBSD (/dev/rcd*), +and OpenBSD (/dev/rcd*). Get a list of available optical drive devices by: +@* +@sp 1 + +xorriso -devices +@* +@sp 1 + +It might be that you need superuser powers for this and then have to enable +access to the device file for the user who runs merge_debian_isos. +@* +@sp 1 + +In order to directly write the merged ISO image to an optical medium, +use the desired device file path with prefix "mmc:": +@* +@sp 1 + +merge_debian_isos mmc:/dev/sr0 merge_mount/iso \ + debian-11.2.0-amd64-DVD-[12345].iso + +@c man .SS +@c man .B Write result directly and safely to USB stick (Linux only) +@node ExDdTarget, ExStdio, ExOptical, Examples +@section Write result directly and safely to USB stick (Linux only) +The Linux-specific script @strong{xorriso-dd-target} evaluates device files +whether they and their content look unimportant enough for being overwritten +by an image file. +@* +This mainly means that the storage device is attached to USB and contains +no filesystems which are not of type FAT or ISO 9660. +@* +You may get xorriso-dd-target by: +@* +@sp 1 + +wget \ + https://dev.lovelyhq.com/libburnia/libisoburn/raw/master/xorriso-dd-target/xorriso-dd-target +chmod u+x xorriso-dd-target +@* +@sp 1 + +Consider to also download xorriso-dd-target.sig and to verify the script by +@* +@sp 1 + +gpg --verify xorriso-dd-target.sig xorriso-dd-target +@* +@sp 1 + +Announce the storage location of the downloaded xorriso-dd-target: +@* +@sp 1 + +export XORRISO_DD_TARGET_PATH="$(pwd)" +@* +@sp 1 + +The prepared use case in merge_debian_isos uses the xorriso-dd-target +option -plug_test under @strong{sudo}, which asks the user for first having +the desired USB stick unplugged so that the unwanted devices can get +registered. Then it asks the user to plug in the USB stick, so that it gets +recognized as desired target. +@* +xorriso-dd-target evaluates the content and decides whether it looks +disposable enough. If so, then it allows merge_debian_isos to write its +result to the device. +@* +@sp 1 + +merge_debian_isos xorriso-dd-target-plug-test merge_mount/iso \ + debian-11.2.0-amd64-DVD-[12345].iso + +@c man .SS +@c man .B Write result directly and unsafely to USB stick +@node ExStdio, Files, ExDdTarget, Examples +@section Write result directly and unsafely to USB stick +On operating systems other than GNU/Linux or with storage devices not +acceptable to xorriso-dd-target it is possible to remove all safety +precautions beyond those of xorriso, which can be overcome by "blanking" +the device. +@* +So after due evaluation of the device situation and on your very own risk +you may use the device path prefix "stdio:", possibly with superuser powers: +@* +@sp 1 + +xorriso -outdev stdio:/dev/sdd -blank as_needed + +merge_debian_isos stdio:/dev/sdd merge_mount/iso \ + debian-11.2.0-amd64-DVD-[12345].iso + +For details about "stdio:" and pseudo-blanking non-optical devices read +man xorriso. +@* +The xorriso run in merge_debian_isos ignores locally defined xorriso startup +files (by command -no_rc). +@node Files, Environ, Examples, Top +@chapter Files +@c man .SH FILES +For now, no files are defined for configuration. +@c man .SH ENVIRONMENT +@node Environ, Seealso, Files, Top +@chapter Environ +The following environment variables influence the program behavior: +@* +Exported non-empty variable MERGE_DATE enforces a particular +date string in the text which gets prepended to /README.txt . +@* +Exported non-empty variable MERGE_FOR_DIST enforces the use of a +particular directory in /dists of iso1. Normally only one +such directory is found and thus no need to set MERGE_FOR_DIST. +@* +Exported non-empty variable MERGE_KEEP_ISO prevents the removal +of result_iso after xorriso indicated failure of production. +@* +Exported non-empty variable XORRISO gives the path to a xorriso binary, +which will be used instead of the system-wide installed xorriso binary. +This may be needed if installed xorriso is older than 1.4.2. +@* +If XORRISO is set to "dummy" then no new ISO will emerge. +@* +Exported non-empty variable XORRISO_DD_TARGET_PATH names the +directory where to find xorriso-dd-target, which evaluates the +suitability of result_iso devices or does the plug-test dialog. +@* +@c man .SH SEE ALSO +@c man .BR xorriso(1), +@c man .BR xorriso-dd-target(1), +@c man-ignore-lines begin +@node Seealso, Bugreport, Environ, Top +@chapter See also +xorriso(1), xorriso-dd-target(1) +@c man-ignore-lines end +@c man .SH BUGS +@node Bugreport, Legal, Seealso, Top +@chapter Reporting bugs +@cindex Bugs, reporting +@cindex Problems, reporting +To report bugs, request help, or suggest enhancements for +@command{xorriso-dd-target}, +please send electronic mail to the public list @email{bug-xorriso@@gnu.org}. +If more privacy is desired, mail to @email{scdbackup@@gmx.net}. +@* +@sp 1 +Please describe what you expect the program to do, the program arguments +which you used, the messages of @command{xorriso-dd-target}, and the +undesirable outcome of your program run. +@* +@sp 1 +Expect to get asked more questions before solutions can be proposed. +@c man .SH AUTHOR +@node Legal, CommandIdx, Bugreport, Top +@chapter Author, Copyright, Credits +@section Author +Thomas Schmitt +@* +for libburnia-project.org +@c man .SH COPYRIGHT +@section Copyright +Copyright (c) 2022 Thomas Schmitt +@* +Permission is granted to distribute this text freely. It shall only be +modified in sync with the technical properties of merge_debian_isos. +If you make use of the license to derive modified versions of merge_debian_isos +then you are entitled to modify this text under that same license. +@c man .SH CREDITS +@section Credits +@command{merge_debian_isos} was originally developed with advise and testing +by Zhang Boyang in the course of Debian bug #1011343. Steve McIntyre provided +information about various file aspects of debian-cd ISO images. +@c man-ignore-lines begin +@node CommandIdx, ConceptIdx, Legal, Top +@chapter Alphabetic Options List +@printindex ky + +@node ConceptIdx, Top, CommandIdx, Top +@chapter Alphabetic List of Concepts and Objects +@printindex cp + +@c man-ignore-lines end +@bye