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

[Brian C. Lane]

On Tue, Nov 10, 2015 at 03:59:21PM +0000, Gareth Randall wrote:
> 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.

I don't think interesting is the right word to use, this should be an
objective overview of partitioning. Something like:

Partitioning is the process of dividing a storage device into local
sections, called partitions, which help organize multiple filesystems
and their associated operating systems.


> 
> -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

I'd drop the word 'long' here.

> +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.

There are more sector sizes than 512 and 4096, better not to try to make
an exhaustive list.

> +
> + 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

They aren't files and shouldn't be called files. I'd use words like
sections, or areas.


> +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.

The partition table doesn't store information about the filesystem, it
stores information about the start/end (or length) of the partition and
a partition type, along with some flags.

> +
> + 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.

If you are going to mention resources you should include links.


Thanks for helping improve the docs,

Brian

-- 
Brian C. Lane | Anaconda Team | IRC: bcl #anaconda | Port Orchard, WA (PST8PDT)