Update documentation according to recent squashfs-lzma-tools4 integration. Provide...

diff --git a/debian/grml-live.docs b/debian/grml-live.docs
index 66f2ad4..d3c20f0 100644 (file)
--- a/debian/grml-live.docs
+++ b/debian/grml-live.docs
@@ -1,2 +1,4 @@
 docs/grml-live.html
 docs/grml-live.html

+docs/grml-live.epub
+docs/grml-live.pdf

 docs/grml-live-remaster.html
 docs/grml-live-remaster.html

diff --git a/docs/Makefile b/docs/Makefile
index a64b80b..ba8aa4e 100644 (file)
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,6 +1,6 @@
 all: doc
 
 all: doc
 

-doc: doc_man doc_html
+doc: doc_man doc_html doc_epub doc_pdf

 
 doc_html: html-stamp
 
 
 doc_html: html-stamp
 


@@ -21,10 +21,25 @@ man-stamp: grml-live.txt grml-live-remaster.txt
        xsltproc /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl grml-live-db.xml
        touch man-stamp
 
        xsltproc /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl grml-live-db.xml
        touch man-stamp
 

-online: doc_html
+doc_epub: epub-stamp
+
+epub-stamp:
+       a2x --icons -a toc -a toclevels=3 -a docinfo -f epub grml-live.txt
+       touch epub-stamp
+
+doc_pdf: pdf-stamp
+
+pdf-stamp:
+       a2x --icons -a toc -a toclevels=3 -a docinfo -f pdf grml-live.txt
+       touch pdf-stamp
+
+online: doc_html doc_epub doc_pdf

        scp grml-live.html grml:/var/www/grml/grml-live/index.html
        scp grml-live.html grml:/var/www/grml/grml-live/index.html

+       scp grml-live.pdf  grml:/var/www/grml/grml-live/
+       scp grml-live.epub grml:/var/www/grml/grml-live/

 
 clean:
 
 clean:

-       rm -rf grml-live-remaster.html grml-live-remaster.xml grml-live-remaster.8
-       rm -rf grml-live.html grml-live.xml grml-live.8 html-stamp man-stamp
-       rm -rf grml-live-db.html grml-live-db.xml grml-live-db.8 html-stamp man-stamp
+       rm -f grml-live-remaster.html grml-live-remaster.xml grml-live-remaster.8
+       rm -f grml-live.html grml-live.xml grml-live.8 grml-live.epub grml-live.pdf
+       rm -f grml-live-db.html grml-live-db.xml grml-live-db.8
+       rm -f html-stamp man-stamp epub-stamp pdf-stamp

diff --git a/docs/grml-live-docinfo.xml b/docs/grml-live-docinfo.xml
new file mode 100644 (file)
index 0000000..aaee686
--- /dev/null
+++ b/docs/grml-live-docinfo.xml
@@ -0,0 +1,24 @@
+<!--
+Revision file for grml-live
+-->
+
+<authorgroup>
+  <author>
+    <firstname>Michael</firstname>
+    <surname>Prokop</surname>
+    <affiliation>
+      <orgname>Grml Solutions</orgname>
+    </affiliation>
+  </author>
+</authorgroup>
+
+<revhistory>
+
+  <revision>
+    <revnumber>0.1</revnumber>
+    <date>2010-09-01</date>
+    <authorinitials>MP</authorinitials>
+    <revremark>Initial document version with included revision information.</revremark>
+  </revision>
+
+</revhistory>

diff --git a/docs/grml-live.txt b/docs/grml-live.txt
index 51a1554..dc2ca8e 100644 (file)
--- a/docs/grml-live.txt
+++ b/docs/grml-live.txt
@@ -476,13 +476,13 @@ Current state of grml-live with squashfs-tools and kernel
 ---------------------------------------------------------
 
 To make it easier to track problems this section documents current state of
 ---------------------------------------------------------
 
 To make it easier to track problems this section documents current state of

-grml-live playing together with squashfs-tools / squashfs-lzma-tools (for
-building the compressed file) and the kernel version. Documentation of this
-section is up2date by 7rd of september 2009, please report any bugs you
-encounter.
+grml-live playing together with squashfs-tools / squashfs-lzma-tools /
+squashfs-lzma-tools4 (for building the compressed file) and the kernel version.
+Documentation of this section is up2date by 1st of september 2010, please report
+any bugs you encounter.

 
 

-Difference between squashfs-lzma-tools and squashfs-tools
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Difference between squashfs-lzma-tools, squashfs-lzma-tools4 and squashfs-tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 
 Whereas the ZLIB compression is much faster in the build process, the LZMA
 compression provides a smaller resulting ISO. If you're wondering: the official
 
 Whereas the ZLIB compression is much faster in the build process, the LZMA
 compression provides a smaller resulting ISO. If you're wondering: the official


@@ -490,39 +490,94 @@ Grml builds use the LZMA compression.
 
 Squashfs-tools was introduced in Debian and once provided support for LZMA
 compression. Sadly LZMA compression within squashfs-tools became unsupported and
 
 Squashfs-tools was introduced in Debian and once provided support for LZMA
 compression. Sadly LZMA compression within squashfs-tools became unsupported and

-therefore squashfs-lzma-tools had to be introduced by the Grml team. Different
-kernel versions provide different squashfs file formats (version 3.x for kernel
-versions until 2.6.28-grml[64], since kernel 2.6.31-grml[64] it's the 4.x
-format).
+therefore squashfs-lzma-tools[4] had to be introduced and maintained by the Grml
+team. Different kernel versions provide different squashfs file formats. Kernel
+versions until 2.6.28-grml[64] used the 3.x file format but those outdated
+kernels aren't supported by grml-live automatically anymore nowdays (manual
+handling through SQUASHFS_BINARY possible though). Kernel versions
+2.6.31-grml[64] and 2.6.33-grml[64] use openwrt's squashfs lzma file format
+version 4. Kernel versions starting with 2.6.35-grml[64] use the mainline ondisk
+file format version 4.

 
 If you're wondering which package supports what, here's a short overview:
 
 
 If you're wondering which package supports what, here's a short overview:
 

-* squashfs-tools 1:4.0-1: ZLIB as default, no LZMA support/options, file format
-version 4
+* squashfs-lzma-tools4 4.0-x: ZLIB as default, LZMA support via '-comp lzma'
+option (enabled by grml-live by default), file format version 4 (mainline
+version), package maintained and available from Grml, recommended for current
+grml-live builds featuring kernels >=2.6.35-grml[64]
+
+* squashfs-lzma-tools 4.0-2: ZLIB as default, LZMA support via '-lzma' option
+(enabled by grml-live by default), file format version 4 (openwrt style),
+package maintained and available from Grml, recommended for any grml-live builds
+with kernel versions 2.6.31-grml[64] and 2.6.33-grml[64]
+
+* squashfs-tools 1:4.0-x: ZLIB as default, no LZMA support/options, file format
+version 4, package maintained and available from Debian, recommended only for
+ZLIB-only builds of any grml-live builds with kernel versions >=2.6.31-grml[64]
+
+////////////////////////////////////////////////////////////////////////////////
+Outdated, JFTR:

 
 * squashfs-tools 1:3.3-7: ZLIB as default, no LZMA support/options, file format
 version 3
 
 
 * squashfs-tools 1:3.3-7: ZLIB as default, no LZMA support/options, file format
 version 3
 

-* squashfs-tools 1:3.2r2-9exp1: LZMA as default, ZLIB support via -nolzma
+* squashfs-tools 1:3.2r2-9exp1: LZMA as default, ZLIB support via '-nolzma'

 option, file format version 3
 
 option, file format version 3
 

-* squashfs-lzma-tools 4.0-2: ZLIB as default, LZMA support via -lzma option,
-file format version 4
-
-* squashfs-lzma-tools 3.3-1: LZMA as default, ZLIB support via -nolzma option,
+* squashfs-lzma-tools 3.3-1: LZMA as default, ZLIB support via '-nolzma' option,

 file format version 3
 file format version 3

+////////////////////////////////////////////////////////////////////////////////
+
+Now, depending on the kernel version you want to use you need different versions
+of squashfs-tools/squashfs-lzma-tools[4]. Yes, that's a mess (don't ask how much
+this sucks for us developers) - though we're putting lots of effort into our
+toolchain to automatically handle this for you through the grml-live build
+system and provide proper documentation. The situation is supposed to calm down
+with the recent integration of the squashfs file format 4 in the mainline
+kernel. Support for LZMA is pending and as soon as it's available mainline this
+should dramatically simplify the situation for developers as well as users.
+
+[TIP]
+If you want to force usage of a specific mksquashfs binary just set the
+SQUASHFS_BINARY configuration/environment variable. Set SQUASHFS_OPTIONS for
+customizing the options that should be used by the mksquashfs binary during
+build process.
+
+Using squashfs-lzma-tools4 4.0-1 on the build system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+squashfs-lzma-tools4 4.0-1 is available via the Grml repositories. It provides
+the mksquashfs-lzma4 and unsquashfs-lzma4 binaries. The package does NOT
+conflict with neither Debian's squashfs-tools package nor Grml's
+squashfs-lzma-tools package, so you can install all of them at the same time and
+the build system will try to figure out the best matching binary automatically
+for you.
+
+The packages can be downloaded from
+link:http://deb.grml.org/pool/main/s/squashfs-lzma-tools4/[http://deb.grml.org/pool/main/s/squashfs-lzma-tools4/]
+
+It provides support for the new squashfs file format version 4 (as available in
+mainline, so *not* the one being used by squashfs-lzma-tools and kernel
+2.6.33-grml) and therefore requires kernel versions starting with
+2.6.35-grml[64]. It supports LZMA as well as ZLIB compression. Just use the
+defaults for enabling LZMA or use grml-live's '-z' option if you want to use
+ZLIB compression instead.

 
 

-Depending on the kernel version you want to use you need different versions
-squashfs-tools/squashfs-lzma-tools. Yes, that's pretty a mess (don't ask how
-much this sucks for us developers) - though this is supposed to calm down with
-the recent integration of squashfs file format 4 in the mainline kernel. Support
-for LZMA is pending and should dramatically simplify the situation for
-developers as well as users as soon as it's available mainline.
+* Kernel 2.6.31-grml[64]: works with ZLIB compression, fails with LZMA
+* Kernel 2.6.33-grml[64]: works with ZLIB compression, fails with LZMA
+* Kernel 2.6.35-grml[64]: works with ZLIB *and* LZMA compression
+
+[NOTE]
+squashfs-lzma-tools4 is the recommended package for building up2date ISOs with
+grml-live! Please use other squashfs-* packages only if you want to build live
+systems providing kernel versions older than 2.6.35-grml*. Use
+squashfs-lzma-tools4 from Grml if you want to remaster any Grml releases MORE
+RECENT than 2010.04.

 
 Using squashfs-lzma-tools 4.0-2 on the build system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
 Using squashfs-lzma-tools 4.0-2 on the build system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

-squashfs-lzma-tools 4.0-2 is available via the grml repositories. It provides
+squashfs-lzma-tools 4.0-2 is available via the Grml repositories. It provides

 the mksquashfs-lzma and unsquashfs-lzma binaries. The package does NOT conflict
 with Debian's squashfs-tools package (you can install both of them at the same
 time).
 the mksquashfs-lzma and unsquashfs-lzma binaries. The package does NOT conflict
 with Debian's squashfs-tools package (you can install both of them at the same
 time).


@@ -530,29 +585,30 @@ time).
 The packages can be downloaded from
 link:http://deb.grml.org/pool/main/s/squashfs-lzma-tools/[http://deb.grml.org/pool/main/s/squashfs-lzma-tools/]
 
 The packages can be downloaded from
 link:http://deb.grml.org/pool/main/s/squashfs-lzma-tools/[http://deb.grml.org/pool/main/s/squashfs-lzma-tools/]
 

-It provides support for the new squashfs file format version 4 and therefore
-requires kernel versions newer than 2.6.28-grml[64]. It supports LZMA as well as
-ZLIB compression. Just use the defaults for enabling LZMA or use grml-live's
-'-z' option if you want to use ZLIB instead.
+It provides support for the new squashfs file format version 4 (based on openwrt
+patches, this is *not* the mainline file format that's being used by kernel
+2.6.35-grml and squashfs-lzma-tools4!) and therefore requires kernel versions
+newer than 2.6.28-grml[64]. It supports LZMA as well as ZLIB compression. Just
+use the defaults for enabling LZMA or use grml-live's '-z' option if you want to
+use ZLIB instead.

 
 

-* Kernel 2.6.23-grml[64]: does not work
-* Kernel 2.6.26-grml[64]: does not work
-* Kernel 2.6.28-grml[64]: does not work
+* Kernel \<=2.6.28-grml[64]: does not work

 * Kernel 2.6.31-grml[64]: works
 * Kernel 2.6.33-grml[64]: works
 * Kernel 2.6.31-grml[64]: works
 * Kernel 2.6.33-grml[64]: works

+* Kernel 2.6.35-grml[64]: works for ZLIB compression, fails for LZMA

 
 [NOTE]
 
 [NOTE]

-
-Please use squashfs-lzma-tools >=4.0-2 from Grml if you want to remaster any
-grml release being MORE RECENT than 2009.05.
+Please use squashfs-lzma-tools >=4.0-2 from Grml only if you want to remaster
+Grml releases 2009.10 and 2010.04 or live systems with their according kernel
+versions.

 
 Using squashfs-tools 1:4.0-X on the build system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 squashfs-tools >=1:4.0-1 is available in Debian/unstable and Debian/testing. It
 
 Using squashfs-tools 1:4.0-X on the build system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 squashfs-tools >=1:4.0-1 is available in Debian/unstable and Debian/testing. It

-provides the mksquashfs and unsquashfs binaries. The package does NOT
-conflict with the squashfs-lzma-tools 4.0-2 package (you can install both of
-them at the same time).
+provides the mksquashfs and unsquashfs binaries. The package does NOT conflict
+neither with the squashfs-lzma-tools 4.0-2 package nor with the
+squashfs-lzma-tools4 package (so you can install all of them at the same time).

 
 The packages can be downloaded from
 link:ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/[ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/]
 
 The packages can be downloaded from
 link:ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/[ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/]


@@ -560,32 +616,37 @@ link:ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/[ftp://ftp.de.deb
 It provides support for the new squashfs file format version 4 and therefore
 requires kernel versions newer than 2.6.28-grml[64].
 
 It provides support for the new squashfs file format version 4 and therefore
 requires kernel versions newer than 2.6.28-grml[64].
 

-It does NOT support LZMA compression. If you need LZMA support please use
-Grml's squashfs-lzma-tools (see section above) instead.
+It does NOT support LZMA compression (dropped with
+link:http://packages.debian.org/changelogs/pool/main/s/squashfs-tools/current/changelog[version
+1:3.3-4] and not yet re-integrated yet, see
+link:http://bugs.debian.org/594595[#594595]). If you need LZMA support please
+use Grml's squashfs-lzma-tools[4] (see sections above) instead.

 
 

-* Kernel 2.6.23-grml[64]: does not work
-* Kernel 2.6.26-grml[64]: does not work
-* Kernel 2.6.28-grml[64]: does not work
-* Kernel 2.6.31-grml[64]: works
-* Kernel 2.6.33-grml[64]: works
+* Kernels \<=2.6.28-grml[64]: does not work
+* Kernel 2.6.31-grml[64]: works (ZLIB only)
+* Kernel 2.6.33-grml[64]: works (ZLIB only)
+* Kernel 2.6.35-grml[64]: works (ZLIB only)

 
 [NOTE]
 
 [NOTE]

-Please use squashfs-tools >=1:4.0-1 only if you want to remaster grml releases
-MORE RECENT than 2009.05 using the ZLIB compression.
+Please use squashfs-tools >=1:4.0-1 only if you want to remaster Grml releases
+starting with 2009.10 using the ZLIB compression, please use squashfs-lzma-tools
+/ squashfs-lzma-tools4 otherwise instead.
+
+//////////////////////////////////////////////////////////////////////////////////
+Outdated, JFTR:

 
 Using squashfs-lzma-tools 3.3-1 on the build system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
 Using squashfs-lzma-tools 3.3-1 on the build system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

-squashfs-lzma-tools 3.3-1 from the grml repository supports kernel
+squashfs-lzma-tools 3.3-1 from the Grml repository supports kernel

 2.6.26-grml[64] and 2.6.28-grml[64] using both LZMA and ZLIB (-nolzma)
 2.6.26-grml[64] and 2.6.28-grml[64] using both LZMA and ZLIB (-nolzma)

-compression. It's the recommended package for building ISOs with grml-live
-currently!
+compression.

 
 The packages can be downloaded from
 link:http://deb.grml.org/pool/main/s/squashfs-lzma/[http://deb.grml.org/pool/main/s/squashfs-lzma/].
 
 [NOTE]
 
 The packages can be downloaded from
 link:http://deb.grml.org/pool/main/s/squashfs-lzma/[http://deb.grml.org/pool/main/s/squashfs-lzma/].
 
 [NOTE]

-Please use squashfs-lzma-tools 3.3-1 if you want to remaster grml release
+Please use squashfs-lzma-tools 3.3-1 only if you want to remaster Grml releases

 2008.11 or 2009.05.
 
 Using squashfs-tools 1:3.3-7 on the build system
 2008.11 or 2009.05.
 
 Using squashfs-tools 1:3.3-7 on the build system


@@ -634,6 +695,7 @@ Using with LZMA compression:
   to Debian package squashfs-lzma-tools 3.3-1 (see section above).
 * Kernel 2.6.28-grml: does NOT work, please use ZLIB mode instead or switch
   to Debian package squashfs-lzma-tools 3.3-1 (see section above).
   to Debian package squashfs-lzma-tools 3.3-1 (see section above).
 * Kernel 2.6.28-grml: does NOT work, please use ZLIB mode instead or switch
   to Debian package squashfs-lzma-tools 3.3-1 (see section above).

+//////////////////////////////////////////////////////////////////////////////////

 
 [[faq]]
 FAQ
 
 [[faq]]
 FAQ


@@ -643,7 +705,7 @@ FAQ
 How do I deploy grml-live on a plain Debian installation?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 How do I deploy grml-live on a plain Debian installation?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

-The easiest way to get a running grml-live setup is to install grml or
+The easiest way to get a running grml-live setup is to install Grml or

 grml-medium using grml2hd (for example inside KVM, Virtualbox, VMware,... if you
 don't want to run it on a physical system). Of course using grml-live on a
 plain, original Debian installation is supported as well. So there we go.
 grml-medium using grml2hd (for example inside KVM, Virtualbox, VMware,... if you
 don't want to run it on a physical system). Of course using grml-live on a
 plain, original Debian installation is supported as well. So there we go.


@@ -680,11 +742,11 @@ Instructions
   Pin: origin deb.grml.org
   Pin-Priority: 1
 
   Pin: origin deb.grml.org
   Pin-Priority: 1
 

-  Package: squashfs-tools
+  Package: squashfs-lzma-tools

   Pin: origin deb.grml.org
   Pin-Priority: 996
 
   Pin: origin deb.grml.org
   Pin-Priority: 996
 

-  Package: squashfs-lzma-tools
+  Package: squashfs-lzma-tools4

   Pin: origin deb.grml.org
   Pin-Priority: 996
   EOF
   Pin: origin deb.grml.org
   Pin-Priority: 996
   EOF


@@ -701,13 +763,17 @@ Instructions
 
   # install relevant tools
   # please check out http://grml.org/grml-live/#current_state when encountering problems!
 
   # install relevant tools
   # please check out http://grml.org/grml-live/#current_state when encountering problems!

-  apt-get -o APT::Install-Recommends=false install grml-live squashfs-tools squashfs-lzma-tools
+  apt-get -o APT::Install-Recommends=false install grml-live squashfs-lzma-tools squashfs-lzma-tools4

 
   # adjust grml-live configuration for our needs:
   cat > /etc/grml/grml-live.local << EOF
 
   # adjust grml-live configuration for our needs:
   cat > /etc/grml/grml-live.local << EOF

-  # consider using LZMA only for space reasons (resulting in longer
-  # build time but smaller ISO):
-  SQUASHFS_OPTIONS="-nolzma"
+  ## want a faster build process and don't need smaller ISOs?
+  ## if so use zlib compression, for kernels >=2.6.35-grml* and squashfs-lzma-tools4:
+  # SQUASHFS_OPTIONS="-comp gzip -b 256k"
+  ## ... or for kernels <=2.6.33-grml* and squashfs-lzma-tools:
+  # SQUASHFS_OPTIONS="-nolzma -b 256k"
+  ## want to use a specific squashfs binary?
+  # SQUASHFS_BINARY='/usr/bin/mksquashfs'

   # install local files into the chroot
   CHROOT_INSTALL="/etc/grml/fai/chroot_install"
   ## adjust if necessary (defaults to /grml/grml-live):
   # install local files into the chroot
   CHROOT_INSTALL="/etc/grml/fai/chroot_install"
   ## adjust if necessary (defaults to /grml/grml-live):


@@ -1012,6 +1078,17 @@ Bugs
 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 link:http://grml.org/contact/[to the grml-team]!
 
 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 link:http://grml.org/contact/[to the grml-team]!
 

+[[documentation]]
+Documentation
+-------------
+
+The most recent grml-live documentation is available online at
+http://grml.org/grml-live/ and for offline reading also available
+in different formats:
+
+* http://grml.org/grml-live/grml-live.epub
+* http://grml.org/grml-live/grml-live.pdf
+

 [[authors]]
 Authors
 -------
 [[authors]]
 Authors
 -------