1 files changed, 107 insertions, 0 deletions
diff --git a/doc/lzma-intro.txt b/doc/lzma-intro.txt
new file mode 100644
index 00000000..bde8a059
--- /dev/null
+++ b/doc/lzma-intro.txt
@@ -0,0 +1,107 @@
+
+Introduction to the lzma command line tool
+------------------------------------------
+
+Overview
+
+    The lzma command line tool is similar to gzip and bzip2, but for
+    compressing and uncompressing .lzma files.
+
+
+Supported file formats
+
+    By default, the tool creates files in the new .lzma format. This can
+    be overriden with --format=FMT command line option. Use --format=alone
+    to create files in the old LZMA_Alone format.
+
+    By default, the tool uncompresses both the new .lzma format and
+    LZMA_Alone format. This is to make it transparent to switch from
+    the old LZMA_Alone format to the new .lzma format. Since both
+    formats use the same filename suffix, average user should never
+    notice which format was used.
+
+
+Differences to gzip and bzip2
+
+  Standard input and output
+
+    Both gzip and bzip2 refuse to write compressed data to a terminal and
+    read compressed data from a terminal. With gzip (but not with bzip2),
+    this can be overriden with the `--force' option. lzma follows the
+    behavior of gzip here.
+
+  Usage of LZMA_OPT environment variable
+
+    gzip and bzip2 read GZIP and BZIP2 environment variables at startup.
+    These variables may contain extra command line options.
+
+    gzip and bzip2 allow passing not only options, but also end-of-options
+    indicator (`--') and filenames via the environment variable. No quoting
+    is supported with the filenames.
+
+    Here are examples with gzip. bzip2 behaves identically.
+
+        bash$ echo asdf > 'foo bar'
+        bash$ GZIP='"foo bar"' gzip
+        gzip: "foo: No such file or directory
+        gzip: bar": No such file or directory
+
+        bash$ GZIP=-- gzip --help
+        gzip: --help: No such file or directory
+
+    lzma silently ignores all non-option arguments given via the
+    environment variable LZMA_OPT. Like on the command line, everything
+    after `--' is taken as non-options, and thus ignored in LZMA_OPT.
+
+        bash$ LZMA_OPT='--help' lzma --version     # Displays help
+        bash$ LZMA_OPT='-- --help' lzma --version  # Displays version
+
+
+Filter chain presets
+
+    Like in gzip and bzip2, lzma supports numbered presets from 1 to 9
+    where 1 is the fastest and 9 the best compression. 1 and 2 are for
+    fast compressing with small memory usage, 3 to 6 for good compression
+    ratio with medium memory usage, and 7 to 9 for excellent compression
+    ratio with higher memory requirements. The default is 7 if memory
+    usage limit allows.
+
+    In future, there will probably be an option like --preset=NAME, which
+    will contain more special presets for specific file types.
+
+    It's also possible that there will be some heuristics to select good
+    filters. For example, the tool could detect when a .tar archive is
+    being compressed, and enable x86 filter only for those files in the
+    .tar archive that are ELF or PE executables for x86.
+
+
+Specifying custom filter chains
+
+    Custom filter chains are specified by using long options with the name
+    of the filters in correct order. For example, to pass the input data to
+    the x86 filter and the output of that to the LZMA filter, the following
+    command will do:
+
+        lzma --x86 --lzma filename
+
+    Some filters accept options, which are specified as a comma-separated
+    list of key=value pairs:
+
+        lzma --delta=distance=4 --lzma=dict=4Mi,lc=8,lp=2 filename
+
+
+Memory usage control
+
+    By default, the command line tool limits memory usage to 1/3 of the
+    available physical RAM. If no preset or custom filter chain has been
+    given, the default preset will be used. If the memory limit is too
+    low for the default preset, the tool will silently switch to lower
+    preset.
+
+    When a preset or a custom filter chain has been specified and the
+    memory limit is too low, an error message is displayed and no files
+    are processed.
+
+    If the decoder hits the memory usage limit, an error is displayed and
+    no more files are processed.
+