Re: (forw) [RFR] D-I Manual: new section on how to load firmware during installs
Christian Perrier forwarded:
> From: Frans Pop <elendil@planet.nl>
[...]
> I have written a draft text for that. Review and comments welcome.
>
> The main description is in a new section:
> - http://people.debian.org/~fjp/tmp/d-i/manual/ch06s04.html
Looks good. One possible change in 6.4 paragraph 2:
# If a device driver requests firmware that is not available, debian-installer
# will display a dialog offering to load the missing firmware. If that question
# is confirmed, debian-installer will scan available devices for either loose
# firmware files or packages containing firmware. If found, the firmware will
# be copied to the correct location (/lib/firmware) and the driver module will
# be reloaded.
Should that be "If this option is selected"?
Oh, and in 6.4 at the end of paragraph 1:
# [...] The recommended file system to use is FAT as that is most
# certain to be supported during the early stages of the installation.
"Most certain" seems somehow wrong. Is "the most certain" better,
or does it only seem that way because it's my idea?
It probably needs a comma after "FAT".
Oh, definite typo at the end of 6.4.2 paragraph 2:
# This has the advantage that the firmware should be updated automatically if
# new a version becomes available.
^^^ ^
"A new version".
> Besides that I've added short introductions regarding firmware with links
> to the new section in the following places:
> - http://people.debian.org/~fjp/tmp/d-i/manual/ch02s02.html
First paragraph:
# Besides the availability of a device driver some hardware also requires
# so-called firmware or microcode to be loaded into the device before it can
# become operational.
This could do with a comma, and maybe a bit of pruning:
As well as device drivers, some hardware also requires [...]
Last paragraph of 2.2:
# Starting with Debian GNU/Linux 5.0 the debian-installer supports loading
# firmware files [...]
Usually where it has a definite article it's "the Debian Installer".
To avoid repeating "Debian" this should probably be:
Starting with Debian GNU/Linux 5.0, debian-installer supports loading
firmware files [...]
> - http://people.debian.org/~fjp/tmp/d-i/manual/ch06s03.html
6.3.1 paragraph 3:
# During hardware detection debian-installer checks if any of the drivers for
# the hardware devices in your system requires firmware to be loaded. If any
# firmware is requested but unavailable, a dialog will be displayed that
# allows to load the missing firmware from a removable medium. [...]
Where "any of the drivers" may be plural it sounds odd to give it
singular agreement.
Then "allows to load". Nope, you need a direct object.
During hardware detection debian-installer checks if any of the drivers for
the hardware devices in your system require firmware to be loaded. If any
firmware is requested but unavailable, a dialog will be displayed that
allows the missing firmware to be loaded from a removable medium. [...]
6.3.1.1 para 1 line 1:
# One of the first things debian-installer does, is to check available
# memory.
Make that:
One of the first things debian-installer does is check available
memory.
6.3.1.1 paragraph 4 refers to "a relatively large swap partition
(64-128MB)". I suppose it means "large relative to the machine's
even smaller supply of physical RAM"; maybe the word is
"disproportionately"?
6.3.1.1 paragraph 5:
# Despite these measures, it is still possible that your system freezes, that
# unexpected errors occur or that processes are killed by the kernel because
# the system runs out of memory (which will result in "Out of memory"
# messages on VT4 and in the syslog).
Tweak some verbs:
Despite these measures, it is still possible that your system will freeze,
that unexpected errors will occur, or that processes will be killed by the
kernel if it runs out of memory (which will result in "Out of memory"
messages on VT4 and in the syslog).
6.3.1.2 para 4, second line:
# [...] The language names are listed in both English (left side) and in the
# language itself (right side); [...]
This feels really picky, but if there are two "in"s then the "both"
should be outside the scope of the first:
[...] The language names are listed both in English (left side) and in the
language itself (right side); [...]
6.3.1.4 para 1 line 1:
# When installing via the hd-media method, there will be a moment where you
# need to find and mount the Debian Installer iso image in order to get the
# rest of the installation files. The component iso-scan does exactly this.
s/ iso / ISO /g.
Before that, "a moment" isn't a "where", it's a "when". But we've
already had a "when", so maybe:
If you are installing via the hd-media method, there will be a point where
you need to find and mount the Debian Installer ISO image [...]
6.3.1.4 para 3:
# In case the previous attempt to find an installer iso image fails,
# iso-scan will ask you whether you would like to perform a more thorough
# search.
This use of "in case" (to mean "if") is accepted in some dialects,
but in mine it would normally be taken to imply that it asks
_first_, unconditionally, to set up a safety net (compare the Note
in 6.3.8.3). And "previous attempt" implies that there's a current
one, but that hasn't started yet. What you want is:
In the case of a failed attempt to find an installer ISO image, iso-scan
will ask you whether you would like to perform a more thorough search.
6.3.1.5 para 3:
# The manual network setup in turn asks you a number of questions
# about your network, notably IP address, Netmask, Gateway, Name
# server addresses, and a Hostname.
Is that "In its turn, the manual network setup asks you a number of
questions" or "The manual network setup asks you a number of
questions in turn"? What's notable about these questions? Why the
German Caps? I'd suggest:
The manual network setup asks you a series of questions about your
network: IP address, netmask, gateway, name server addresses, and
a hostname.
6.3.2.2 para 1:
# [...] How to manually setup your partition table [...]
No, you haven't split that infinitive enough! It's "a setup", but
"to set up", so:
# [...] How to manually set up your partition table [...]
There are also a couple of other uses of "to setup" in 6.3.2.3 (near
the start, "use mdcfg to setup your drives"; near the end, "After
you setup MD devices"). The verb is always two words.
Either my eyes are getting tired or the next bit is better.
However, in 6.3.2.3's section on RAID5:
# [...] The parity disk is not static (that would be called RAID4), but
# is changing 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 remaining data and its parity.
That makes it sound like a (recoverable) loss of data instead of a
(recoverable) loss of redundancy. Maybe:
[...] The parity disk is not static (that would be called RAID4), but
changes periodically, so the parity information is distributed
equally on all disks. When one of the disks fails, no information
is lost and the array can be fully reconstructed.
Then after the table:
# To create a MD device, you need to have the desired partitions it should
# consist of marked for use in a RAID. (This is done in partman in the
# Partition settings menu where you should select Use as: -> physical
# volume for RAID.)
That's AN em dee device; and the rest is a bit awkward.
To create an MD device, you need to mark the appropriate partitions
as being intended for this use in partman's Partition settings menu;
select Use as: -> physical volume for RAID.
Later, in the bulleted list, there are a couple of article problems:
# * 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
# 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 few seconds ago.
^a (earlier?)
(Or perhaps "the number you just gave".)
# Don't worry. If you make a mistake and select different number of
^a
# partitions, the debian-installer won't let you continue until you
^^^
# correct the issue.
#
# * RAID5 has a similar setup procedure as RAID1 [...]
^^
# * RAID6 also has a similar setup procedure as RAID1 [...]
^^
# * RAID10 again has a similar setup procedure as RAID1 [...]
^^
Similar to, not similar as; s/ as / to /g
6.3.2.4 para 1:
# [...] and you had to manage this situation with moving stuff around,
# symlinking, etc.
s/with/by/
Para 2:
# To avoid the described situation you can use Logical Volume Manager
# (LVM). Simply said, with LVM you can combine your partitions [...]
s/Simply said/To put it simply/
Para 3:
# Now when you realize you need more space for your old 160GB /home
# partition, you can simply add a new 300GB disk to the computer, join it
# with your existing volume group and then resize the logical volume
# which holds your /home filesystem and voila [...]
I'd spell that voilà, but maybe this is an en_USism.
The "Note" paragraph:
# [...] The performance impact depends on your CPU speed, chosen cipher and
# a key length
^
Why "a"? I'd suggest:
# [...] The performance impact depends on the chosen cipher and key length
# and on your CPU speed.
In the second-last paragraph of 6.3.2.4:
# One thing to note here are the identifiers in parentheses (sda2_crypt and
(--singular---) (---plural---)
# loop0 in this case) and the mount points you assigned to each encrypted
# volume. You will need this information later when booting the new system.
# The differences between ordinary boot process and boot process with
^the ^the
# encryption involved will be covered later [...]
Make that:
# Pay attention to the identifiers in parentheses (sda2_crypt and loop0 in
# this case) and the mount points you assigned to each encrypted volume.
# You will need this information later when booting the new system.
# The differences between the ordinary boot process and the boot process
# with encryption involved will be covered later [...]
6.3.4.2 paragraph 1:
# The system will ask you whether you wish to create an ordinary user account
# at this point. This account should be your main personal log-in. You should
# not use the root account for daily use or as your personal login.
The noun is "login", but I'd prefer something like
[...] This should be your main personal login account. [...]
6.3.5.1 paragraph 2:
# apt must be configured so that it knows from where to retrieve packages.
Far more natural as "knows where to retrieve packages from", but if
people have taboos against that I'd recommend "knows where to find
packages".
6.3.5.1 last para:
# If you do scan multiple CDs or DVDs, the installer will prompt you to
# exchange them when it needs packages from another CD/DVD than the one
# currently in the drive. [...]
I'd have said "from a CD/DVD other than the one..."
6.3.6.4, end of para 2:
# [...] Other information you will need are the disk and partition you
# selected for your / filesystem and, if you chose to install /boot
# on a separate partition, also your /boot filesystem.
First, information doesn't "are". But rephrase:
[...] You will also need to remember the disk and partition you selected
for your root (/) file system, plus your /boot partition if you chose to
make that a separate file system.
(Oh, wait, I haven't been checking for s/filesystem/file system/g.)
6.3.8.2 para 1:
# [...] Use Left Alt+F1 to switch back to installer itself.
^the
Section 6.3.8.3 is good on the whole, but might want some extra caps
in "non-ASCII" and (several times) "SSH".
In the Note paragraph:
# [...] ssh will refuse to connect to such host. The reason is that it
# will have different fingerprint [...]
Yes, that's (/usr/bin/)ssh, but I'm not keen on "such host" or
"different fingerprint". Maybe:
[...] ssh will refuse to connect to these hosts, because they will
have different fingerprints [...]
Footnote 11:
# To be honest, you can construct MD device even from partitions residing
# on single physical drive, but that won't bring you anything useful.
Say:
Indeed, you can construct an MD device even from partitions residing
on a single physical drive, but that won't give any benefits.
Footnote 17:
# The following command will remove an existing entry for a host:
# ssh-keygen -R <hostname|IPaddress>.
Perhaps that should be "<hostname or IP address>".
(Phew.)
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: