Source: installation-guide
Version: 20150528
Severity: minor
Tags: d-i patch

Following up #794936, here's my second bugreport for a big clear
individual issue before I start on a general proofreading sweep.

Section 6.3.3.4 (aka the file "using-d-i/modules/mdcfg.xml") describes
how to set up RAID arrays in D-I.  But instead of just calling them
that it insists on using jargon which users are unlikely to be
familiar with and which isn't even technically correct.

I'm including general proofreading fixes in this patch as well as the
headline problem, because it's all in one .xml file - if I tried to
separate things out into one patch fixing the grammar issues and one
standardising the punctuation and so on then they'd all just trample
on one another's toes.

Here's an annotated copy of the patch (and yes, this time I've
double-checked the attached version is the same file!):

> Index: mdcfg.xml
> ===================================================================
> --- mdcfg.xml (revision 70030)
> +++ mdcfg.xml (working copy)
> @@ -2,32 +2,32 @@
>  <!-- $Id$ -->
>  
>     <sect3 id="mdcfg">
> -   <title>Configuring Multidisk Devices (Software RAID)</title>
> +   <title>Configuring Software RAID</title>

Because absolutely nobody calls them Multidisk Devices, and MD has
never stood for that anyway.  (There are rumours it was once "Mirror
Disk", but it has officially always been "Multiple Device".)

I was going to add that if you Google "Multidisk Devices", it just
goes "did you mean...?" - but in fact if I insist, it will do that
search, and finds Frans Pop filing bug #387696 about this in 2006.
That was allegedly fixed, but here it still is.

If the mdcfg module supported RAID plus some other things then it
might be more pedantically accurate to talk here in terms of using
Multiple Device storage in general.  But it doesn't.  It's talking
about RAID, which was already widely known as RAID before Linux
existed.  So call it RAID!

>  <para>
>  
> -If you have more than one harddrive<footnote><para>
> +If you have more than one hard drive<footnote><para>

I'm letting "mountpoints" and "filesystems" get away with being
written as one word, but "harddrive" is a step too far.

(Meanwhile, the day may be approaching when we'll need to say "hard
disk, flash drive, or similar main non-volatile storage system".  Or
maybe we'll be able to use plain "drive" as a cover-term...)
  
> -To be honest, you can construct an MD device even from partitions
> -residing on single physical drive, but that won't give any benefits.
> +To be strictly accurate, you can construct a RAID array even from partitions
> +residing on a single physical drive, but that won't give any benefits.

Leaving out this detail wouldn't have been dishonest.

Our default name for RAID arrays should be "RAID arrays".  Referring
to RAID in terms of the Linux kernel driver used for it makes even
less sense when you consider that this installer is also intended foe
use on systems where &arch-kernel; != Linux.

Missing indefinite article.

> -</para></footnote> in your computer, you can use
> -<command>mdcfg</command> to set up your drives for increased
> -performance and/or better reliability of your data. The result is
> -called <firstterm>Multidisk Device</firstterm> (or after its most
> -famous variant <firstterm>software RAID</firstterm>).
> +</para></footnote> in your computer, you can set up your drives for
> +improved performance and/or reliability by using software RAID.
> +The &d-i; module used for this is <literal>mdcfg</literal>, named
> +after the Linux <literal>md</literal> (<quote>Multiple Device</quote>)
> +driver.

Users of D-I are never told that they're using mdcfg, so it's fairly
pointless to act as if they'd recognise the name; instead, _introduce_
it here.  Tagging "mdcfg" as a <command> just spoils any plan we might
have for making the <command> tag pull its weight (they might for
instance link to manpages.debian.org - but D-I modules don't have man
pages).  I'm falling back on marking "mdcfg" as a basic <literal> here
(which should result in the same markup as for a <command>), but it's
not clear it's entitled even to this much, since it isn't a word that
users ever need to be treat as a verbatim string...

"Reliability of your data" is subtly wrong.  If my data is the
collected prophetic ramblings of Nostradamus, RAID isn't going to make
it any more reliable!  Just say "improved [...] reliability".

Then the end of the second sentence is the main point of this bug
report.  The result of using mdcfg is _not_ called "Multidisk Device".
It isn't even called "MD".  It's called RAID.  Introduce it as RAID,
then note in case anybody cares that it's implemented in Linux under
the name "md".  (This might even go in a footnote, but we've just had
one of those.)
  
>  </para><para>
>  
> -MD is basically a bunch of partitions located on different disks and
> -combined together to form a <emphasis>logical</emphasis> device. This
> -device can then be used like an ordinary partition (i.e. in
> -<command>partman</command> you can format it, assign a mountpoint,
> -etc.).
> +A RAID array is basically a bunch of partitions located on different
> +disks and combined together to form a <emphasis>logical</emphasis>
> +device. You can then proceed with the install using it just like an
> +ordinary partition &mdash; you can format it, assign a mountpoint, and
> +so on.

Don't call it MD, call it RAID, and don't talk as if users had some
way of knowing when they're "in partman".  (Since partman is the thing
the install immediately continues with when you exit mdcfg, it hardly
needs to be named anyway.)

Plus some general tweaks to the English - use "you" consistently
rather than a passive construction, and avoid overdosing on latinisms
(e.g. i.e., etc.).

>  
>  </para><para>
>  
> -What benefits this brings depends on the type of MD device you are
> -creating. Currently supported are:
> +What benefits this brings will depend on the type of RAID setup you
> +create. Currently supported are:

Don't call it MD, call it RAID.  I've also reorganised the use of
tenses, not because the original version was ungrammatical,
particularly, but just because "this brings depends" is slightly
jarring.
  
>  <variablelist>
>  <varlistentry>
> @@ -53,14 +53,14 @@
>  <term>RAID1</term><listitem><para>
>  
>  Is suitable for setups where reliability is the first concern.  It
> -consists of several (usually two) equally-sized partitions where every
> +consists of several (usually two) equal-sized partitions where every

Either of these is idiomatic spoken English, but there are some
styleguides that object to the adverb version.

>  partition contains exactly the same data. This essentially means three
>  things.  First, if one of your disks fails, you still have the data
>  mirrored on the remaining disks. Second, you can use only a fraction
>  of the available capacity (more precisely, it is the size of the
> -smallest partition in the RAID). Third, file-reads are load-balanced among
> -the disks, which can improve performance on a server, such as a file
> -server, that tends to be loaded with more disk reads than writes.
> +smallest partition in the array). Third, file-reads are load-balanced among
> +the disks, which can improve performance on systems such as file
> +servers that tend to be loaded with more disk reads than writes.

Just for once I've taken the word "RAID" out here, because although
the acronym expands to "Redundant Array of In(...mumble...) Disks", it
doesn't usually mean an array; "RAID" as a noun generally refers to
the technology in general.

The repetition of "servers" and use of commas in the last sentence
strike me as awkward.  I would also naturally use "between", not
"among", but I'm leaving that since it's often an en-GB/en-US thing.
  
>  </para><para>
>  
> @@ -73,14 +73,14 @@
>  
>  <term>RAID5</term><listitem><para>
>  
> -Is a good compromise between speed, reliability and data redundancy.
> +Is a good compromise between speed, reliability, and data redundancy.

"Harvard comma", since it's used elsewhere in this page.

>  RAID5 splits all incoming data into stripes and distributes them
>  equally on all but one disk (similar to RAID0). Unlike RAID0, RAID5
>  also computes <firstterm>parity</firstterm> information, which gets
>  written on the remaining disk. The parity disk is not static (that
> -would be called RAID4), but is changing periodically, so the parity
> +would be called RAID4), but changes periodically, so the parity

Wrong aspectual construction.

>  information is distributed equally on all disks.  When one of the
> -disks fails, the missing part of information can be computed from
> +disks fails, the missing information can be computed from the

I could have added a definite article instead, but the easier
solution is to eliminate the need for one.

>  remaining data and its parity. RAID5 must consist of at least three
>  active partitions. Optionally you can have a spare disk in the array
>  which will take the place of the failed disk in the case of failure.
> @@ -88,9 +88,9 @@
>  </para><para>
>  
>  As you can see, RAID5 has a similar degree of reliability to RAID1
> -while achieving less redundancy. On the other hand, it might be a bit
> -slower on write operations than RAID0 due to computation of parity
> -information.
> +with somewhat lower redundancy. On the other hand, it might be a bit
> +slower on write operations than RAID0 due to the overhead of parity
> +computation.

"Achieving less redundancy" is ambiguous, especially with something
which can be either good or bad, like redundancy.  The use of "On
the other hand" to separate two things that are both disadvantages
makes it even more confusing, so I've tweaked it for added clarity.
  
>  </para></listitem>
>  </varlistentry>
> @@ -114,14 +114,16 @@
>  RAID10 combines striping (as in RAID0) and mirroring (as in RAID1).
>  It creates <replaceable>n</replaceable> copies of incoming data and
>  distributes them across the partitions so that none of the copies of
> -the same data are on the same device.
> -The default value of <replaceable>n</replaceable> is 2, but it can be
> +a given piece of data are on the same device.

"Copies of the same data as what?"

> +The default value of <replaceable>n</replaceable> is two, but it can be

Just following the usual styleguide rule that low numbers are
written out as words (though using figures in a table is fine, and
you might argue that this is in effect quoting from the table...)

>  set to something else in expert mode. The number of partitions used
>  must be at least <replaceable>n</replaceable>.
> -RAID10 has different layouts for distributing the copies. The default is
> -near copies. Near copies have all of the copies at about the same offset
> -on all of the disks. Far copies have the copies at different offsets on
> -the disks. Offset copies copy the stripe, not the individual copies.
> +RAID10 supports three different layouts for distributing the copies.
> +<firstterm>Near</firstterm> copies, the default, have all of the
> +copies at about the same offset on all of the disks.
> +<firstterm>Far</firstterm> copies have the copies at different offsets
> +on the disks. <firstterm>Offset</firstterm> copies duplicate stripes,
> +not the individual copies.

"RAID10 has different layouts" is hard to follow.  Then the rest of
this paragraph suffers slightly from excessively short sentences -
not a common problem in technical writing!  Yes, short tends to be
good, but if you take it too far it ends up choppy and repetitive,
so I've merged the sentence about "near" being the default into the
following one.

The definition of "offset copies" was confusing, so I've called in a
synonym.  It still isn't easy to follow, but at least it doesn't
seem to be saying that in the other layouts copies copy copies.

>  
>  </para><para>
>  
> @@ -141,7 +143,7 @@
>    <entry>Type</entry>
>    <entry>Minimum Devices</entry>
>    <entry>Spare Device</entry>
> -  <entry>Survives disk failure?</entry>
> +  <entry>Survives Disk Failure?</entry>
>    <entry>Available Space</entry>
>  </row>
>  </thead>

Consistent capitalisation.

> @@ -152,7 +154,10 @@
>    <entry>2</entry>
>    <entry>no</entry>
>    <entry>no</entry>
> -  <entry>Size of the smallest partition multiplied by number of devices in 
> RAID</entry>
> +  <entry>
> +    Size of the smallest partition multiplied by number of devices in
> +    RAID
> +  </entry>
>  </row>

Just making the layout consistent with the other columns.

>  
>  <row>
> @@ -191,7 +196,8 @@
>    <entry>optional</entry>
>    <entry>yes</entry>
>    <entry>
> -    Total of all partitions divided by the number of chunk copies (defaults 
> to two)
> +    Total of all partitions divided by the number of chunk copies
> +    (defaults to two)
>    </entry>
>  </row>

Ditto.  (The fact that it says "two" rather than "2" was the deciding
vote against referring to a default value as "2" above.) 

>  
> @@ -200,15 +206,14 @@
>  </para><para>
>  
>  If you want to know more about Software RAID, have a look
> -at <ulink url="&url-software-raid-howto;">Software RAID HOWTO</ulink>.
> +at the <ulink url="&url-software-raid-howto;">Software RAID HOWTO</ulink>.

Well, we're treating it as definitive, so let's give it the
definite article.

>  
>  </para><para>
>  
> -To create an MD device, you need to have the desired partitions it
> -should consist of marked for use in a RAID.  (This is done in
> -<command>partman</command> in the <guimenu>Partition
> -settings</guimenu> menu where you should select <menuchoice>
> -<guimenu>Use as:</guimenu> <guimenuitem>physical volume for
> +To create a RAID setup, you need to mark the partitions you want it to
> +consist of as intended for use in a RAID array.  (This is done in the
> +<guimenu>Partition settings</guimenu> menu, where you should select
> +<menuchoice> <guimenu>Use as:</guimenu> <guimenuitem>physical volume for
>  RAID</guimenuitem> </menuchoice>.)

Don't call it MD, call it RAID (but not "a RAID", and avoid repeating
"RAID array").

Talking about having the partitions marked makes it sound as if
either it needs to already have been done or you've had someone do
it for you.  Just phrase it in terms of what you should do.

As usual it's fairly pointless to mention partman, since users have no
way of knowing whether they're "in partman" or not.  Just get on with
introducing the menu item they do see.

>  
>  </para><note><para>
> @@ -217,29 +222,29 @@
>  you are planning. In general it will be necessary to create a separate
>  file system for <filename>/boot</filename> when using RAID for the root
>  (<filename>/</filename>) file system.
> -Most boot loaders <phrase arch="x86">(including lilo and grub)</phrase>
> +Most boot loaders <phrase arch="x86">(including LILO and GRUB)</phrase>

The "upstream brandnames" (as opposed to the things you'd wrap in
<command> or <package> tags) are all-caps.

>  do support mirrored (not striped!) RAID1, so using for example RAID5 for
> -<filename>/</filename> and RAID1 for <filename>/boot</filename> can be
> -an option.
> +<filename>/</filename> and RAID1 for <filename>/boot</filename> is an
> +option.

You can use it, and it is an option; saying that it can be an option
is overconditionalisation.

>  
>  </para></note><para>
>  
>  Next, you should choose <guimenuitem>Configure software
> -RAID</guimenuitem> from the main <command>partman</command> menu.
> -(The menu will only appear after you mark at least one partition for
> -use as <guimenuitem>physical volume for RAID</guimenuitem>.)
> -On the first screen of <command>mdcfg</command> simply select
> +RAID</guimenuitem> from the main partitioning menu.
> +(The option will only appear after you mark at least one partition for
> +use as a <guimenuitem>physical volume for RAID</guimenuitem>.)
> +On the first RAID configuration screen, simply select

You can't expect users to navigate by D-I module names when those
names aren't signposted in D-I.  This particular case is even more
unhelpful, since it mentions the partman menu, then says "The menu"
will appear - but it doesn't mean it'll cause the appearance of the
partman menu, it means the option "Configure software RAID" (which if
chosen will open a submenu)!

(Oh, and there's a missing indefinite article.)

Likewise, mdcfg isn't signposted as mdcfg.  (And none of these module
names is a <command>.)

>  <guimenuitem>Create MD device</guimenuitem>. You will be presented with

I don't have any choice about this, but it would be nice if it could
be eliminated from D-I as well.

> -a list of supported types of MD devices, from which you should choose
> -one (e.g. RAID1). What follows depends on the type of MD you selected.
> +a list of supported RAID types, from which you should choose
> +one (e.g. RAID1). What follows depends on the type of RAID you selected.
>  </para>

Don't call it MD, call it RAID.

>  <itemizedlist>
>  <listitem><para>
>  
> -RAID0 is simple &mdash; you will be issued with the list of available
> +RAID0 is simple &mdash; you will be presented with the list of available
>  RAID partitions and your only task is to select the partitions which
> -will form the MD.
> +will form the array.

I might be "issued with" a passport or a gasmask or something, but
it doesn't fit this context.

Don't call it MD, call it... well, call the technology RAID, but
call the instance an array.

>  
>  </para></listitem>
>  <listitem><para>
> @@ -246,10 +251,10 @@
>  
>  RAID1 is a bit more tricky. First, you will be asked to enter the
>  number of active devices and the number of spare devices which will
> -form the MD. Next, you need to select from the list of available RAID
> +form the array. Next, you need to select from the list of available RAID

Ditto.

>  partitions those that will be active and then those that will be
>  spare. The count of selected partitions must be equal to the number
> -provided earlier. Don't worry. If you make a mistake and
> +provided earlier. Don't worry &mdash; if you make a mistake and
>  select a different number of partitions, &d-i; won't let you
>  continue until you correct the issue.

Or it might deserve a colon.

>  
> @@ -269,8 +274,8 @@
>  <listitem><para>
>  
>  RAID10 again has a setup procedure similar to RAID1 except in expert
> -mode. In expert mode, &d-i; will ask you for the layout.
> -The layout has two parts. The first part is the layout type. It is either
> +mode. In expert mode, &d-i; will ask you for the layout, which
> +has two parts. The first part is the layout type, which is either
>  <literal>n</literal> (for near copies), <literal>f</literal> (for far
>  copies), or <literal>o</literal> (for offset copies). The second part is
>  the number of copies to make of the data. There must be at least that

Again merging short, choppy, repetitive sentences.

(There are people who would say you can't have "either" of three
things, but I disagree with them.)


> @@ -282,19 +287,19 @@
>  
>  <para>
>  
> -It is perfectly possible to have several types of MD at once. For
> -example, if you have three 200 GB hard drives dedicated to MD, each
> -containing two 100 GB partitions, you can combine the first partitions on
> -all three disks into the RAID0 (fast 300 GB video editing partition)
> -and use the other three partitions (2 active and 1 spare) for RAID1
> -(quite reliable 100 GB partition for <filename>/home</filename>).
> +It is perfectly possible to have several types of RAID at once. For
> +example, if you have three 200&nbsp;GB hard drives dedicated to RAID, each
> +containing two 100&nbsp;GB partitions, you can combine the first partitions 
> on
> +all three disks into the RAID0 (a fast 300&nbsp;GB video editing partition)
> +and use the other three partitions (two active and one spare) for RAID1
> +(a quite reliable 100&nbsp;GB partition for <filename>/home</filename>).

Don't call it MD, call it RAID.

Separate numbers and units with non-breaking spaces.

Use words rather than figures for low numbers.

Add an indefinite article in the last line.

(These figures are getting cobwebby - 100 GB looks distinctly cramped
for a home partition these days - but who knows, maybe there's a huge
fileserver on the network as well.)

>  
>  </para><para>
>
> -After you set up MD devices to your liking, you can
> -<guimenuitem>Finish</guimenuitem> <command>mdcfg</command> to return
> -back to the <command>partman</command> to create filesystems on your
> -new MD devices and assign them the usual attributes like mountpoints.
> +After you have set up RAID to your liking, you can select
> +<guimenuitem>Finish</guimenuitem> to return
> +to the partitioner so you can create filesystems on your
> +new RAID array and assign them the usual attributes, such as mountpoints.

Don't call it MD, call it RAID, and don't expect users to navigate
by D-I module names.

Plus a few fixes for minor language problems, such as that "return
back" is redundant (and I don't mean the good sort of redundant).
-- 
JBR     with qualifications in linguistics, experience as a Debian
        sysadmin, and probably no clue about this particular package
Index: mdcfg.xml
===================================================================
--- mdcfg.xml	(revision 70030)
+++ mdcfg.xml	(working copy)
@@ -2,32 +2,32 @@
 <!-- $Id$ -->
 
    <sect3 id="mdcfg">
-   <title>Configuring Multidisk Devices (Software RAID)</title>
+   <title>Configuring Software RAID</title>
 <para>
 
-If you have more than one harddrive<footnote><para>
+If you have more than one hard drive<footnote><para>
 
-To be honest, you can construct an MD device even from partitions
-residing on single physical drive, but that won't give any benefits.
+To be strictly accurate, you can construct a RAID array even from partitions
+residing on a single physical drive, but that won't give any benefits.
 
-</para></footnote> in your computer, you can use
-<command>mdcfg</command> to set up your drives for increased
-performance and/or better reliability of your data. The result is
-called <firstterm>Multidisk Device</firstterm> (or after its most
-famous variant <firstterm>software RAID</firstterm>).
+</para></footnote> in your computer, you can set up your drives for
+improved performance and/or reliability by using software RAID.
+The &d-i; module used for this is <literal>mdcfg</literal>, named
+after the Linux <literal>md</literal> (<quote>Multiple Device</quote>)
+driver.
 
 </para><para>
 
-MD is basically a bunch of partitions located on different disks and
-combined together to form a <emphasis>logical</emphasis> device. This
-device can then be used like an ordinary partition (i.e. in
-<command>partman</command> you can format it, assign a mountpoint,
-etc.).
+A RAID array is basically a bunch of partitions located on different
+disks and combined together to form a <emphasis>logical</emphasis>
+device. You can then proceed with the install using it just like an
+ordinary partition &mdash; you can format it, assign a mountpoint, and
+so on.
 
 </para><para>
 
-What benefits this brings depends on the type of MD device you are
-creating. Currently supported are:
+What benefits this brings will depend on the type of RAID setup you
+create. Currently supported are:
 
 <variablelist>
 <varlistentry>
@@ -53,14 +53,14 @@
 <term>RAID1</term><listitem><para>
 
 Is suitable for setups where reliability is the first concern.  It
-consists of several (usually two) equally-sized partitions where every
+consists of several (usually two) equal-sized partitions where every
 partition contains exactly the same data. This essentially means three
 things.  First, if one of your disks fails, you still have the data
 mirrored on the remaining disks. Second, you can use only a fraction
 of the available capacity (more precisely, it is the size of the
-smallest partition in the RAID). Third, file-reads are load-balanced among
-the disks, which can improve performance on a server, such as a file
-server, that tends to be loaded with more disk reads than writes.
+smallest partition in the array). Third, file-reads are load-balanced between
+the disks, which can improve performance on systems such as file
+servers that tend to be loaded with more disk reads than writes.
 
 </para><para>
 
@@ -73,14 +73,14 @@
 
 <term>RAID5</term><listitem><para>
 
-Is a good compromise between speed, reliability and data redundancy.
+Is a good compromise between speed, reliability, and data redundancy.
 RAID5 splits all incoming data into stripes and distributes them
 equally on all but one disk (similar to RAID0). Unlike RAID0, RAID5
 also computes <firstterm>parity</firstterm> information, which gets
 written on the remaining disk. The parity disk is not static (that
-would be called RAID4), but is changing periodically, so the parity
+would be called RAID4), but changes periodically, so the parity
 information is distributed equally on all disks.  When one of the
-disks fails, the missing part of information can be computed from
+disks fails, the missing information can be computed from the
 remaining data and its parity. RAID5 must consist of at least three
 active partitions. Optionally you can have a spare disk in the array
 which will take the place of the failed disk in the case of failure.
@@ -88,9 +88,9 @@
 </para><para>
 
 As you can see, RAID5 has a similar degree of reliability to RAID1
-while achieving less redundancy. On the other hand, it might be a bit
-slower on write operations than RAID0 due to computation of parity
-information.
+with somewhat lower redundancy. On the other hand, it might be a bit
+slower on write operations than RAID0 due to the overhead of parity
+computation.
 
 </para></listitem>
 </varlistentry>
@@ -114,14 +114,16 @@
 RAID10 combines striping (as in RAID0) and mirroring (as in RAID1).
 It creates <replaceable>n</replaceable> copies of incoming data and
 distributes them across the partitions so that none of the copies of
-the same data are on the same device.
-The default value of <replaceable>n</replaceable> is 2, but it can be
+a given piece of data are on the same device.
+The default value of <replaceable>n</replaceable> is two, but it can be
 set to something else in expert mode. The number of partitions used
 must be at least <replaceable>n</replaceable>.
-RAID10 has different layouts for distributing the copies. The default is
-near copies. Near copies have all of the copies at about the same offset
-on all of the disks. Far copies have the copies at different offsets on
-the disks. Offset copies copy the stripe, not the individual copies.
+RAID10 supports three different layouts for distributing the copies.
+<firstterm>Near</firstterm> copies, the default, have all of the
+copies at about the same offset on all of the disks.
+<firstterm>Far</firstterm> copies have the copies at different offsets
+on the disks. <firstterm>Offset</firstterm> copies duplicate stripes,
+not the individual copies.
 
 </para><para>
 
@@ -141,7 +143,7 @@
   <entry>Type</entry>
   <entry>Minimum Devices</entry>
   <entry>Spare Device</entry>
-  <entry>Survives disk failure?</entry>
+  <entry>Survives Disk Failure?</entry>
   <entry>Available Space</entry>
 </row>
 </thead>
@@ -152,7 +154,10 @@
   <entry>2</entry>
   <entry>no</entry>
   <entry>no</entry>
-  <entry>Size of the smallest partition multiplied by number of devices in RAID</entry>
+  <entry>
+    Size of the smallest partition multiplied by number of devices in
+    RAID
+  </entry>
 </row>
 
 <row>
@@ -191,7 +196,8 @@
   <entry>optional</entry>
   <entry>yes</entry>
   <entry>
-    Total of all partitions divided by the number of chunk copies (defaults to two)
+    Total of all partitions divided by the number of chunk copies
+    (defaults to two)
   </entry>
 </row>
 
@@ -200,15 +206,14 @@
 </para><para>
 
 If you want to know more about Software RAID, have a look
-at <ulink url="&url-software-raid-howto;">Software RAID HOWTO</ulink>.
+at the <ulink url="&url-software-raid-howto;">Software RAID HOWTO</ulink>.
 
 </para><para>
 
-To create an MD device, you need to have the desired partitions it
-should consist of marked for use in a RAID.  (This is done in
-<command>partman</command> in the <guimenu>Partition
-settings</guimenu> menu where you should select <menuchoice>
-<guimenu>Use as:</guimenu> <guimenuitem>physical volume for
+To create a RAID setup, you need to mark the partitions you want it to
+consist of as intended for use in a RAID array.  (This is done in the
+<guimenu>Partition settings</guimenu> menu, where you should select
+<menuchoice> <guimenu>Use as:</guimenu> <guimenuitem>physical volume for
 RAID</guimenuitem> </menuchoice>.)
 
 </para><note><para>
@@ -217,29 +222,29 @@
 you are planning. In general it will be necessary to create a separate
 file system for <filename>/boot</filename> when using RAID for the root
 (<filename>/</filename>) file system.
-Most boot loaders <phrase arch="x86">(including lilo and grub)</phrase>
+Most boot loaders <phrase arch="x86">(including LILO and GRUB)</phrase>
 do support mirrored (not striped!) RAID1, so using for example RAID5 for
-<filename>/</filename> and RAID1 for <filename>/boot</filename> can be
-an option.
+<filename>/</filename> and RAID1 for <filename>/boot</filename> is an
+option.
 
 </para></note><para>
 
 Next, you should choose <guimenuitem>Configure software
-RAID</guimenuitem> from the main <command>partman</command> menu.
-(The menu will only appear after you mark at least one partition for
-use as <guimenuitem>physical volume for RAID</guimenuitem>.)
-On the first screen of <command>mdcfg</command> simply select
+RAID</guimenuitem> from the main partitioning menu.
+(The option will only appear after you mark at least one partition for
+use as a <guimenuitem>physical volume for RAID</guimenuitem>.)
+On the first RAID configuration screen, simply select
 <guimenuitem>Create MD device</guimenuitem>. You will be presented with
-a list of supported types of MD devices, from which you should choose
-one (e.g. RAID1). What follows depends on the type of MD you selected.
+a list of supported RAID types, from which you should choose
+one (e.g. RAID1). What follows depends on the type of RAID you selected.
 </para>
 
 <itemizedlist>
 <listitem><para>
 
-RAID0 is simple &mdash; you will be issued with the list of available
+RAID0 is simple &mdash; you will be presented with the list of available
 RAID partitions and your only task is to select the partitions which
-will form the MD.
+will form the array.
 
 </para></listitem>
 <listitem><para>
@@ -246,10 +251,10 @@
 
 RAID1 is a bit more tricky. First, you will be asked to enter the
 number of active devices and the number of spare devices which will
-form the MD. Next, you need to select from the list of available RAID
+form the array. Next, you need to select from the list of available RAID
 partitions those that will be active and then those that will be
 spare. The count of selected partitions must be equal to the number
-provided earlier. Don't worry. If you make a mistake and
+provided earlier. Don't worry &mdash; if you make a mistake and
 select a different number of partitions, &d-i; won't let you
 continue until you correct the issue.
 
@@ -269,8 +274,8 @@
 <listitem><para>
 
 RAID10 again has a setup procedure similar to RAID1 except in expert
-mode. In expert mode, &d-i; will ask you for the layout.
-The layout has two parts. The first part is the layout type. It is either
+mode. In expert mode, &d-i; will ask you for the layout, which
+has two parts. The first part is the layout type, which is either
 <literal>n</literal> (for near copies), <literal>f</literal> (for far
 copies), or <literal>o</literal> (for offset copies). The second part is
 the number of copies to make of the data. There must be at least that
@@ -282,19 +287,19 @@
 
 <para>
 
-It is perfectly possible to have several types of MD at once. For
-example, if you have three 200 GB hard drives dedicated to MD, each
-containing two 100 GB partitions, you can combine the first partitions on
-all three disks into the RAID0 (fast 300 GB video editing partition)
-and use the other three partitions (2 active and 1 spare) for RAID1
-(quite reliable 100 GB partition for <filename>/home</filename>).
+It is perfectly possible to have several types of RAID at once. For
+example, if you have three 200&nbsp;GB hard drives dedicated to RAID, each
+containing two 100&nbsp;GB partitions, you can combine the first partitions on
+all three disks into the RAID0 (a fast 300&nbsp;GB video editing partition)
+and use the other three partitions (two active and one spare) for RAID1
+(a quite reliable 100&nbsp;GB partition for <filename>/home</filename>).
 
 </para><para>
 
-After you set up MD devices to your liking, you can
-<guimenuitem>Finish</guimenuitem> <command>mdcfg</command> to return
-back to the <command>partman</command> to create filesystems on your
-new MD devices and assign them the usual attributes like mountpoints.
+After you have set up RAID to your liking, you can select
+<guimenuitem>Finish</guimenuitem> to return
+to the partitioner so you can create filesystems on your
+new RAID array and assign them the usual attributes, such as mountpoints.
 
 </para>
    </sect3>

Reply via email to