New -zisofs parameters version_2=, block_size_v2=, max_bpt=, max_bpt_f=

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.3, Sep 30, 2020"
+@c man .TH XORRISO 1 "Version 1.5.3, Oct 14, 2020"
 @c man .\" Please adjust this date whenever revising the manpage.
 @c man .\"
 @c man .\" Some roff macros, for reference:
@@ -3603,23 +3603,61 @@ User id to be used for all files when the new ISO tree gets written to media.
 @cindex Group, global in ISO image, -gid
 Group id to be used for all files when the new ISO tree gets written to media.
 @c man .TP
-@item -zisofs option[:options]
+@item -zisofs parameter[:parameters]
 @kindex -zisofs   controls zisofs production
 @cindex Filter, zisofs parameters, -zisofs
 Set global parameters for zisofs compression. This data format is recognized
 and transparently uncompressed by some Linux kernels. It is to be applied
 via command -set_filter with built-in filter "@minus{}@minus{}zisofs".
+@*
+Note: This command is only permitted while no --zisofs filters are applied to
+any files.
+@*
 Parameters are:
 @*
  "level="[0-9] zlib compression: 0=none, 1=fast,..., 9=slow
 @*
- "block_size="32k|64k|128k size of compression blocks
+ "block_size="32k|64k|128k sets the size of version 1 compression blocks.
 @*
  "by_magic=on" enables an expensive test at image generation time which checks
 files from disk whether they already are zisofs compressed, e.g. by program
 mkzftree.
 @*
- "default" same as "level=6:block_size=32k:by_magic=off"
+ "version_2="off|as_needed|on enables the use of experimental version zisofs2
+which can encode files of size 4 GiB or larger. The Linux kernel (as of 5.9)
+does not yet know this format and will complain like
+@*
+  isofs: Unknown ZF compression algorithm: PZ
+@*
+The files will then appear in their compressed form with zisofs2 header,
+block pointer list, and compressed data.
+@*
+zisofs2 is recognized by xorriso in files from loaded images and gets equipped
+with --zisofs-decode filters, unless restrictions on the number of
+block pointers prevent this.
+@*
+Mode "off" restricts compression to files smaller than 4 GiB uncompressed size.
+Mode "as_needed" uses zisofs2 for larger files. Mode "on" uses zisofs2 for all
+zisofs compressed files.
+@*
+ "block_size_v2="32k|64k|128k|256k|512k|1m sets the size of compression blocks
+for zisofs2.
+@*
+ "max_bpt="1k|...|128g sets the limit for the overall allocated block pointer
+memory. Block pointers occupy virtual memory while a file gets uncompressed
+and while a file, which shall be compressed, waits for ISO filesystem creation.
+@*
+One pointer occupies 8 bytes of memory and governs block_size or block_size_v2
+uncompressed bytes.
+I.e. with block size 128k, 1m of block pointer memory suffices for 16g of
+uncompressed file size.
+@*
+ "max_bpt_f="1k|...|128g sets the limit for the memory size of the block
+pointer list of a single file. max_bpt_f is never larger than max_bpt.
+If either is set to violate this rule, the other gets set to the same value.
+@*
+ "default" same as "level=6:block_size=32k:by_magic=off:
+version_2=off:block_size_v2=128k:max_bpt=256m:max_bpt_f=256m".
 @c man .TP
 @item -speed code|number[k|m|c|d|b]
 @kindex -speed   set write speed
@@ -5333,6 +5371,14 @@ Frequently used types are:
  cout:'disk_path offset count'  for -cut_out files.
 @*
  extf:'filter_name' for external filters.
+@*
+ --zisofs:algorithm:block_size  for zisofs compression filters.
+@*
+ --zisofs-decode:algorithm:block_size  for zisofs uncompression filters.
+@*
+ --gzip for internal gzip compression filters.
+@*
+ --gunzip for internal gzip uncompression filters.
 @*
 Example:
 @*