Re: [RFR] templates://uswsusp/{uswsusp.templates}
Christian Perrier wrote:
> Your review should be sent as an answer to this mail.
I'm adopting MJ's suggestions throughout.
> Avoid "corner cases" which sounds like spoken language to me (I may be
> wrong)
(Used accurately it's a piece of technical jargon from engineering;
here it was a slightly colloquial/inaccurate usage, best avoided.)
> Template: uswsusp/snapshot_device
[...]
> + Please specify the preferred maximum image size (in bytes) for the
> + system's snapshot.
s/system's/system/ - or maybe even, to save a line:
Please specify a maximum system snapshot image size (in bytes).
> + This limit is not strict; the uswsusp tool will do its best to limit
> + the image size as specified by this parameter. However, if suspend
> + needs a bigger image, that size will be exceeded.
Squeezing:
This limit is not strict; uswsusp does its best to respect it, but will
exceed the specified limit if suspend needs a bigger image.
> + Using 0 for that parameter will enforce the use of the smallest
> + possible snapshot image. An empty value will use the hard coded
> + default, which is 500MB. The default value is 45% of the system's
> + memory: this is not the maximal size, but some additional free memory
> + speeds up the suspend and resume process.
s/for that parameter/here/ (saving another line).
> Template: uswsusp/suspend_loglevel
[...]
> +_Description: Log level for software suspend:
> + Please specify the kernel console log level which the s2disk/s2both
> + and resume utilities will use to report the suspend and resume
> + progress. On a stock kernel, messages with levels higher than 7 are
> + usually not shown.
s/the suspend and resume progress/the progress of suspend and resume/
> Template: uswsusp/max_loglevel
> Type: string
> _Description: Maximal log level:
> - You can specify the kernel console loglevel which the resume utility will use
> + Please specify the kernel console log level which the resume utility will use
> in case the resume fails.
I assume that's the usage of "in case" that's synonymous with "if"
(i.e. "conditionally, in the case that..."). That can be confusing
for speakers of dialects like mine where "in case" only ever means
"lest" ("unconditionally, in order to avoid...").
I would recommend simplifying s/in case/if/.
> Template: uswsusp/compress
[...]
> + The resume device synchronization can start early in the process of writing
> + the image to it. This has been reported to speed up suspend on some
> + systems and eliminate the 'fast progress meter and long fsync wait' effect.
I can't quite say why, but this is better as:
The synchronization of the resume device can start early in the
process of writing the image to it.
> Template: uswsusp/RSA_key_file
[...]
> + To avoid being prompted for a passphrase during each suspend,
> + an RSA key can be used to encrypt the image.
The subject of the sentence (the key) isn't the one who's avoiding
being prompted. Make it:
To avoid the need for a passphrase prompt during each suspend,
an RSA key can be used to encrypt the image.
> Template: uswsusp/RSA_key_bits
[...]
> + Please specify the size of the RSA key (number of bits between 1024
> + and 4096). A bigger key adds increases the encryption strength but slows
^^^^
> + down the encryption process.
Surplus word.
> Template: uswsusp/shutdown_method
[...]
> + If this parameter is set to 'reboot', the s2disk utility will
> + reboot the machine rather than powering down. This is usually useful
> + for testing purposes.
Usually useful is slightly repetitive, and besides, usually you
aren't testing. How about "This can be useful"?
> Strangely, this template does not explain what "platform" is meant for.
The HOWTO says:
If it is set to "platform", the machine will be shut down using special
power management operations available from the kernel that may be necessary
for the hardware to be properly reinitialized after the resume, and may cause
the system to resume faster (this is the recommended shutdown method on the
majority of systems). For any other value the machine will be powered off.
The default is to use the "platform" method. [For this feature to work,
you will need an -mm kernel, 2.6.18-mm3 or newer.]
If I'm following that correctly, we might summarise it as "using
hardware-specific optimization if available".
In the control file:
> Description: tools to use userspace software suspend provided by Linux
> - uswsusp (also known as µswsusp or simply suspend) contains the programs to
> + This package contains the programs to
It seems a pity to lose the explanation for u = mu-for-micro...
> use the userspace software suspend facility available in Linux kernel
> - 2.6.17-rc1 and higher. It enables you to save the state of the whole system
> - to disk and power off your system. After restarting your system it will be
> - put back in the exact system state you left it (this is sometimes called
> + 2.6.17-rc1 and higher. It allows saving the state of the whole system
> + to disk and powering off the system. When restarting, the system will be
> + put back in the state it was left (this is sometimes called
> hibernation).
Various small changes (e.g. too many systems and a missing in):
This package (also known as µswsusp or simply suspend) contains the
programs to use the userspace software suspend facility available in
Linux kernels 2.6.17-rc1 and higher. It allows the system to have its
state saved to disk and be powered off. On restarting, it will be put
back in the state it was left in (this is sometimes called
hibernation).
> Change "enables you to save" which sounds incorrect to me.
It's fine as English, but it did introduce an unnecessary "you".
> + It also includes a program to suspend the system to RAM after the
> + state is saved to disk. In that state, the system still uses power,
> + but resuming is faster. In case the battery depletes, the state is
> + resumed from disk without data loss.
Again s/in case/if/
And then I'm introducing two miscellaneous amendments.
In uswsusp/compute_checksum: s/a check sum/a checksum/
In uswsusp/compress: "with LZF compression algorithm" needs "the".
--
JBR
Ankh kak! (Ancient Egyptian blessing)
--- ../uswsusp.old/debian/uswsusp.templates 2007-09-20 07:40:59.000000000 +0100
+++ debian/uswsusp.templates 2007-09-23 18:03:13.000000000 +0100
@@ -1,35 +1,39 @@
Template: uswsusp/resume_device
Type: select
Choices: ${list}
-_Description: The swap space to resume from:
- To be able to suspend your system, uswsusp needs a swap partition or file
- to write a snapshot of your system to. Provided is a list of suitable swap
- spaces, sorted by size, the largest first.
+_Description: Swap space to resume from:
+ To be able to suspend the system, uswsusp needs a swap partition or file
+ to store a system snapshot. Please choose the device to use, from the
+ list of suitable swap spaces, sorted by size (largest first).
Template: uswsusp/resume_offset
Type: string
Description: Offset of swap file's header:
- When using a swap file for storing the snapshot during suspend, you need to
- specify where the swap file's header is located. This parameter specifies this
- location, in <PAGE_SIZE> units, as the offset from the beginning of the
+ When using a swap file for storing the snapshot during suspend, the
+ location of the swap file's header must be specified. This will be
+ stored in <PAGE_SIZE> units, as the offset from the beginning of the
partition that contains the swap file.
Template: uswsusp/no_swap
Type: error
-_Description: No swap space found; userspace software suspend will not work
- To be able to suspend your system, uswsusp needs a swap partition or file to
- write a snapshot of your system to. Your system doesn't seem to have such a
- space. Please make one, preferably with twice the size of your physical ram.
- Then run dpkg-reconfigure or setup the configuration file yourself.
+_Description: No suitable swap space for software suspend
+ To be able to suspend the system, uswsusp needs a swap partition or file to
+ store a system snapshot. No such space seems to be available for this.
+ .
+ You should create a swap partition or file, preferably twice the size of
+ the system's physical RAM.
+ .
+ Then, run 'dpkg-reconfigure uswsusp' or edit the configuration file
+ manually.
Template: uswsusp/no_snapshot
-Type: note
-_Description: Your kernel doesn't support userspace software suspend
- Your kernel doesn't support userspace software suspend. Please reconfigure
- your kernel to include CONFIG_SOFTWARE_SUSPEND=y and recompile.
+Type: error
+_Description: No userspace software suspend support in the kernel
+ The current kernel doesn't support userspace software suspend. Please
+ recompile the kernel with the 'CONFIG_SOFTWARE_SUSPEND=y' option.
Template: uswsusp/continue_without_swap
@@ -37,60 +41,65 @@
Default: true
_Description: Continue without a valid swap space?
The swap file or partition that was found in uswsusp's configuration
- file is not active. In most cases this means userspace software suspend will
- not work for you and you will need to choose (or let uswsusp choose) another
- swap space. In some corner cases however, this can be what you want.
+ file is not active.
+ .
+ In most cases this means userspace software suspend will
+ not work as expected. You should choose another swap space.
+ .
+ However, in some rare cases, this configuration may be intentional.
Template: uswsusp/snapshot_device
Type: string
_Description: The device node through which uswsusp can talk to the kernel:
- If you leave this empty, you will get the hardcoded default, /dev/snapshot.
- This should be OK in almost all cases, don't change this unless you have a
- good reason to do so.
+ If this is empty, the hardcoded default, /dev/snapshot, is used.
+ This should be OK in almost all cases. Don't change this unless there
+ is a good reason to do so.
Template: uswsusp/image_size
Type: string
_Description: Preferred maximum image size:
- You can specify the preferred maximum image size (in bytes). This is not a hard
- bound; the uswsusp tool will do its best to limit the image size as specified
- by this parameter, but if that's not possible, it will suspend the system
- anyway with a bigger image. If this value is set to 0, the snapshot image will
- be as small as possible. If you leave it empty you get the hard coded default,
- which is 500MB. The default value you are presented with is 45% of the memory
- available on your system, this is not the maximal size, but some additional
- free memory speeds up the suspend and resume process.
+ Please specify a maximum system snapshot image size (in bytes).
+ .
+ This limit is not strict; uswsusp does its best to respect it, but will
+ exceed the specified limit if suspend needs a bigger image.
+ .
+ Using 0 here will enforce the use of the smallest possible snapshot image.
+ An empty value will use the hard coded default, which is 500MB. The
+ default value is 45% of the system's memory: this is not the maximal size,
+ but some additional free memory speeds up the suspend and resume process.
Template: uswsusp/suspend_loglevel
Type: string
-_Description: Log level:
- You can specify the kernel console loglevel which the s2disk/s2both and resume
- utilities will use to report progress. On a stock kernel, messages with
- level higher then 7 are usually not shown.
+_Description: Log level for software suspend:
+ Please specify the kernel console log level which the s2disk/s2both
+ and resume utilities will use to report the progress of suspend and
+ resume. On a stock kernel, messages with levels higher than 7 are
+ usually not shown.
Template: uswsusp/max_loglevel
Type: string
_Description: Maximal log level:
- You can specify the kernel console loglevel which the resume utility will use
- in case the resume fails.
+ Please specify the kernel console log level which the resume utility will use
+ if the resume fails.
Template: uswsusp/compute_checksum
Type: boolean
Default: false
_Description: Perform checksum on image?
- Performing a check sum using the MD5 algorithm to verify the image
- integrity is slightly safer, but also takes slightly more time.
+ Performing a checksum using the MD5 algorithm to verify the image
+ integrity is slightly safer, but also takes more time.
Template: uswsusp/compress
Type: boolean
Default: true
_Description: Compress image?
- Compressing the image with LZF compression algorithm will result in a
+ Compressing the image with the LZF compression algorithm will result in a
smaller image, which makes it possible to suspend with a smaller swap
partition. Generally it will also make reading and writing the image faster
because there is less to read and write.
@@ -100,75 +109,74 @@
Type: boolean
Default: true
_Description: Perform early write out?
- uswsusp can start syncing the resume device early in the process of writing
- the image to it. This has been reported to speed up the suspend on some
- boxes and eliminate the "fast progress meter and long fsync wait" effect.
+ The synchronization of the resume device can start early in the process of
+ writing the image to it. This has been reported to speed up suspend on some
+ systems and eliminate the 'fast progress meter and long fsync wait' effect.
Template: uswsusp/splash
Type: boolean
Default: true
_Description: Show splash screen?
- Instead of informative output you can enjoy a nice splash screen with progress
- bar during the suspend and resume process. For this to work you will need to
- have the splashy package installed.
+ Instead of informative output, a splash screen with progress bar can
+ be shown during the suspend and resume process. This requires the splashy
+ package to be installed.
Template: uswsusp/encrypt
Type: boolean
Default: false
_Description: Encrypt snapshot?
- For added security it is possible to encrypt the snapshot of your system
- that is written to disk during suspend. On resume (and suspend if you don't
- you use an RSA key) you will be asked to provide a passphrase. With encryption
- the suspend and resume process will take significantly more time.
+ For increased security, it is possible to encrypt the snapshot
+ that is written to disk during suspend. On resume (and suspend unless
+ using an RSA key), you will be prompted for a passphrase. Encryption
+ adds a significant time to the suspend and resume processes.
Template: uswsusp/RSA_key_file
Type: string
Default: /etc/uswsusp.key
_Description: Path to RSA key file:
- To avoid being prompted for a passphrase during suspend every time, one can
- supply an RSA key which will be used to encrypt the image. This option takes
- the path to that file. The default path will be good for most people. If
- you don't want to use an RSA key, leave this empty.
+ To avoid the need for a passphrase prompt during each suspend,
+ an RSA key can be used to encrypt the image.
+ .
+ Please specify the path to that file. Leave this field empty to not
+ use an RSA key.
Template: uswsusp/create_RSA_key
Type: boolean
Default: false
-_Description: Create RSA key?
- The key necessary for using the RSA encryption scheme can be generated for you.
+_Description: Create an RSA key?
+ The key necessary for using the RSA encryption scheme can be generated now.
You will be prompted for a passphrase.
Template: uswsusp/RSA_key_bits
Type: string
Default: 1024
-_Description: RSA key bits:
- The number of bits (between 1024 and 4096 inclusive) the RSA key will have.
- The more bits, the more secure, but also slower operation.
+_Description: RSA key size:
+ Please specify the size of the RSA key (number of bits between 1024
+ and 4096). A bigger key increases the encryption strength but slows
+ down the encryption process.
Template: uswsusp/RSA_passphrase
Type: password
_Description: RSA passphrase:
- This is the passphrase you will have to type on every resume to decrypt the
+ Please choose the passphrase to use on every resume to decrypt the
image.
Template: uswsusp/RSA_passphrase_v
Type: password
-_Description: RSA passphrase (again):
- To verify you know what you just typed, type the passphrase again.
+_Description: RSA passphrase confirmation:
Template: uswsusp/shutdown_method
Type: select
-Choices: reboot, platform, poweroff
+__Choices: reboot, platform, poweroff
Default: platform
Description: Shutdown method:
- If the "shutdown method" parameter is set to "reboot", the s2disk utility will
- reboot the machine rather than powering down. This is useful when testing
- repeated benchmarks, such as when checking whether "early writeout" produces a
- speedup or not for your combination of hardware, image size, and s2disk
- parameters.
+ If this parameter is set to 'reboot', the s2disk utility will
+ reboot the machine rather than powering down. This can be useful
+ for testing purposes.
--- ../uswsusp.old/debian/control 2007-09-20 07:40:59.000000000 +0100
+++ debian/control 2007-09-23 18:08:41.000000000 +0100
@@ -2,7 +2,7 @@
Section: admin
Priority: optional
Maintainer: Tim Dijkstra <tim@famdijkstra.org>
-Build-Depends: debhelper (>= 5), pciutils-dev, docbook2x, docbook-xml, xsltproc, po-debconf, libgcrypt11-dev, zlib1g-dev, libsplashy1-dev, libx86-dev [amd64 i386], liblzo2-dev
+Build-Depends: debhelper (>= 5), pciutils-dev, docbook2x, docbook-xml, xsltproc, po-debconf, libgcrypt11-dev, zlib1g-dev, libsplashy1-dev, libx86-dev [amd64 i386]
Standards-Version: 3.7.2
Package: uswsusp
@@ -10,18 +10,18 @@
Depends: ${shlibs:Depends}, ${misc:Depends}
Recommends: initramfs-tools (>= 0.74), mount (>= 2.12r-17)
Suggests: splashy (>= 0.3)
-Description: tools to use userspace software suspend provided by Linux
- uswsusp (also known as µswsusp or simply suspend) contains the programs to
- use the userspace software suspend facility available in Linux kernel
- 2.6.17-rc1 and higher. It enables you to save the state of the whole system
- to disk and power off your system. After restarting your system it will be
- put back in the exact system state you left it (this is sometimes called
- hibernation).
+Description: tools to use Linux userspace software suspend
+ This package (also known as μswsusp or simply suspend) contains the
+ programs to use the userspace software suspend facility available in
+ Linux kernels 2.6.17-rc1 and higher. It allows the system to have its
+ state saved to disk and be powered off. On restarting, it will be put
+ back in the state it was left in (this is sometimes called
+ hibernation).
.
- It also includes a program to suspend-to-ram after the state is saved to disk.
- In the suspend-to-ram state the system still uses power, but is faster in
- resuming. In case the battery depletes the state is still on disk and
- resume can continue without data loss.
+ It also includes a program to suspend the system to RAM after the
+ state is saved to disk. In that state, the system still uses power,
+ but resuming is faster. If the battery depletes, the state is resumed
+ from disk without data loss.
.
Optional features include encrypting the system snapshot and a themeable
splash screen during the suspend and resume processes.
Template: uswsusp/resume_device
Type: select
Choices: ${list}
_Description: Swap space to resume from:
To be able to suspend the system, uswsusp needs a swap partition or file
to store a system snapshot. Please choose the device to use, from the
list of suitable swap spaces, sorted by size (largest first).
Template: uswsusp/resume_offset
Type: string
Description: Offset of swap file's header:
When using a swap file for storing the snapshot during suspend, the
location of the swap file's header must be specified. This will be
stored in <PAGE_SIZE> units, as the offset from the beginning of the
partition that contains the swap file.
Template: uswsusp/no_swap
Type: error
_Description: No suitable swap space for software suspend
To be able to suspend the system, uswsusp needs a swap partition or file to
store a system snapshot. No such space seems to be available for this.
.
You should create a swap partition or file, preferably twice the size of
the system's physical RAM.
.
Then, run 'dpkg-reconfigure uswsusp' or edit the configuration file
manually.
Template: uswsusp/no_snapshot
Type: error
_Description: No userspace software suspend support in the kernel
The current kernel doesn't support userspace software suspend. Please
recompile the kernel with the 'CONFIG_SOFTWARE_SUSPEND=y' option.
Template: uswsusp/continue_without_swap
Type: boolean
Default: true
_Description: Continue without a valid swap space?
The swap file or partition that was found in uswsusp's configuration
file is not active.
.
In most cases this means userspace software suspend will
not work as expected. You should choose another swap space.
.
However, in some rare cases, this configuration may be intentional.
Template: uswsusp/snapshot_device
Type: string
_Description: The device node through which uswsusp can talk to the kernel:
If this is empty, the hardcoded default, /dev/snapshot, is used.
This should be OK in almost all cases. Don't change this unless there
is a good reason to do so.
Template: uswsusp/image_size
Type: string
_Description: Preferred maximum image size:
Please specify a maximum system snapshot image size (in bytes).
.
This limit is not strict; uswsusp does its best to respect it, but will
exceed the specified limit if suspend needs a bigger image.
.
Using 0 here will enforce the use of the smallest possible snapshot image.
An empty value will use the hard coded default, which is 500MB. The
default value is 45% of the system's memory: this is not the maximal size,
but some additional free memory speeds up the suspend and resume process.
Template: uswsusp/suspend_loglevel
Type: string
_Description: Log level for software suspend:
Please specify the kernel console log level which the s2disk/s2both
and resume utilities will use to report the progress of suspend and
resume. On a stock kernel, messages with levels higher than 7 are
usually not shown.
Template: uswsusp/max_loglevel
Type: string
_Description: Maximal log level:
Please specify the kernel console log level which the resume utility will use
if the resume fails.
Template: uswsusp/compute_checksum
Type: boolean
Default: false
_Description: Perform checksum on image?
Performing a checksum using the MD5 algorithm to verify the image
integrity is slightly safer, but also takes more time.
Template: uswsusp/compress
Type: boolean
Default: true
_Description: Compress image?
Compressing the image with the LZF compression algorithm will result in a
smaller image, which makes it possible to suspend with a smaller swap
partition. Generally it will also make reading and writing the image faster
because there is less to read and write.
Template: uswsusp/early_writeout
Type: boolean
Default: true
_Description: Perform early write out?
The synchronization of the resume device can start early in the process of
writing the image to it. This has been reported to speed up suspend on some
systems and eliminate the 'fast progress meter and long fsync wait' effect.
Template: uswsusp/splash
Type: boolean
Default: true
_Description: Show splash screen?
Instead of informative output, a splash screen with progress bar can
be shown during the suspend and resume process. This requires the splashy
package to be installed.
Template: uswsusp/encrypt
Type: boolean
Default: false
_Description: Encrypt snapshot?
For increased security, it is possible to encrypt the snapshot
that is written to disk during suspend. On resume (and suspend unless
using an RSA key), you will be prompted for a passphrase. Encryption
adds a significant time to the suspend and resume processes.
Template: uswsusp/RSA_key_file
Type: string
Default: /etc/uswsusp.key
_Description: Path to RSA key file:
To avoid the need for a passphrase prompt during each suspend,
an RSA key can be used to encrypt the image.
.
Please specify the path to that file. Leave this field empty to not
use an RSA key.
Template: uswsusp/create_RSA_key
Type: boolean
Default: false
_Description: Create an RSA key?
The key necessary for using the RSA encryption scheme can be generated now.
You will be prompted for a passphrase.
Template: uswsusp/RSA_key_bits
Type: string
Default: 1024
_Description: RSA key size:
Please specify the size of the RSA key (number of bits between 1024
and 4096). A bigger key increases the encryption strength but slows
down the encryption process.
Template: uswsusp/RSA_passphrase
Type: password
_Description: RSA passphrase:
Please choose the passphrase to use on every resume to decrypt the
image.
Template: uswsusp/RSA_passphrase_v
Type: password
_Description: RSA passphrase confirmation:
Template: uswsusp/shutdown_method
Type: select
__Choices: reboot, platform, poweroff
Default: platform
Description: Shutdown method:
If this parameter is set to 'reboot', the s2disk utility will
reboot the machine rather than powering down. This can be useful
for testing purposes.
Source: uswsusp
Section: admin
Priority: optional
Maintainer: Tim Dijkstra <tim@famdijkstra.org>
Build-Depends: debhelper (>= 5), pciutils-dev, docbook2x, docbook-xml, xsltproc, po-debconf, libgcrypt11-dev, zlib1g-dev, libsplashy1-dev, libx86-dev [amd64 i386]
Standards-Version: 3.7.2
Package: uswsusp
Architecture: i386 amd64 powerpc
Depends: ${shlibs:Depends}, ${misc:Depends}
Recommends: initramfs-tools (>= 0.74), mount (>= 2.12r-17)
Suggests: splashy (>= 0.3)
Description: tools to use Linux userspace software suspend
This package (also known as μswsusp or simply suspend) contains the
programs to use the userspace software suspend facility available in
Linux kernels 2.6.17-rc1 and higher. It allows the system to have its
state saved to disk and be powered off. On restarting, it will be put
back in the state it was left in (this is sometimes called
hibernation).
.
It also includes a program to suspend the system to RAM after the
state is saved to disk. In that state, the system still uses power,
but resuming is faster. If the battery depletes, the state is resumed
from disk without data loss.
.
Optional features include encrypting the system snapshot and a themeable
splash screen during the suspend and resume processes.
.
To use this package you need a Linux kernel version 2.6.17-rc1 or newer
configured to use an initramfs. Hooks and scripts to integrate with
initramfs-tools are provided.
.
Homepage: http://suspend.sourceforge.net/
Reply to: