Index: README |
=================================================================== |
--- README (revision 87706) |
+++ README (working copy) |
@@ -5,7 +5,7 @@ |
0. Overview |
1. Documentation |
1.1. Overall documentation |
- 1.2. Documentation for command line tools |
+ 1.2. Documentation for command-line tools |
1.3. Documentation for liblzma |
2. Version numbering |
3. Reporting bugs |
@@ -17,21 +17,21 @@ |
0. Overview |
----------- |
- XZ Utils provide a general-purpose data compression library and |
- command line tools. The native file format is the .xz format, but |
+ XZ Utils provide a general-purpose data-compression library plus |
+ command-line tools. The native file format is the .xz format, but |
also the legacy .lzma format is supported. The .xz format supports |
- multiple compression algorithms, which are called "filters" in |
+ multiple compression algorithms, which are called "filters" in the |
context of XZ Utils. The primary filter is currently LZMA2. With |
typical files, XZ Utils create about 30 % smaller files than gzip. |
To ease adapting support for the .xz format into existing applications |
and scripts, the API of liblzma is somewhat similar to the API of the |
- popular zlib library. For the same reason, the command line tool xz |
- has similar command line syntax than that of gzip. |
+ popular zlib library. For the same reason, the command-line tool xz |
+ has a command-line syntax similar to that of gzip. |
- When aiming for the highest compression ratio, LZMA2 encoder uses |
+ When aiming for the highest compression ratio, the LZMA2 encoder uses |
a lot of CPU time and may use, depending on the settings, even |
- hundreds of megabytes of RAM. However, in fast modes, LZMA2 encoder |
+ hundreds of megabytes of RAM. However, in fast modes, the LZMA2 encoder |
competes with bzip2 in compression speed, RAM usage, and compression |
ratio. |
@@ -44,8 +44,8 @@ |
since that needs to be done only once to benefit many people. |
With some file types, combining (or "chaining") LZMA2 with an |
- additional filter can improve compression ratio. A filter chain may |
- contain up to four filters, although usually only one two is used. |
+ additional filter can improve the compression ratio. A filter chain may |
+ contain up to four filters, although usually only one or two are used. |
For example, putting a BCJ (Branch/Call/Jump) filter before LZMA2 |
in the filter chain can improve compression ratio of executable files. |
@@ -88,9 +88,9 @@ |
packages. |
-1.2. Documentation for command line tools |
+1.2. Documentation for command-line tools |
- The command line tools are documented as man pages. In source code |
+ The command-line tools are documented as man pages. In source code |
releases (and possibly also in some binary packages), the man pages |
are also provided in plain text (ASCII only) and PDF formats in the |
directory "doc/man" to make the man pages more accessible to those |
@@ -109,8 +109,8 @@ |
written yet. |
For now, if you have never used liblzma, libbzip2, or zlib, I |
- recommend learning *basics* of zlib API. Once you know that, it |
- should be easier to learn liblzma. |
+ recommend learning the *basics* of the zlib API. Once you know that, |
+ it should be easier to learn liblzma. |
http://zlib.net/manual.html |
http://zlib.net/zlib_how.html |
@@ -124,23 +124,27 @@ |
- X is the major version. When this is incremented, the library |
API and ABI break. |
- - Y is the minor version. It is incremented when new features are |
- added without breaking existing API or ABI. Even Y indicates |
- stable release and odd Y indicates unstable (alpha or beta |
- version). |
+ - Y is the minor version. It is incremented when new features |
+ are added without breaking the existing API or ABI. An even Y |
+ indicates a stable release and an odd Y indicates unstable |
+ (alpha or beta version). |
- - Z is the revision. This has different meaning for stable and |
+ - Z is the revision. This has a different meaning for stable and |
unstable releases: |
+ |
* Stable: Z is incremented when bugs get fixed without adding |
- any new features. |
+ any new features. This is intended to be convenient for |
+ downstream distributors that want bug fixes but don't want |
+ any new features to minimize the risk of introducing new bugs. |
+ |
* Unstable: Z is just a counter. API or ABI of features added |
in earlier unstable releases having the same X.Y may break. |
- S indicates stability of the release. It is missing from the |
- stable releases where Y is an even number. When Y is odd, S |
+ stable releases, where Y is an even number. When Y is odd, S |
is either "alpha" or "beta" to make it very clear that such |
versions are not stable releases. The same X.Y.Z combination is |
- not used for more than one stability level i.e. after X.Y.Zalpha, |
+ not used for more than one stability level, i.e. after X.Y.Zalpha, |
the next version can be X.Y.(Z+1)beta but not X.Y.Zbeta. |
@@ -176,7 +180,7 @@ |
Don't send core dump files or any executables. If you have a small |
example file(s) (total size less than 256 KiB), please include |
it/them as an attachment. If you have bigger test files, put them |
- online somewhere and include an URL to the file(s) in the bug report. |
+ online somewhere and include a URL to the file(s) in the bug report. |
Always include the exact version number of XZ Utils in the bug report. |
If you are using a snapshot from the git repository, use "git describe" |
@@ -193,7 +197,7 @@ |
The messages from the xz tool have been translated into a few |
languages. Before starting to translate into a new language, ask |
- the author that someone else hasn't already started working on it. |
+ the author whether someone else hasn't already started working on it. |
Test your translation. Testing includes comparing the translated |
output to the original English version by running the same commands |
@@ -214,7 +218,7 @@ |
Note especially the following: |
- The output of --help and --long-help must look nice on |
- a 80-column terminal. It's OK to add extra lines if needed. |
+ an 80-column terminal. It's OK to add extra lines if needed. |
- In contrast, don't add extra lines to error messages and such. |
They are often preceded with e.g. a filename on the same line, |