[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

[RFR] templates://zope-common/{templates}



Please find, for review, the debconf templates of zope-common.

This review will last from Wednesday, July 04, 2007 to Saturday, July 14, 2007.

Please send reviews as unified diffs (diff -u) against the original
files. Comments about your proposed changes will be appreciated.

Your review should be sent as an answer to this mail.

When appropriate, I will send intermediate requests for review, with
"[RFRn]" (n>=2) as a subject tag.

When we will reach a consensus, I send a "Last Chance For
Comments" mail with "[LCFC]" as a subject tag.

Finally, the reviewed templates will be sent to the package maintainer
as a bug report, and a mail will be sent to this list with "[BTS]" as
a subject tag.

Rationale:
--- zope-common.old/debian/templates	2007-06-25 20:41:56.553019815 +0200
+++ zope-common/debian/templates	2007-07-03 18:43:13.297162592 +0200
@@ -3,103 +3,99 @@
 _Choices: configuring, end, manually
 Default: end
 _Description: Automatic restart of Zope instances:
- Zope has an extensible, modular structure that allows you to easily
- add extra components (products) or features. Each product or feature
- can usually be found in packages whose name starts with a 'zope-'
- prefix. Unfortunately, each Zope instance needs to be restarted to
- use any new add-on. Here you can choose the default behaviour of
- Zope instances in any installed Zope version when Zope needs to be
- restarted. Each instance, however, is allowed to overwrite this
- setting:
+ Zope offers an extensible, modular structure that allows for an
+ easy addition of extra components (products) or features. Each product or feature
+ is usually provided by packages whose name starts with a 'zope-'
+ prefix. Each Zope instance needs to be restarted to
+ use any new add-on.

Be less verbose.

Avoid personnalization (allows you...)

I drop a few parts that seem IMHO to be less needed such as details
about each instance being able to override this default. We already
say this is a default anyway...:)

  .
-  * configuring: restart instances after each product configuration.
+ Please choose the default behaviour of Zope instances when Zope needs
+ to be restarted:
+ .
+  - configuring: restart instances after each product configuration;
   * end:         restart instances only once at the end of the whole
-                 installation/upgrading process.
-  * manually:    no restart, it is your responsibility to restart
-                 Zope instances.
+                 installation/upgrading process;
+  - manually:    no automated restart.

Consistent bullet use among packages.

Consistent wand typographically correct way to enumerate

Shorten down the list. No need to say "it is your responsibility, bah
blah"....as long as there is no automated restart, that's pretty
obvious.

Shortening down debconf screens is important, especially with select
templates. Otherwise, when both the long description and the choices
do not fit on the screen, with the most common debconf interface
(dialog), the choices are shown separately from the information.

 
 Template: zope-common/remove-instance-without-data
 Type: select
 _Choices: abort, remove and continue
 Default: abort
-_Description: Found an old/incomplete zope instance '${instance}':
- Found an old/incomplete ${instance} instance in
- /var/lib/zope${zver}/instance/${instance}. No data file Data.fs was found
- for the instance, meaning that the installation was not completed
- for some reason, or the installation was incompletely removed.
- Aborting the installation will allow you to inspect the state of the
- instance, continuing will remove /var/lib/zope${zver}/instance/${instance}
- and reinstall the ${instance}. Existing logfiles in
+_Description: Action on old/incomplete zope instance '${instance}':

The short description was not a "prompt". It should really "introduce"
the choice.

Rewriting it is tricky, though.

IMHO, turning this template into a boolean could be better, maybe.

+ An old/incomplete ${instance} instance was found in
+ /var/lib/zope${zver}/instance/${instance}, with no Data.fs file Data.fs.
+ This installation is either incomplete or incompletely removed.
+ .
+ Choosing 'abort' will allow you to inspect the state of the
+ instance.
+ .
+ Choosing 'remove and continue' will remove /var/lib/zope${zver}/instance/${instance}
+ and reinstall ${instance}. Existing logfiles in

Rephrase and separate into paragraphs to make the choice clearer and
detail what are the consequences of each choice.

  /var/log/zope${zver}/${instance} and configuration files in
- /etc/zope${zver}/${instance} are preserved.
+ /etc/zope${zver}/${instance} will be preserved.

I'm not completely sure about the change in tense, here. Maybe
Frenglish influence.

 
 Template: zope-common/keep-data-on-purge
 Type: boolean
 Default: true
 _Description: Keep data for ${instance} on package purge?
- Purging the data files of a zope instance on package purge
- results in loss of all data of the zope instance. The data
- files for this instance are stored in
+ Purging the data files of a Zope instance on package purge
+ results in loss of all data of that instance. These data
+ files are stored in
  /var/lib/zope${zver}/instance/${instance}.

s/zope/Zope

Avoid repetition

 
 Template: zope-common/admin-user
 Type: string
 Default: admin
-_Description: Admin user for zope instance '${instance}':
- Please enter an admin user for the zope instance '${instance}'.
- A valid user name starts with a letter, followed by letters and digits.
- .
- NOTE: Once the instance has been created, the parameter entered
- here isn't relevant anymore.  To change the admin user (and password)
- later on, call:
+_Description: Administrative user for '${instance}' Zope instance:
+ Please enter the login name of the administrative user for the '${instance}' Zope instance .
+ A valid login name starts with a letter, followed by letters and digits.
+ .
+ This will only be used for the instance creation. To later change the
+ administrative user login name and password, please use the following
+ command:
  .
  /var/lib/zope${zver}/instance/${instance}/bin/zopectl adduser <user> <password>

s/admin/administrative: no abbreviation..:-)

We usually replace "user name" by "login name" which is more precise.

I think that "The <foo> Zope instance" is better English than "The
Zope instance <foo>"

Use of "NOTE:", "WARNING:", "ATTENTION:" should be discouraged. All
those texts are notes anyway.

I am unsure about "starts with a letter"...
 
 
 Template: zope-common/admin-password
 Type: password
-_Description: Password for the admin user:
- Please enter a password for the admin user. The password must not be empty.
- The password is deleted from the configuration database, once the
- instance is sucessfully created and cannot be recoverd.
- .
- NOTE: Once the instance has been created, the parameter entered
- here isn't relevant anymore.  To change the admin user (and password)
- later on, call:
+_Description: Password for the administrative user:
+ Please enter a password for the administrative user. The password
+ must not be empty.  The password is deleted from the configuration
+ database, once the instance is sucessfully created and cannot be
+ recoverd.
+ .
+ This will only be used for the instance creation. To later change the
+ administrative user login name and password, please use the following
+ command:
  .
  /var/lib/zope${zver}/instance/${instance}/bin/zopectl adduser <user> <password>

Mostly the same changes than its sister template

 
 Template: zope-common/admin-password-confirmation
 Type: password
-_Description: Same password:
- Please enter again the password for the admin user.
- .
- NOTE: Once the instance has been created, the parameter entered
- here isn't relevant anymore.  To change the admin user (and password)
- later on, call:
- .
- /var/lib/zope${zver}/instance/${instance}/bin/zopectl adduser <user> <password>
+_Description: Password confirmation:
+ Please confirm the administrative user's password.

No need to repeat the verbiage we already used in the previous
template.

The common way to prompt for a password the second time is "Password confirmation:"
 
 Template: zope-common/instance-http-port
 Type: string
 _Description: HTTP port for this instance:
- Please enter the HTTP port for the instance ${instance}.
+ Please enter the HTTP port number for the ${instance} instance.

Same than above: "The <foo> instance" seems better to me.

  .
  Other services (e.g. FTP, WebDAV, debug) will be disabled by default.
- You can enable them editing /etc/zope${zver}/${instance}/zope.conf.
+ They can be enabled by editing /etc/zope${zver}/${instance}/zope.conf.

Slightlmy less personnalisation (OK, this involves passive form).
 
 Template: zope-common/instance-zeo-port
 Type: string
 _Description: TCP port for the ZEO instance:
- Please enter the TCP port for the ZEO instance ${instance}.
+ Please enter the TCP port number for the ${instance} ZEO instance.

Ditto.
 
 Template: zope-common/admin-automatic-password
 Type: note
-_Description: Automatically generated user and password for your instance
- You haven't provided a user and a password for your instance, so these 
- values have been automatically generated.
+_Description: Automatically generated user and password for this instance
+ No administrative user login name and a password were provided for
+ this instance. They have been automatically generated.

Remove personnalization. Again, that means a switch to passive form
unless someone finds a better solution.

  .
- Use these values to log in the Zope${zver} instance ${instance}:
+ Please use the following values to log in the ${instance} Zope${zver} instance:
  .
-  * User     : ${user}
-  * Password : ${password}
+  - User     : ${user}
+  - Password : ${password}




--- zope-common.old/debian/control	2007-06-25 20:41:56.553019815 +0200
+++ zope-common/debian/control	2007-07-03 18:46:24.795277973 +0200
@@ -11,5 +11,5 @@
 Package: zope-common
 Architecture: all
 Depends: adduser, python2.4, ${misc:Depends}
-Description: common settings and scripts for zope installations
- The package contains common settings and scripts for zope installations.
+Description: common settings and scripts for Zope installations
+ This package contains common settings and scripts for Zope installations.

"The" package does not really fit the purpose of a package
description.

s/zope/Zope

-- 




Template: shared/zope/restart
Type: select
_Choices: configuring, end, manually
Default: end
_Description: Automatic restart of Zope instances:
 Zope offers an extensible, modular structure that allows for an
 easy addition of extra components (products) or features. Each product or feature
 is usually provided by packages whose name starts with a 'zope-'
 prefix. Each Zope instance needs to be restarted to
 use any new add-on.
 .
 Please choose the default behaviour of Zope instances when Zope needs
 to be restarted:
 .
  - configuring: restart instances after each product configuration;
  - end:         restart instances only once at the end of the whole
                 installation/upgrading process;
  - manually:    no automated restart.

Template: zope-common/remove-instance-without-data
Type: select
_Choices: abort, remove and continue
Default: abort
_Description: Action on old/incomplete zope instance '${instance}':
 An old/incomplete ${instance} instance was found in
 /var/lib/zope${zver}/instance/${instance}, with no Data.fs file Data.fs.
 This installation is either incomplete or incompletely removed.
 .
 Choosing 'abort' will allow you to inspect the state of the
 instance.
 .
 Choosing 'remove and continue' will remove /var/lib/zope${zver}/instance/${instance}
 and reinstall ${instance}. Existing logfiles in
 /var/log/zope${zver}/${instance} and configuration files in
 /etc/zope${zver}/${instance} will be preserved.

Template: zope-common/keep-data-on-purge
Type: boolean
Default: true
_Description: Keep data for ${instance} on package purge?
 Purging the data files of a Zope instance on package purge
 results in loss of all data of that instance. These data
 files are stored in
 /var/lib/zope${zver}/instance/${instance}.

Template: zope-common/admin-user
Type: string
Default: admin
_Description: Administrative user for '${instance}' Zope instance:
 Please enter the login name of the administrative user for the '${instance}' Zope instance .
 A valid login name starts with a letter, followed by letters and digits.
 .
 This will only be used for the instance creation. To later change the
 administrative user login name and password, please use the following
 command:
 .
 /var/lib/zope${zver}/instance/${instance}/bin/zopectl adduser <user> <password>


Template: zope-common/admin-password
Type: password
_Description: Password for the administrative user:
 Please enter a password for the administrative user. The password
 must not be empty.  The password is deleted from the configuration
 database, once the instance is sucessfully created and cannot be
 recoverd.
 .
 This will only be used for the instance creation. To later change the
 administrative user login name and password, please use the following
 command:
 .
 /var/lib/zope${zver}/instance/${instance}/bin/zopectl adduser <user> <password>

Template: zope-common/admin-password-confirmation
Type: password
_Description: Password confirmation:
 Please confirm the administrative user's password.

Template: zope-common/instance-http-port
Type: string
_Description: HTTP port for this instance:
 Please enter the HTTP port number for the ${instance} instance.
 .
 Other services (e.g. FTP, WebDAV, debug) will be disabled by default.
 They can be enabled by editing /etc/zope${zver}/${instance}/zope.conf.

Template: zope-common/instance-zeo-port
Type: string
_Description: TCP port for the ZEO instance:
 Please enter the TCP port number for the ${instance} ZEO instance.

Template: zope-common/admin-automatic-password
Type: note
_Description: Automatically generated user and password for this instance
 No administrative user login name and a password were provided for
 this instance. They have been automatically generated.
 .
 Please use the following values to log in the ${instance} Zope${zver}
 instance:
 .
  - User     : ${user}
  - Password : ${password}
--- ../zope-common.old/debian/templates	2007-06-25 20:41:56.553019815 +0200
+++ debian/templates	2007-07-04 07:08:29.643352525 +0200
@@ -3,103 +3,100 @@
 _Choices: configuring, end, manually
 Default: end
 _Description: Automatic restart of Zope instances:
- Zope has an extensible, modular structure that allows you to easily
- add extra components (products) or features. Each product or feature
- can usually be found in packages whose name starts with a 'zope-'
- prefix. Unfortunately, each Zope instance needs to be restarted to
- use any new add-on. Here you can choose the default behaviour of
- Zope instances in any installed Zope version when Zope needs to be
- restarted. Each instance, however, is allowed to overwrite this
- setting:
- .
-  * configuring: restart instances after each product configuration.
-  * end:         restart instances only once at the end of the whole
-                 installation/upgrading process.
-  * manually:    no restart, it is your responsibility to restart
-                 Zope instances.
+ Zope offers an extensible, modular structure that allows for an
+ easy addition of extra components (products) or features. Each product or feature
+ is usually provided by packages whose name starts with a 'zope-'
+ prefix. Each Zope instance needs to be restarted to
+ use any new add-on.
+ .
+ Please choose the default behaviour of Zope instances when Zope needs
+ to be restarted:
+ .
+  - configuring: restart instances after each product configuration;
+  - end:         restart instances only once at the end of the whole
+                 installation/upgrading process;
+  - manually:    no automated restart.
 
 Template: zope-common/remove-instance-without-data
 Type: select
 _Choices: abort, remove and continue
 Default: abort
-_Description: Found an old/incomplete zope instance '${instance}':
- Found an old/incomplete ${instance} instance in
- /var/lib/zope${zver}/instance/${instance}. No data file Data.fs was found
- for the instance, meaning that the installation was not completed
- for some reason, or the installation was incompletely removed.
- Aborting the installation will allow you to inspect the state of the
- instance, continuing will remove /var/lib/zope${zver}/instance/${instance}
- and reinstall the ${instance}. Existing logfiles in
+_Description: Action on old/incomplete zope instance '${instance}':
+ An old/incomplete ${instance} instance was found in
+ /var/lib/zope${zver}/instance/${instance}, with no Data.fs file Data.fs.
+ This installation is either incomplete or incompletely removed.
+ .
+ Choosing 'abort' will allow you to inspect the state of the
+ instance.
+ .
+ Choosing 'remove and continue' will remove /var/lib/zope${zver}/instance/${instance}
+ and reinstall ${instance}. Existing logfiles in
  /var/log/zope${zver}/${instance} and configuration files in
- /etc/zope${zver}/${instance} are preserved.
+ /etc/zope${zver}/${instance} will be preserved.
 
 Template: zope-common/keep-data-on-purge
 Type: boolean
 Default: true
 _Description: Keep data for ${instance} on package purge?
- Purging the data files of a zope instance on package purge
- results in loss of all data of the zope instance. The data
- files for this instance are stored in
+ Purging the data files of a Zope instance on package purge
+ results in loss of all data of that instance. These data
+ files are stored in
  /var/lib/zope${zver}/instance/${instance}.
 
 Template: zope-common/admin-user
 Type: string
 Default: admin
-_Description: Admin user for zope instance '${instance}':
- Please enter an admin user for the zope instance '${instance}'.
- A valid user name starts with a letter, followed by letters and digits.
- .
- NOTE: Once the instance has been created, the parameter entered
- here isn't relevant anymore.  To change the admin user (and password)
- later on, call:
+_Description: Administrative user for '${instance}' Zope instance:
+ Please enter the login name of the administrative user for the '${instance}' Zope instance .
+ A valid login name starts with a letter, followed by letters and digits.
+ .
+ This will only be used for the instance creation. To later change the
+ administrative user login name and password, please use the following
+ command:
  .
  /var/lib/zope${zver}/instance/${instance}/bin/zopectl adduser <user> <password>
 
 
 Template: zope-common/admin-password
 Type: password
-_Description: Password for the admin user:
- Please enter a password for the admin user. The password must not be empty.
- The password is deleted from the configuration database, once the
- instance is sucessfully created and cannot be recoverd.
- .
- NOTE: Once the instance has been created, the parameter entered
- here isn't relevant anymore.  To change the admin user (and password)
- later on, call:
+_Description: Password for the administrative user:
+ Please enter a password for the administrative user. The password
+ must not be empty.  The password is deleted from the configuration
+ database, once the instance is sucessfully created and cannot be
+ recoverd.
+ .
+ This will only be used for the instance creation. To later change the
+ administrative user login name and password, please use the following
+ command:
  .
  /var/lib/zope${zver}/instance/${instance}/bin/zopectl adduser <user> <password>
 
 Template: zope-common/admin-password-confirmation
 Type: password
-_Description: Same password:
- Please enter again the password for the admin user.
- .
- NOTE: Once the instance has been created, the parameter entered
- here isn't relevant anymore.  To change the admin user (and password)
- later on, call:
- .
- /var/lib/zope${zver}/instance/${instance}/bin/zopectl adduser <user> <password>
+_Description: Password confirmation:
+ Please confirm the administrative user's password.
 
 Template: zope-common/instance-http-port
 Type: string
 _Description: HTTP port for this instance:
- Please enter the HTTP port for the instance ${instance}.
+ Please enter the HTTP port number for the ${instance} instance.
  .
  Other services (e.g. FTP, WebDAV, debug) will be disabled by default.
- You can enable them editing /etc/zope${zver}/${instance}/zope.conf.
+ They can be enabled by editing /etc/zope${zver}/${instance}/zope.conf.
 
 Template: zope-common/instance-zeo-port
 Type: string
 _Description: TCP port for the ZEO instance:
- Please enter the TCP port for the ZEO instance ${instance}.
+ Please enter the TCP port number for the ${instance} ZEO instance.
 
 Template: zope-common/admin-automatic-password
 Type: note
-_Description: Automatically generated user and password for your instance
- You haven't provided a user and a password for your instance, so these 
- values have been automatically generated.
+_Description: Automatically generated user and password for this instance
+ No administrative user login name and a password were provided for
+ this instance. They have been automatically generated.
  .
- Use these values to log in the Zope${zver} instance ${instance}:
+ Please use the following values to log in the ${instance} Zope${zver}
+ instance:
  .
-  * User     : ${user}
-  * Password : ${password}
+  - User     : ${user}
+  - Password : ${password}
--- ../zope-common.old/debian/control	2007-06-25 20:41:56.553019815 +0200
+++ debian/control	2007-07-03 18:46:24.795277973 +0200
@@ -11,5 +11,5 @@
 Package: zope-common
 Architecture: all
 Depends: adduser, python2.4, ${misc:Depends}
-Description: common settings and scripts for zope installations
- The package contains common settings and scripts for zope installations.
+Description: common settings and scripts for Zope installations
+ This package contains common settings and scripts for Zope installations.
Source: zope-common
Section: web
Priority: optional
Maintainer: Debian/Ubuntu Zope Team <pkg-zope-developers@lists.alioth.debian.org>
Uploaders: Fabio Tranchitella <kobold@debian.org>, Andrea Mennucci <mennucc1@debian.org>, martin f. krafft <madduck@debian.org>, Matthias Klose <doko@debian.org>, Jonas Meurer <mejo@debian.org>, Bernd Zeimetz <bernd@bzed.de>
Build-Depends: debhelper (>= 5.0.0), po-debconf, lsb-release
Build-Depends-Indep: docbook-to-man
Standards-Version: 3.7.2
XS-Vcs-Svn: svn://svn.debian.org/pkg-zope/zope-common/trunk

Package: zope-common
Architecture: all
Depends: adduser, python2.4, ${misc:Depends}
Description: common settings and scripts for Zope installations
 This package contains common settings and scripts for Zope installations.

Attachment: signature.asc
Description: Digital signature


Reply to: