New paragraph "Reproducibility considerations" moved out of ENVIRONMENT

xorriso/xorriso.info

@@ -595,6 +595,7 @@ inner dashes are interpreted as underscores.
 * Emulation::           Command compatibility emulations (cdrtools)
 * Scripting::           Scripting, dialog and program control features
 * Frontend::            Support for frontend programs via stdin and stdout
+* Reproducible::        Reproducibility considerations
 
 
 File: xorriso.info,  Node: ArgSort,  Next: AqDrive,  Prev: Commands,  Up: Commands
@@ -5330,7 +5331,7 @@ File: xorriso.info,  Node: Scripting,  Next: Frontend,  Prev: Emulation,  Up: Co
      readline history.
 
 
-File: xorriso.info,  Node: Frontend,  Next: ExDevices,  Prev: Scripting,  Up: Commands
+File: xorriso.info,  Node: Frontend,  Next: Reproducible,  Prev: Scripting,  Up: Commands
 
 9.22 Support for frontend programs via stdin and stdout
 =======================================================
@@ -5509,6 +5510,52 @@ File: xorriso.info,  Node: Frontend,  Next: ExDevices,  Prev: Scripting,  Up: Co
 -prog_help text
      Use text as name of this program and perform -help.
 
+
+File: xorriso.info,  Node: Reproducible,  Next: Examples,  Prev: Frontend,  Up: Commands
+
+9.23 Reproducibility considerations
+===================================
+
+Stable versions of xorriso are prepared to produce in repeated runs from
+the same input files with the same file metadata and the same xorriso
+commands the same ISO 9660 filesystem bytes.  The only exception are
+bytes which depend on the current time of the xorriso run.
+These time dependent values can be set to fixed values by the commands
+-volume_date "uuid", -boot_image "any" "gpt_disk_guid=", -volume_date
+"all_file_dates", and -iso_nowtime.  Instead of setting each of them, it
+is possible to influence them all by the environment variable
+SOURCE_DATE_EPOCH.
+SOURCE_DATE_EPOCH belongs to the specification of
+reproducible-builds.org.  It is supposed to be either undefined or to
+contain a decimal number which tells the seconds since january 1st 1970.
+If it contains a number, then it is used as time value to set the
+default of -volume date "uuid", sets -boot_image "any" "gpt_disk_guid="
+to "volume_date_uuid", -volume_date "all_file_dates" to "set_to_mtime",
+and -iso_nowtime.
+Startup files and xorriso commands can override the effect of
+SOURCE_DATE_EPOCH.
+
+   Different versions of xorriso may or may not produce the same result
+from the same input and commands.  Reproducibility may be prevented by
+bug fixes or feature enhancements between versions.
+xorriso puts its version information into the Preparer Id field of the
+ISO 9660 Primary Volume Descriptor by default.  This may be desired in
+order to clearly define which xorriso version has to be used for
+reproduction.  But it may also be undesired because a wider range of
+xorriso versions shall not be excluded from an attempt of reproduction.
+Use command -preparer_id with a text other than "@xorriso@" if you want
+to override the default at first production time.  This command may also
+be used to explicitly set the preparer id as found in an ISO 9660
+filesystem which shall be reproduced by a different version of xorriso.
+The preparer id can be inquired by command -pvd_info.
+
+   If reproducibility of xorriso results is desired, then the
+precautions - like setting SOURCE_DATE_EPOCH - should be done already
+with the original xorriso run.  All input files, the used xorriso
+commands in exact sequence, the version of xorriso, and the possibly set
+SOURCE_DATE_EPOCH value should then be kept or recorded for later
+re-use.
+
 
 File: xorriso.info,  Node: Examples,  Next: Files,  Prev: Commands,  Up: Top
 
@@ -6048,26 +6095,8 @@ File: xorriso.info,  Node: Environ,  Next: Seealso,  Prev: Files,  Up: Top
 
 The following environment variables influence the program behavior:
 HOME is used to find startup files of xorriso and mkisofs.
-SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org.  It
-is supposed to be either undefined or to contain a decimal number which
-tells the seconds since january 1st 1970.  If it contains a number, then
-it is used as time value to set the default of -volume date "uuid", sets
--boot_image "any" "gpt_disk_guid=" to "volume_date_uuid", -volume_date
-"all_file_dates" to "set_to_mtime", and -iso_nowtime to
-"=$SOURCE_DATE_EPOCH".
-Startup files and program commands can override the effect of
-SOURCE_DATE_EPOCH.
-Be aware that by default xorriso puts its version information into the
-Preparer Id field of the ISO 9660 Primary Volume Descriptor.  This may
-be desired in order to clearly define which xorriso version has to be
-used for reproduction.  But it may also be undesired because a wider
-range of xorriso versions shall not be excluded from an attempt of
-reproduction.
-Use command -preparer_id with a text other than "@xorriso@" if you want
-to override the default at first production time.  This command may also
-be used to explicitly set the preparer id as found in an ISO 9660
-filesystem which shall be reproduced by a different version of xorriso.
-The id can be inquired by command -pvd_info.
+SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org.  See
+above paragraph "Reproducibility considerations".
 
 
 File: xorriso.info,  Node: Seealso,  Next: Bugreport,  Prev: Environ,  Up: Top
@@ -6783,51 +6812,52 @@ Node: Extras15805
 Node: Processing21907
 Node: Dialog25744
 Node: Commands27433
-Node: ArgSort29110
-Node: AqDrive30604
-Node: Loading37784
-Node: Insert68537
-Node: SetInsert80732
-Node: Manip90968
-Node: CmdFind103464
-Node: Filter125324
-Node: Writing129946
-Node: SetWrite142440
-Node: Bootable173872
-Node: Jigdo206606
-Node: Charset211609
-Node: Exception214938
-Node: DialogCtl221127
-Node: Inquiry223729
-Node: Navigate236424
-Node: Verify248477
-Node: Restore259626
-Node: Emulation271833
-Node: Scripting283409
-Node: Frontend291664
-Node: Examples301290
-Node: ExDevices302468
-Node: ExCreate303129
-Node: ExDialog304429
-Node: ExGrowing305700
-Node: ExModifying306509
-Node: ExBootable307019
-Node: ExCharset307574
-Node: ExPseudo308470
-Node: ExCdrecord309397
-Node: ExMkisofs309717
-Node: ExGrowisofs311614
-Node: ExException312767
-Node: ExTime313225
-Node: ExIncBackup313683
-Node: ExRestore317709
-Node: ExRecovery318655
-Node: Files319227
-Node: Environ320561
-Node: Seealso322000
-Node: Bugreport322800
-Node: Legal323391
-Node: CommandIdx324403
-Node: ConceptIdx343709
+Node: ArgSort29165
+Node: AqDrive30659
+Node: Loading37839
+Node: Insert68592
+Node: SetInsert80787
+Node: Manip91023
+Node: CmdFind103519
+Node: Filter125379
+Node: Writing130001
+Node: SetWrite142495
+Node: Bootable173927
+Node: Jigdo206661
+Node: Charset211664
+Node: Exception214993
+Node: DialogCtl221182
+Node: Inquiry223784
+Node: Navigate236479
+Node: Verify248532
+Node: Restore259681
+Node: Emulation271888
+Node: Scripting283464
+Node: Frontend291719
+Node: Reproducible301348
+Node: Examples303809
+Node: ExDevices304987
+Node: ExCreate305648
+Node: ExDialog306948
+Node: ExGrowing308219
+Node: ExModifying309028
+Node: ExBootable309538
+Node: ExCharset310093
+Node: ExPseudo310989
+Node: ExCdrecord311916
+Node: ExMkisofs312236
+Node: ExGrowisofs314133
+Node: ExException315286
+Node: ExTime315744
+Node: ExIncBackup316202
+Node: ExRestore320228
+Node: ExRecovery321174
+Node: Files321746
+Node: Environ323080
+Node: Seealso323431
+Node: Bugreport324231
+Node: Legal324822
+Node: CommandIdx325834
+Node: ConceptIdx345140
 
 End Tag Table