New paragraph "Reproducibility considerations" moved out of ENVIRONMENT

xorriso/xorriso.texi

@@ -50,7 +50,7 @@
 @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 XORRISO 1 "Version 1.5.7, Apr 24, 2025"
+@c man .TH XORRISO 1 "Version 1.5.7, Jun 10, 2025"
 @c man .\" Please adjust this date whenever revising the manpage.
 @c man .\"
 @c man .\" Some roff macros, for reference:
@@ -844,6 +844,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
 @end menu
 @c man .TP
 @node ArgSort, AqDrive, Commands, Commands
@@ -7227,7 +7228,7 @@ Do not execute the line but store it in readline history.
 @end table
 @c man .TP
 @c man .B Support for frontend programs via stdin and stdout:
-@node Frontend, ExDevices, Scripting, Commands
+@node Frontend, Reproducible, Scripting, Commands
 @section Support for frontend programs via stdin and stdout
 @table @asis
 @c man .TP
@@ -7479,6 +7480,57 @@ Use text as name of this program in subsequent messages
 @cindex Program, print help text, -prog_help
 Use text as name of this program and perform -help.
 @end table
+@c man .TP
+@c man .B Reproducibility considerations:
+@node Reproducible, Examples, Frontend, Commands
+@section Reproducibility considerations
+@c man .PP
+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.
+@c man .PP
+@sp 1
+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.
+@c man .PP
+@sp 1
+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.
+@*
 @c man .br
 @node Examples, Files, Commands, Top
 @chapter Examples
@@ -8215,27 +8267,7 @@ 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.
+See above paragraph "Reproducibility considerations".
 @*
 @sp 1
 @c man .SS