updated doc to underline difference between block and frame

as this is a very frequent source of confusion for new users.

doc/lz4_manual.html

@@ -26,19 +26,23 @@
   multiple GB/s per core, typically reaching RAM speed limits on multi-core systems.
 
   The LZ4 compression library provides in-memory compression and decompression functions.
+  It gives full buffer control to user.
   Compression can be done in:
     - a single step (described as Simple Functions)
     - a single step, reusing a context (described in Advanced Functions)
     - unbounded multiple steps (described as Streaming compression)
 
-  lz4.h provides block compression functions. It gives full buffer control to user.
-  Decompressing an lz4-compressed block also requires metadata (such as compressed size).
-  Each application is free to encode such metadata in whichever way it wants.
+  lz4.h generates and decodes LZ4-compressed blocks (doc/lz4_Block_format.md).
+  Decompressing a block requires additional metadata, such as its compressed size.
+  Each application is free to encode and pass such metadata in whichever way it wants.
 
-  An additional format, called LZ4 frame specification (doc/lz4_Frame_format.md),
-  take care of encoding standard metadata alongside LZ4-compressed blocks.
-  Frame format is required for interoperability.
-  It is delivered through a companion API, declared in lz4frame.h.
+  lz4.h only handle blocks, it can not generate Frames.
+
+  Blocks are different from Frames (doc/lz4_Frame_format.md).
+  Frames bundle both blocks and metadata in a specified manner.
+  This are required for compressed data to be self-contained and portable.
+  Frame format is delivered through a companion API, declared in lz4frame.h.
+  Note that the `lz4` CLI can only manage frames.
 <BR></pre>
 
 <a name="Chapter2"></a><h2>Version</h2><pre></pre>

lib/README.md

@@ -16,13 +16,14 @@ They generate and decode data using the [LZ4 block format].
 For more compression ratio at the cost of compression speed,
 the High Compression variant called **lz4hc** is available.
 Add files **`lz4hc.c`** and **`lz4hc.h`**.
-This variant also depends on regular `lib/lz4.*` source files.
+This variant also compresses data using the [LZ4 block format],
+and depends on regular `lib/lz4.*` source files.
 
 
 #### Frame support, for interoperability
 
 In order to produce compressed data compatible with `lz4` command line utility,
-it's necessary to encode lz4-compressed blocks using the [official interoperable frame format].
+it's necessary to use the [official interoperable frame format].
 This format is generated and decoded automatically by the **lz4frame** library.
 Its public API is described in `lib/lz4frame.h`.
 In order to work properly, lz4frame needs all other modules present in `/lib`,
@@ -44,7 +45,7 @@ by using build macro `LZ4_PUBLISH_STATIC_FUNCTIONS`.
 
 #### Build macros
 
-The following build macro can be determined at compilation time :
+The following build macro can be selected at compilation time :
 
 - `LZ4_FAST_DEC_LOOP` : this triggers the optimized decompression loop.
   This loops works great on x86/x64 cpus, and is automatically enabled on this platform.
@@ -61,7 +62,7 @@ The following build macro can be determined at compilation time :
 
 - `LZ4_DISABLE_DEPRECATE_WARNINGS` : invoking a deprecated function will make the compiler generate a warning.
   This is meant to invite users to update their source code.
-  Should this be a problem, it's generally to make the compiler ignore these warnings,
+  Should this be a problem, it's generally possible to make the compiler ignore these warnings,
   for example with `-Wno-deprecated-declarations` on `gcc`,
   or `_CRT_SECURE_NO_WARNINGS` for Visual Studio.
   Another method is to define `LZ4_DISABLE_DEPRECATE_WARNINGS`

lib/lz4.h

@@ -51,19 +51,23 @@ extern "C" {
   multiple GB/s per core, typically reaching RAM speed limits on multi-core systems.
 
   The LZ4 compression library provides in-memory compression and decompression functions.
+  It gives full buffer control to user.
   Compression can be done in:
     - a single step (described as Simple Functions)
     - a single step, reusing a context (described in Advanced Functions)
     - unbounded multiple steps (described as Streaming compression)
 
-  lz4.h provides block compression functions. It gives full buffer control to user.
-  Decompressing an lz4-compressed block also requires metadata (such as compressed size).
-  Each application is free to encode such metadata in whichever way it wants.
+  lz4.h generates and decodes LZ4-compressed blocks (doc/lz4_Block_format.md).
+  Decompressing a block requires additional metadata, such as its compressed size.
+  Each application is free to encode and pass such metadata in whichever way it wants.
 
-  An additional format, called LZ4 frame specification (doc/lz4_Frame_format.md),
-  take care of encoding standard metadata alongside LZ4-compressed blocks.
-  Frame format is required for interoperability.
-  It is delivered through a companion API, declared in lz4frame.h.
+  lz4.h only handle blocks, it can not generate Frames.
+
+  Blocks are different from Frames (doc/lz4_Frame_format.md).
+  Frames bundle both blocks and metadata in a specified manner.
+  This are required for compressed data to be self-contained and portable.
+  Frame format is delivered through a companion API, declared in lz4frame.h.
+  Note that the `lz4` CLI can only manage frames.
 */
 
 /*^***************************************************************

lib/lz4frame.h

@@ -32,11 +32,14 @@
    - LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c
 */
 
-/* LZ4F is a stand-alone API to create LZ4-compressed frames
- * conformant with specification v1.6.1.
- * It also offers streaming capabilities.
+/* LZ4F is a stand-alone API able to create and decode LZ4 frames
+ * conformant with specification v1.6.1 in doc/lz4_Frame_format.md .
+ * Generated frames are compatible with `lz4` CLI.
+ *
+ * LZ4F also offers streaming capabilities.
+ *
  * lz4.h is not required when using lz4frame.h,
- * except to get constant such as LZ4_VERSION_NUMBER.
+ * except to extract common constant such as LZ4_VERSION_NUMBER.
  * */
 
 #ifndef LZ4F_H_09782039843
@@ -195,7 +198,7 @@ typedef struct {
 *  Simple compression function
 ***********************************/
 
-LZ4FLIB_API int LZ4F_compressionLevel_max(void);
+LZ4FLIB_API int LZ4F_compressionLevel_max(void);   /* v1.8.0+ */
 
 /*! LZ4F_compressFrameBound() :
  *  Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences.

programs/README.md

@@ -1,18 +1,26 @@
 Command Line Interface for LZ4 library
 ============================================
 
-Command Line Interface (CLI) can be created using the `make` command without any additional parameters.
-There are also multiple targets that create different variations of CLI:
+### Build
+The Command Line Interface (CLI) can be generated
+using the `make` command without any additional parameters.
+
+The `Makefile` script supports all [standard conventions](https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html),
+including standard targets (`all`, `install`, `clean`, etc.)
+and standard variables (`CC`, `CFLAGS`, `CPPFLAGS`, etc.).
+
+For advanced use cases, there are targets to different variations of the CLI:
 - `lz4` : default CLI, with a command line syntax close to gzip
 - `lz4c` : Same as `lz4` with additional support legacy lz4 commands (incompatible with gzip)
 - `lz4c32` : Same as `lz4c`, but forced to compile in 32-bits mode
 
+The CLI generates and decodes [LZ4-compressed frames](../doc/lz4_Frame_format.md).
+
 
 #### Aggregation of parameters
 CLI supports aggregation of parameters i.e. `-b1`, `-e18`, and `-i1` can be joined into `-b1e18i1`.
 
 
-
 #### Benchmark in Command Line Interface
 CLI includes in-memory compression benchmark module for lz4.
 The benchmark is conducted using a given filename.