Subject: Rescuing the GNU Storage Guide?

From: [email-masked] (Ludovic Courtès)
Date: Sat, 04 Jun 2016 23:00:08 +0200

Hello!

The Parted manual mentions a “GNU Storage Guide” that the intertubes
haven’t even seen, it seems.

I found that r600 by Leslie P. Polzer in the original svn repo was the
one that introduced the references to this guide (see patch below, or
‘svn diff -c600 svn://svn.debian.org/svn/parted/upstream/trunk’).

I was wondering if Leslie or someone else would have a copy of this
guide?

Alternately, what about reinstating the relevant bits of r600?

The reason I’m asking is that, in the context of GuixSD, it would be
great to be able to refer to the Parted manual or to the Storage Guide,
rather than writing yet another half-baked intro to partitioning with
Parted that is bound to become outdated.

Thoughts?

Thanks in advance.  :-)
Ludo’.

Index: parted.texi
===================================================================
--- parted.texi	(revision 599)
+++ parted.texi	(revision 600)
@@ -1,3 +1,4 @@
+@c TODO: "version" command.  Read through and correct.
 \input texinfo    @c -*-texinfo-*-
 @c %**start of header
 @setfilename parted.info
@@ -72,7 +73,7 @@
 
 This document applies to @value{VERSION} of GNU Parted.  The original
 version was by Andrew Clausen, and was translated into this format
-by Richard M. Kreuter.  It is currently maintained by Andrew Clausen.
+by Richard M. Kreuter.  It was heavily edited by Leslie P. Polzer in 2006. 
 @end ifnottex
 
 @shortcontents
@@ -123,42 +124,32 @@
 ``disk imaging'' --- replicating an installation on another computer.
 
 This documentation is written with the assumption that the reader
-has some understanding of partitions and file systems.  If you want to
-learn more about these, the Partition mini-HOWTO is recommended reading.
-It is probably included with your distribution, or it is available at
+has some understanding of partitioning and file systems.  If you want to
+learn more about these, the upcoming GNU Storage Guide is recommended
+reading.
 
-@c FIXME: standards: howto labelled non-free by LDP
-@uref{http://www.linuxdoc.org/HOWTO/mini/Partition/index.html}
-
 GNU Parted was designed to minimize the chance of data loss.  For
 example, it was designed to avoid data loss during interruptions (like
-power failure) and performs many safety checks.  However there could
-be bugs in Parted, so you should back up your important files before
+power failure) and performs many safety checks.  However, there could
+be bugs in GNU Parted, so you should back up your important files before
 running Parted.
+Also note that reiserfs support relies on libreiserfs, which does not
+fulfil the aforementioned requirement.  The same holds for any external
+tools like @kbd{ntfsresize}.
 
-The GNU Parted homepage is @uref{http://www.gnu.org/software/parted}.  It can
-be downloaded from @uref{ftp://ftp.gnu.org/gnu/parted}.
+The GNU Parted homepage is @uref{http://www.gnu.org/software/parted}.  The
+library and frontend themselves can be downloaded from
+@uref{ftp://ftp.gnu.org/gnu/parted}.
+You can also find a listing of mailing lists, notes for contributing and
+more useful information on the web site.
 
-The Parted mailing list is @email{parted@@gnu.org}.  To subscribe, write
-to @email{bug-parted-request@@gnu.org} with @samp{subscribe} as the
-Subject of the message.  Subscription information and archives are
-available at:
-
-@uref{http://mail.gnu.org/mailman/listinfo/bug-parted}
-
 Please send bug reports to @email{bug-parted@@gnu.org}.  When sending bug
-reports, please include the version of GNU Parted.  If the bug is
-related to partition tables, then please include the output from these
-commands (for disk @file{/dev/hda}):
+reports, please include the version of GNU Parted.
+Please include the output from these commands (for disk @file{/dev/hda}):
 
 @example
 @group
 # @kbd{parted /dev/hda print unit s print unit chs print}
-# @kbd{fdisk /dev/hda -l -u}
-# @kbd{fdisk /dev/hda}
-Command (m for help): @kbd{p}
-Command (m for help): @kbd{x}
-Extended command (m for help): @kbd{p}
 @end group
 @end example
 
@@ -281,7 +272,7 @@
 disables dynamic loading of some libraries (only libreiserfs for now,
 although we hope to expand this).  Dynamic loading is useful because it
 allows you to reuse libparted shared libraries even when you don't know
-when if some libraries will be available.  It has a small overhead (mainly
+if some libraries will be available.  It has a small overhead (mainly
 linking with libdl), so it may be useful to disable it on bootdisks if
 you don't need the flexibility.
 
@@ -301,14 +292,8 @@
 @item --disable-Werror
 ignore warning messages in compilation
 
-@item --enable-all-static		
-builds the Parted binary as a fully static binary.  This is convienient
-for boot disks, because you don't need to install any libraries on the
-boot disk (although, other programs may require them@dots{})  Note: you will
-also want to run strip(1).
-
 @item --enable-discover-only
-support only reading/probing
+support only reading/probing (reduces size considerably)
 
 @item --enable-mtrace
 enable malloc() debugging
@@ -319,70 +304,39 @@
 @end table
 
 @node Parted boot disks
-@section Using a Parted Boot Disk
+@section Using a Parted stand-alone disk
 @cindex boot disk
-@cindex boot floppy
 @cindex unsupported platforms
 @cindex resizing root device
 
-If you want run Parted on a machine without GNU/Linux installed, or you
+If you want to run GNU Parted on a machine without GNU/Linux installed, or you
 want to resize a root or boot partition, you will need to use a boot disk.
 
+Special boot disk images for GNU Parted used to be available, but with the
+emergence of a plethora of rescue disks and Live CDs that all
+include GNU Parted this is no longer necessary.
+However, please note that these disks often ship with out-of-date
+versions of Parted.  To compensate for this a static binary
+of the latest GNU Parted version is available, which you can use thus:
 
-Boot disk images (x86-only) are available from:
+@c There should be instructions for CD and USB here.
 
-@uref{ftp://ftp.gnu.org/gnu/parted/bootdisk}
-
-You need two disks.  The boot disk contains Linux... it doesn't
-vary between Parted versions.  The root disk contains Parted (and
-other stuff), and varies between Parted releases.
-
-So, here are the steps:
-
+@subsection Creating the Parted disk
 @enumerate
-@item Download the boot disk (i.e. @kbd{partboot.img}) and a root disk
-(eg: @kbd{partroot-@value{VERSION}.img}).
+@item Boot your system 
 
-@item Create the boot disk, by copying the image to a floppy.  In GNU/Linux,
-you can type:
+@item Download @file{parted-static-VERSION.tgz} from @uref{ftp://ftp.gnu.org/parted/static}
+@item Unpack the tarball, resulting in a file called ``parted.static".
 
-	@example
-	# @kbd{dd if=partboot.img of=/dev/fd0 bs=1440k}
-	@end example
+@item Insert a floppy.
 
-In Windows, you can use @kbd{rawrite.exe}.  It is available in many
-places, including @uref{ftp://ftp.tux.org/pub/dos/rawrite/rawrite.exe}.
+@item Do a low-level format on it (on GNU/Linux this can be achieved with
+      the tool ``fdformat" from the ``util-linux" package.
+      This is basically a sanity check because floppy disks often 
+      contain bad blocks.
 
-@item Create the root disk, using a similar procedure.  e.g.:
+@item Create a file system. Example:
 
-	@example
-	# @kbd{dd if=partroot-@value{VERSION}.img of=/dev/fd0 bs=1440k}
-	@end example
-
-@item Boot off the boot disk.  Do this by inserting the boot disk, and
-rebooting your computer.  You might need to tell your BIOS (the startup
-program when your computer turns on) to allow booting off a floppy disk.
-
-@item When asked, insert the root floppy disk.
-@end enumerate
-
-The boot disk contains many drivers for different hard disk controllers,
-but yours might not be supported.  So, if you're unlucky, you will need
-to make your own boot disk.  You can copy the parted binary from the parted
-bootdisk onto another disk, or try other boot disks, or make your own.
-You may find Mkpart useful (not to be confused with Parted's mkpart command),
-which is a shell script to make custom parted boot disks.  It is available at:
-
-@uref{ftp://ftp.tux.org/pub/people/kent-robotti/mkpart}
-
-To copy parted from the boot disk onto another disk:
-
-@enumerate
-@item Boot from the Parted boot disk.
-
-@item Insert another ext2-formatted floppy disk.  If it isn't formated,
-you can create a file system with, for example:
-
 @example
 $ @kbd{parted /dev/fd0 mklabel loop mkpartfs primary ext2 0 1.4}
 @end example
@@ -393,10 +347,10 @@
 $ @kbd{mount -t ext2 /dev/fd0 /mnt/floppy}
 @end example
 
-@item Copy @file{/usr/bin/parted} to the floppy, e.g.,
+@item Copy @file{parted.static} to the floppy, e.g.,
 
 @example
-$ @kbd{cp /usr/bin/parted /mnt/floppy}
+$ @kbd{cp parted.static /mnt/floppy}
 @end example
 
 @item Unmount the floppy, e.g.,
@@ -404,10 +358,11 @@
 @example
 $ @kbd{umount /mnt/floppy}
 @end example
+@end enumerate
 
-@item Find a boot disk that @emph{does} support your hard disk.
-(Hint: try looking for rescue disks from various distributions on big
-mirror sites)
+@subsection Using the Parted disk
+@enumerate
+@item Choose a rescue disk that suits you. 
 
 @item Boot off your rescue disk.  Mount the disk you copied Parted onto.
 
@@ -415,7 +370,7 @@
 
 @example
 # @kbd{cd /mnt/floppy}
-# @kbd{./parted}
+# @kbd{./parted-static}
 @end example
 @end enumerate
 
@@ -432,49 +387,16 @@
 @end menu
 
 @node Partitioning
-@section Partitioning Concepts
+@section Introduction to Partitioning 
 @cindex partitioning overview
 
 Unfortunately, partitioning your disk is rather complicated.  This is
 because there are interactions between many different systems that need
-to be taken into consideration:
+to be taken into consideration.
 
-@itemize @bullet
-@item
-The firmware -- the program that is programmed into a ROM chip inside
-your computer, that does memory checks, etc.  You cannot (easily)
-change programs in this system.  Examples of firmware programs: AmiBIOS,
-Award, Phoenix, OpenFirmware.  You will only have one of these programs.
+This manual used to introduce the reader to these systems and their
+working.  This content has moved to the GNU Storage Guide.
 
-@item
-The boot loader -- the program that allows you to select which operating
-system you want to use, and loads that operating system.  Examples:
-LILO, GRUB, Yaboot, Quik.  You may have more than one boot loader
-installed, especially if you have more than one type of operating system
-installed.
-
-@item
-The operating system (at the moment, this must be GNU/Linux or GNU/Hurd)
-that runs Parted, and the other operating systems that you use.
-
-@item
-The file system types -- the way the data stored on partitions.  Examples
-of these are: ext2, fat32, hfs, reiserfs.  You will often have
-partitions of different file system types.
-@end itemize
-
-Parted supports many combinations of firmware, boot loader, operating
-system, and file systems, and will support more in the future.  To
-further understand the roles of each, please see @ref{Firmware},
-@ref{Boot Loaders}, @ref{Operating Systems}, and @ref{File Systems}.
-
-This chapter describes how to use Parted, which is mostly independent
-of system details.  You should read this chapter and then the chapters
-on firmware, boot loaders, operating systems, and file systems that
-are relevant to your installation.  For example, if you are only using
-LILO as your boot loader, then you should read the introduction and
-@ref{LILO, the section on LILO}.
-
 @node Running Parted
 @section Using GNU Parted
 @cindex modes of use
@@ -512,6 +434,7 @@
 type ``p'' instead of ``print'', and ``resi'' instead of ``resize''.
 Commands can be typed either in English, or your native language (if
 your language has been translated).  This may create ambiguities.
+Commands are case-insensitive.
 
 Numbers indicating partition locations can be whole numbers or decimals.
 The suffix selects the unit, which may be one of those described in
@@ -540,7 +463,9 @@
 significantly different from the size requested, Parted will warn you.
 Since many partitioning systems have complicated constraints, Parted will
 usually do something slightly different to what you asked.  (For example,
-create a partitiong starting at 10.352Mb, not 10.4Mb)
+create a partition starting at 10.352Mb, not 10.4Mb)
+If the calculated values differ too much, Parted will ask you for
+confirmation.
 
 @node Invoking Parted
 @section Command Line Options
@@ -548,7 +473,7 @@
 @cindex commands, overview
 @cindex invocation options
 
-When invoked from the command line, parted supports the following syntax:
+When invoked from the command line, Parted supports the following syntax:
 
 @example
 # @kbd{parted [@var{option}] @var{device} [@var{command} [@var{argument}]]}
@@ -555,7 +480,7 @@
 @end example
 
 Available options and commands follow.  For detailed explanations of the
-use of parted commands, see @ref{Command explanations}. Options begin
+use of Parted commands, see @ref{Command explanations}. Options begin
 with a hyphen, commands do not:
 
 Options:
@@ -604,6 +529,7 @@
 * select::
 * set::
 * unit::
+* version::
 @end menu
 
 @node check
@@ -692,13 +618,10 @@
 will have no partitions.  This command (normally) won't technically
 destroy your data, but it will make it basically unusable,
 and you will need to use the rescue command (@pxref{Related Software and
-Info}) to recover any partitions.  Gpart only works for msdos disk
-labels (AFAIK), but is much better than parted at recovering partitions.
+Info}) to recover any partitions.
 Parted works on all partition tables.  @footnote{Everyone seems to
 have a different word for ``disk label'' --- these are all the same
-thing: partition table, partition map.  Also, the Master Boot Record on
-x86 machines is stored in the same sector as Partition Tables (you don't
-need to know this to use Parted).}
+thing: partition table, partition map.}
 
 @var{label-type} must be one of these supported disk labels:
 @itemize @bullet
@@ -717,7 +640,8 @@
 (parted) @kbd{mklabel msdos}
 @end example
 
-Create an msdos style disklabel.
+Create an MS-DOS disk label.  This is still the most common disk label for
+PCs.
 @end deffn
 
 @node mkfs
@@ -852,7 +776,7 @@
 Example:
 
 @example
-(parted) move 2 150 500
+(parted) move 2 150M 500M
 @end example
 
 Move the partition numbered 2 so that it begins 150 megabytes from the start of
@@ -928,7 +852,8 @@
 It is only after Parted exits that the Linux kernel knows about the changes
 Parted has made to the disks.  However, the changes caused by typing your
 commands will @emph{probably} be made to the disk immediately after typing a
-command.  However, Linux's cache, and the disk's hardware cache may delay this.
+command.  However, the operating system's cache and the disk's hardware cache
+may delay this.
 @end deffn
 
 @node rescue
@@ -1016,7 +941,7 @@
 Example:
 
 @example
-(parted) @kbd{resize 3 200 850}
+(parted) @kbd{resize 3 200M 850M}
 @end example
 
 Resize partition 3, so that it begins 200 megabytes and ends 850
@@ -1094,7 +1019,7 @@
 enforced by Parted).
 
 @item lba
-(MS-DOS) - this flag can be enabled, to tell MS DOS, MS Windows 9x and
+(MS-DOS) - this flag can be enabled to tell MS DOS, MS Windows 9x and
 MS Windows ME based operating systems to use Linear (LBA) mode.
 
 @item root
@@ -1196,9 +1121,9 @@
 wrote that satisfies constraints from both the operation, the
 filesystem being worked on, the disk label, other partitions and so
 on.  Use the sector unit ``s'' to specify exact locations (if they
-do not satisfy every constraints, Parted will refuse to do the
-operation).  Note that negative numbers count back from the end of
-the disk, with ``-1s'' indicating the end of the disk.  
+do not satisfy all onstraints, Parted will ask you for the nearest 
+solution).  Note that negative numbers count back from the end of
+the disk, with ``-1s'' pointing to the end of the disk.  
 
 Example:
 
@@ -2248,8 +2173,8 @@
 @noindent NOTES:
 @enumerate
 @c (1)
-@item The start of the partition must stay fixed for ext2, ext3, reiserfs, hfs,
-hfs+ and hfsx.
+@item The start of the partition must stay fixed for ext2, ext3, Reiser FS,
+HFS, HFS+ and HFSx.
 @c (2)
 @item The partition you copy to must be bigger (or exactly the same size)
 as the partition you copy from.
@@ -2259,11 +2184,11 @@
 gracefully fail, leaving the file system intact, if there are any errors.
 @c (4)
 @item The size of the new partition, after resizing or copying, is
-restricted by the cluster size for fat (mainly affects FAT16).  This is
-worse than you think, because you don't get to choose your cluster size
-(it's a bug in Windows, but you want compatibility, right?).
+restricted by the cluster size for the FAT file system (mainly affects FAT16).
+This is worse than you think, because you don't get to choose your cluster
+size. It's a bug in Microsoft Windows, but you want compatibility, right?
 
-So, in practise, you can always shrink your partition (because Parted
+So, in practice, you can always shrink your partition (because Parted
 can shrink the cluster size), but you may not be able to grow the
 partition to the size you want.  If you don't have any problems with
 using FAT32, you will always be able to grow the partition to the size
@@ -2272,10 +2197,10 @@
 Summary: you can always shrink your partition.  If you can't use FAT32
 for some reason, you may not be able to grow your partition.
 @c (5)
-@item Parted can only shrink hfs, hfs+ and hfsx file systems.
+@item Parted can only shrink HFS, HFS+ and HFSx file systems.
 @c (6)
-@item Reiserfs support is enabled if you install libreiserfs, which is available
-at @uref{http://www.namesys.com/pub/libreiserfs}.
+@item Reiser FS support is enabled if you install libreiserfs,
+which is available at @uref{http://www.namesys.com/pub/libreiserfs}.
 @end enumerate
 
 @node Ext2
@@ -2288,16 +2213,17 @@
 are other ways of copying partitions, however:
 
 @itemize @bullet
-@item Use Parted's mkfs command (or mkfs.ext2), and then run at the shell:
+@item Use Parted's mkfs command (or mkfs.ext2) on the target partiton and copy
+all the files. Example for copying: 
 
-FIXME!!! this doesn't work quite right - but it should be OK for most
-people@dots{}
-
 @example
-# @kbd{mount -t ext2 /dev/hda2 /mnt/dst}
-# @kbd{find /mnt/src -depth | cpio -pm /mnt/dst}
+# @kbd{(cd /mnt/src; tar -c .) | (cd /mnt/dst; tar -x )}
 @end example
 
+This was tested with GNU tar and should work with most other, if not all,
+versions of the tar program. Mount the appropriate devices on @file{/mnt/src}
+and @file{/mnt/dst}. Also note the @kbd{--sparse} option of GNU tar.
+
 @item If the duplicate partition is going to bigger than the original,
 this can also be done: first, create the new ext2 partition.  Then: