libisoburn/test/merge_debian_isos.texi

\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 <n>    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{merge_debian_isos}, 
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{merge_debian_isos}, 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 <scdbackup@@gmx.net>
@*
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