compression: update / refine docs

README.rst

@@ -51,7 +51,8 @@ Main features
     authenticity is verified using HMAC-SHA256.
 
 **Compression**
-    All data can be compressed by lz4, zlib or lzma.
+    All data can be compressed by lz4 (super fast, low compression), zlib
+    (medium speed and compression) or lzma (low speed, high compression).
 
 **Off-site backups**
     Borg can store data on any remote host accessible over SSH.  If Borg is

docs/internals.rst

@@ -386,19 +386,29 @@ Compression
 
 - none (no compression, pass through data 1:1)
 - lz4 (low compression, but super fast)
-- zlib (level 1-9, level 1 is low, level 9 is high compression)
-- lzma (level 0-9, level 0 is low, level 9 is high compression.
+- zlib (level 0-9, level 0 is no compression [but still adding zlib overhead],
+  level 1 is low, level 9 is high compression)
+- lzma (level 0-9, level 0 is low, level 9 is high compression).
 
 Speed:  none > lz4 > zlib > lzma
 Compression: lzma > zlib > lz4 > none
 
+Be careful, higher zlib and especially lzma compression levels might take a
+lot of resources (CPU and memory).
+
 The overall speed of course also depends on the speed of your target storage.
 If that is slow, using a higher compression level might yield better overall
 performance. You need to experiment a bit. Maybe just watch your CPU load, if
 that is relatively low, increase compression until 1 core is 70-100% loaded.
 
-Be careful, higher zlib and especially lzma compression levels might take a
-lot of resources (CPU and memory).
+Even if your target storage is rather fast, you might see interesting effects:
+while doing no compression at all (none) is a operation that takes no time, it
+likely will need to store more data to the storage compared to using lz4.
+The time needed to transfer and store the additional data might be much more
+than if you had used lz4 (which is super fast, but still might compress your
+data about 2:1). This is assuming your data is compressible (if you backup
+already compressed data, trying to compress them at backup time is usually
+pointless).
 
 Compression is applied after deduplication, thus using different compression
 methods in one repo does not influence deduplication.

docs/quickstart.rst

@@ -101,11 +101,13 @@ If you have a quick repo storage and you want a little compression:
 
     $ borg create --compression lz4 /mnt/backup::repo ~
 
-If you have a medium fast repo storage and you want a bit more compression (N=0..9):
+If you have a medium fast repo storage and you want a bit more compression (N=0..9,
+0 means no compression, 9 means high compression):
 
     $ borg create --compression zlib,N /mnt/backup::repo ~
 
-If you have a very slow repo storage and you want high compression (N=0..9):
+If you have a very slow repo storage and you want high compression (N=0..9, 0 means
+low compression, 9 means high compression):
 
     $ borg create --compression lzma,N /mnt/backup::repo ~
 

docs/support.rst

@@ -4,6 +4,9 @@
 Support
 =======
 
+Please first read the docs and the FAQ section in the docs, a lot of stuff is
+documented / explained there.
+
 Issue Tracker
 -------------
 

docs/usage.rst

@@ -76,8 +76,7 @@ Resource Usage
 |project_name| might use a lot of resources depending on the size of the data set it is dealing with.
 
 CPU: it won't go beyond 100% of 1 core as the code is currently single-threaded.
-     Especially higher zlib and lzma compression uses significant amounts of CPU
-     cycles.
+     Especially higher zlib and lzma compression levels use significant amounts of CPU cycles.
 
 Memory (RAM): the chunks index and the files index are read into memory for performance reasons.
               compression, esp. lzma compression with high levels might need substantial amounts