[parted-devel] [PATCH] doc: Improve section 2.1 and remove reference to missing GNU Storage Guide.

[Gareth Randall]

Hi,

I'd like to fix a long-standing bug in the parted info documentation in 
which a reference is made to a non-existant document. I've also taken the 
opportunity to write a longer introduction and make it more upbeat.

The bug concerns the line:
"This manual used to introduce the reader to these systems and their 
working. This content has moved to the GNU Storage Guide."

This text dates from about 10 years ago and the GNU Storage Guide still 
doesn't appear to be available. A web search for "GNU Storage Guide" will 
reveal several bugs in different GNU/Linux distributions relating to this, 
such as this one:
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=600563

Here is my proposed patch, also posted at:
http://paste.debian.net/330368/
in case there are line break issues in the text below.

Hope you like it!

Yours,

Gareth Randall


diff --git a/doc/parted.texi b/doc/parted.texi
index cb12e8d..bdd692d 100644
--- a/doc/parted.texi
+++ b/doc/parted.texi
@@ -291,12 +291,39 @@ or you want to modify a root or boot partition, use 
GParted Live:
  @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.
+Partitioning your disk is interesting because it allows you to boot from
+multiple different operating systems and use multiple filesystems.

-This manual used to introduce the reader to these systems and their
-working.  This content has moved to the GNU Storage Guide.
+A storage device presents itself as a long sequence of bytes, numbered
+starting from zero and increasing until the maximum capacity of the
+device is reached. Bytes are normally read and written a sector at a
+time, rather than individually, and each sector is typically 512 bytes
+or 4096 bytes depending on the device.
+
+ at example
++------------------------------------------------------------+
+|            storage device with no partitions               |
++------------------------------------------------------------+
+0 start                                                    end
+ at end example
+
+In order to store multiple filesystems, a storage device can be divided
+up in to multiple partitions. Each partition can be thought of as a file
+which contains a real filesystem inside of it. To show where these
+partitions are on the device a small table is written at the start,
+shown as PT in the diagram below. This table is called a partition
+table, or disklabel, and also stores information about what sort of
+filesystem each partition contains and whether it is bootable.
+
+ at example
++--+---------------+----------------+------------------------+
+|PT|  Partition 1  |  Partition 2   |  Partition 3           |
++--+---------------+----------------+------------------------+
+0 start                                                    end
+ at end example
+
+There are many good online resources that describe partitioning in more
+detail.

  @node Running Parted
  @section Using GNU Parted