[Pkg-openldap-devel] Bug#447224: Bug#447224: Bug#447224: openldap2.3: [debconf_rewrite] Debconf templates and debian/control review
Steve Langasek
vorlon at debian.org
Sat Jan 12 00:52:28 UTC 2008
On Tue, Nov 13, 2007 at 05:45:47AM +0000, Christian Perrier wrote:
> OK, then. "Final" templates attached (with Debian branding removed).
> Shall we go for these ones?
> (poor translators...including /me.....:-))
Well, I've finally had an opportunity to sit down with this list of proposed
changes. I'm sorry that I can't say I agree with all of them, but I think
it's a flaw in the process that translations are requested before the
templates have been accepted by the package maintainers, and I don't intend
to accept what I consider regressions in the template language just because
it will avoid frustrating translators.
I do feel guilty about not addressing this in a timely manner - but not so
guilty that I'm willing to set aside my principles as a language curmudgeon.
So, on to the patch.
Template: slapd/no_configuration
Type: boolean
Default: false
_Description: Omit OpenLDAP server configuration?
If you enable this option, no initial configuration or database will be
- created for you.
+ created.
This change upsets me. Debconf templates are *not* an academic paper
written for an abstract audience, they are instructions addressed to an
*individual* user about what will happen on a *specific* machine.
Eliminating the use of second person pronouns is not an improvement to the
UI!
I know that this is something you have strong opinions about, because we've
butted heads on this question before. But those opinions are not
universally held, and I continue to be dismayed that such sanitizing
recommendations are coming out of the Smith Review Project - both because I
do think they impoverish the language of the interface through adherence to
a baseless rule, and because they're changes that needlessly cause (have
caused) more work for translators.
Please don't push your personal usage preferences on the project when they
aren't representative of a consensus.
Template: slapd/dump_database
Type: select
-Choices: always, when needed, never
+__Choices: always, when needed, never
Default: when needed
_Description: Dump databases to file on upgrade:
- Before upgrading to a new version of the OpenLDAP server the data of
- your LDAP directories can be dumped to plain text files (LDIF format)
- which is a standardized description of that data (LDIF stands for
- LDAP Data Interchange Format).
- .
- Selecting "always" will make the maintainer scripts dump your
- databases before upgrading unconditionally. Selecting "when needed"
- will only dump the database if the new version is incompatible with
- the old database format and it has to be reimported. The "never"
- choice will just go ahead without ever dumping your database.
+ Before the upgrade to a new version of the OpenLDAP server, the LDAP
+ directories can be dumped into plain text LDIF files (in the
+ standardized LDAP Data Interchange Format).
+ .
To me, "Before the upgrade to a new version" is awkward. Why are a definite
and indefinite article juxtaposed? This template talks about the behavior
on /each/ upgrade. I believe the original "Before upgrading to a new
version" is better, and don't understand why this was changed.
Nor do I understand why "the data" was trimmed here. "the data from" would
be better than "the data of", but I think omitting it makes it less clear to
a layman what's meant by "dumping" a directory.
Also, parentheticals are inherently evil and should be avoided where
possible, so at least this sentence should IMHO be revised to:
[T]he LDAP directories can be dumped into plain text files in the standard
LDAP Data Interchange Format.
+ Selecting "always" will cause the databases to be dumped
+ unconditionally before an upgrade. Selecting "when needed" will only
+ dump the database if the new version is incompatible with the old
+ database format and it needs to be reimported. Selecting "never" will
+ cause no dump to occur.
I agree that this is an improvement. I think the last sentence should be
improved further:
If you select "never", no dump will be done.
Template: slapd/dump_database_destdir
Type: string
Default: /var/backups/slapd-VERSION
-_Description: Directory to dump databases:
+_Description: Directory for dumped databases:
Hrm. "Directory to use for dumped databases" sounds better to me.
Please specify the directory where the LDAP databases will be exported.
- Within this directory several LDIF files are created which correspond
+ In this directory, several LDIF files will be created which correspond
I'm indifferent to the first change; the second change I agree with.
to the search bases located on the server. Make sure you have enough
- free space on the partition the directory is located. The first
+ free space on the partition where it's located. The first
where it's -> where the directory is. (Looking at the list archives, I
don't think it was Justin's intention to elide "the directory", just to
point out the missing "where"?)
occurrence of the string "VERSION" is replaced with the server version
- you are upgrading from. The default is /var/backups/slapd-VERSION
+ you are upgrading from.
Yes, very important to fix.
Template: slapd/move_old_database
Type: boolean
@@ -44,109 +52,92 @@
Template: slapd/invalid_config
Type: boolean
Default: true
-_Description: Invalid configuration. Retry configuration?
+_Description: Retry configuration?
Improved, yes, but I don't think "retry" is a very good word here to begin
with. I would be inclined to say "Try to configure again?" or "Attempt
configuration again?"
But not a regression in any case.
The configuration you entered is invalid. Make sure that the DNS domain name
- has a valid syntax, the organization is not left empty and that the admin
+ is valid, the organization is not left empty and that the admin
"Valid" can mean many things, and in this case I see at least two possible
interpretations: "is syntactically valid" ("has a valid syntax"), and "is
resolvable". We're asking for the first, I think it would be better to be
explicit.
passwords match. If you decide not to retry the configuration the LDAP server
- will not be set up. Run "dpkg-reconfigure" if you want to retry later.
+ will not be set up. Run 'dpkg-reconfigure slapd' if you want to retry later.
Ack.
Template: slapd/domain
Type: string
_Description: DNS domain name:
- The DNS domain name is used to construct the base DN of your LDAP directory.
- Entering foo.bar.org will give you the base DN dc=foo, dc=bar, dc=org.
+ The DNS domain name is used to construct the base DN of the LDAP directory.
+ For example, 'foo.example.org' will create the directory with
+ 'dc=foo, dc=example, dc=org' as base DN.
Again, pointless rewrite to avoid second-person pronouns.
In this case I don't think the rewritten version is substantially /worse/
than the original, though; so given that it lets us use various updated
translations without further modification, I don't object to the change
(just to the process that spawned it).
Template: shared/organization
Type: string
-_Description: Name of your organization:
- Whatever you enter here will be stored as the name of your organization in
- the base DN of your LDAP directory.
+_Description: Organization:
+ Please enter the name of the organization to use in
+ the base DN of the LDAP directory.
Perhaps "Organization name:" would be better than just "Organization:"?
s/of the LDAP directory/of your LDAP directory/ would also be an
improvement.
Template: slapd/password1
Type: password
-_Description: Admin password:
- Please enter the password for the admin entry in your LDAP directory.
+_Description: Administrator password:
+ Please enter the password for the administrator entry in the LDAP directory.
Hum, this change seems unnecessary to me.
Actually, since the literal rdn that's added to the directory is "cn=admin",
the change to the long description is arguably a regression, since "the
admin entry" == "the entry with common name 'admin'".
Template: slapd/password2
Type: password
_Description: Confirm password:
- Please reenter the admin password for your LDAP directory for
- verification.
I'm lukewarm on this change. I think that debconf questions should stand
alone, and not rely on the context of preceding questions to be understood.
FWIW, this change is inconsistent with the current behavior of the
user-setup-udeb package's password prompts. I don't think it's a good idea
to make such changes to slapd in an ad hoc manner.
Template: slapd/password_mismatch
Type: note
_Description: Password mismatch
- The admin password and its confirmation must match. Please note that
- differences such as uppercase/lowercase and added whitespace matter.
+ The administrator password and its confirmation must match. Please
+ note that differences such as uppercase/lowercase and added
+ whitespace matter.
I would suggest using the text from user-setup-udeb, which in addition to
being well-used, is also widely translated:
The two passwords you entered were not the same. Please try again.
Template: slapd/purge_database
Type: boolean
Default: false
-_Description: Do you want your database to be removed when slapd is purged?
+_Description: Do you want the LDAP database to be removed when purging the package?
Er, over-long short description. The original should be retained.
In fact, the original short description is over-long as well, so:
_Description: Do you want the database to be removed when slapd is purged?
Template: slapd/internal/adminpw
Type: password
-_Description: Encrypted admin password:
+_Description: Encrypted administrator password:
Um, given the title of this template (slapd/internal/adminpw), perhaps we
should go with:
Description: ooga booga don't look at this
;)
I.e., the description doesn't matter, but it should be marked as
not-for-translation since it's never shown to the user.
Template: slapd/allow_ldap_v2
Type: boolean
Default: false
_Description: Allow LDAPv2 protocol?
- The slapd daemon now disables the old LDAPv2 protocol by default.
- Programs and users are generally expected to be upgraded to LDAPv3.
- If you have old programs which have not been moved to use LDAPv3
- and you still need LDAPv2 support then select this option and
- 'allow bind_v2' will be added to your slapd.conf to tell slapd to
- accept LDAPv2 connections.
-
+ The obsolete LDAPv2 protocol is disabled by default in slapd.
+ Programs and users should upgrade to LDAPv3.
+ If some old programs can't use LDAPv3, you should
+ select this option and 'allow bind_v2' will be added to the
+ slapd.conf file.
The first two sentences are an improvement, the rest is another regression
caused by strict avoidance of second-person pronouns.
Template: slapd/suffix_change
Type: boolean
Default: false
-_Description: Move aside current database and create a new one?
- You have specified a directory suffix (domain) that doesn't match the
- one currently in /etc/ldap/slapd.conf. Changing the directory suffix
+_Description: Back up current database and create a new one?
+ The directory suffix (domain) you specified doesn't match the
+ one currently in /etc/ldap/slapd.conf. Changing the directory suffix
requires moving aside the current LDAP database and creating a new
- one. Please confirm whether you want to abandon the current database
- (a backup will be made).
+ one. Please confirm whether you want to back up and abandon the current
+ database.
Ack.
Template: slapd/upgrade_slapcat_failure
-Type: note
-_Description: slapcat failed during upgrade
- An error occurred during the attempt to upgrade your LDAP directory.
- This error occurred when performing the 'slapcat' which attempts to
- extract your LDAP directory. This failure could be because of an
- incorrect config file. For example, if the appropriate moduleload
- lines for your backend database type are missing. This failure
- will cause 'slapadd' later to fail too. The old database files are
- about to be moved to /var/backups. If you want to try this upgrade
- again then move the old database files back into place, fix whatever
+Type: error
+#flag:translate!:5
+#flag:comment:4
+# This paragraph is followed by a (non translatable) paragraph
+# containing a command line
+#flag:comment:6
+# Translators: keep "$location" unchanged. This is a variable that
+# will be replaced by a directory name at execution
+_Description: slapcat failure during upgrade
+ An error occurred during the attempt to upgrade the LDAP directory.
+ .
+ The 'slapcat' program, which attempts to
+ extract the LDAP directory, failed. This may be caused by an
+ incorrect configuration file (for example, missing 'moduleload'
+ lines to support the backend database).
+ .
+ This failure will cause 'slapadd' to later fail. The old database files
+ will be moved to /var/backups. If you want to retry the upgrade, you
+ should move the old database files back into place, fix whatever
caused slapcat to fail, and run:
+ .
slapcat | /usr/share/slapd/fix_ldif -w -o "$organization" > $location
.
Then move the database files back to a backup area and then try running
I've just double-checked that dapper has a version of debconf that supports
"error" templates; so this is ok (better than ok, it's good). Thanks for
going to the effort of adding the appropriate comments here.
I don't understand the rationale for the s/failed/failure/ change, both seem
equally valid to me, making this a gratuitous change that invalidates
pre-existing translations.
Some of the other language still looks a little rough to me; I would
suggest:
An error occurred while upgrading the LDAP directory.
.
The 'slapcat' program failed while extracting the LDAP directory. This may
be caused by an incorrect configuration file (for example, missing
'moduleload' lines to support the backend database).
.
This failure will cause 'slapadd' to fail later as well. The old database
files will be moved to /var/backups. If you want to try this upgrade again,
you should move the old database files back into place, fix whatever caused
slapcat to fail, and run:
@@ -155,68 +146,46 @@
Template: slapd/upgrade_slapadd_failure
Type: note
_Description: slapadd failed during upgrade
- An error occurred during the attempt to upgrade your LDAP directory.
- This error occurred when performing the 'slapadd' which attempts to
- populate an empty new LDAP directory using the information from your
- original LDAP directory. Your original LDAP directory files have
- been saved in /var/backups. The results of the attempted upgrade
- is the ldif file in /var/backups. slapadd may have failed due to
- a configuration problem (in which case slapcat would have failed
- too) or due to a problem in the LDIF file. If the problem was with the
- LDIF file, you may be able to fix it and attempt the slapadd again.
+ An error occurred during the attempt to upgrade the LDAP directory.
+ .
+ The 'slapadd' program, which attempts to
+ populate an empty new LDAP directory using the information from the
+ original LDAP directory, failed. This may be caused by an
+ incorrect configuration file (for example, missing 'moduleload'
+ lines to support the backend database).
+
+ Original LDAP directory files are saved in
+ /var/backups. The result of the attempted upgrade is the LDIF file
+ in /var/backups. The failure may be due to a configuration problem
+ (in which case slapcat would have failed too) or due to a problem in the
+ LDIF file. In such case, you should fix it and run slapadd
+ again.
Same suggestions here.
An error occurred while upgrading the LDAP directory.
.
The 'slapadd' program failed while populating an empty new LDAP directory
using the information from your original LDAP directory.
.
Original LDAP directory files are saved in /var/backups. The result of the
attempted upgrade is the LDIF file in /var/backups. The failure may be due
to a configuration problem (in which case slapcat would have also failed)
or due to a problem i nthe LDIF file. If the problem was with the LDIF
file, you should fix it and run 'dpkg --configure --pending' to attempt the
slapadd again.
... however, this template appears to no longer be used at all in the code,
so I guess we should remove it altogether instead.
Template: slapd/migrate_ldbm_to_bdb
Type: boolean
Default: true
_Description: Change backend type from LDBM to BDB?
- The LDBM backend type has been deprecated in OpenLDAP 2.2 and has shown to not
- work well. BDB is the recommended choice of the OpenLDAP developers.
- .
- When using the BDB backend make sure you configure BDB properly. For
- information to do so, see /usr/share/doc/slapd/README.DB_CONFIG.gz
- .
- If you enable this option an attempt will be made to update your
- configuration to use BDB instead of LDBM and convert your databases.
+ The LDBM backend type has serious stability problems and has been
+ deprecated by OpenLDAP as of 2.2. It is no longer supported by the
+ OpenLDAP packages.
+ .
+ When the BDB backend is used, it must be configured properly. For
+ more information, see /usr/share/doc/slapd/README.DB_CONFIG.gz.
+ .
+ If you enable this option, an attempt will be made to update the
+ configuration to use BDB instead of LDBM and convert the databases.
+ If you do not enable this option, the upgrade will be aborted.
I think s/When the BDB backend is used/To use the BDB backend/ would be
slightly better, but not worth invalidating translations for.
Otherwise, ok (with the usual reservations).
We may want to consider s/BDB/HDB/ throughout this now that HDB is the
backend we're recommending elsewhere, but that's out of scope for the
template changes and may not be worth the effort anyway.
Template: slapd/backend
Type: select
Choices: BDB, HDB
-Default: BDB
+Default: HDB
_Description: Database backend to use:
- The BDB backend is the recommended choice of the OpenLDAP developers.
- When using the BDB backend make sure that you configure the underlying
- database for your requirements.
- Look into /usr/share/doc/slapd/README.DB_CONFIG.gz
- .
- HDB is the next generation of BDB which might replace it sometime in
- the future. There are some problems still in the HDB code of the 2.2
- series of OpenLDAP so you should probably stick to BDB until version 2.3.
- .
- The BDB backend (back-bdb) and LDBM backend (back-ldbm) are comparable in
- purpose and back-bdb evolved from experience gained from back-ldbm, but the
- two are quite distinct today. They both store entries based on a 32-bit entry
- ID key, and they use a dn2id table to map from DNs to entry IDs. They both
- perform attribute indexing using the same code, and store index data as lists
- of entry IDs. As such, the LDAP-specific features they offer are nearly
- identical. The differences are in the APIs used to implement the databases.
- back-ldbm uses a generic database API that can plug into several different
- database packages. In Debian, it's built against BerkeleyDB (BDB). While
- BerkeleyDB supports this generic interface, it also offers a much richer API
- that has a lot more power and a lot more complexity. back-bdb is written
- specifically for the full BDB API, and uses some of BDB's more advanced
- features to offer transaction processing, fine grained locking, and other
- features that offer improved concurrency and reliability. For more
- information, see /usr/share/doc/slapd/README.DB_CONFIG.gz
+ The HDB backend is recommended. HDB and BDB use similar storage formats,
+ but HDB adds support for subtree renames. Both support the same
+ configuration options.
+ .
+ In either case, you should review the resulting database configuration
+ for your needs. See /usr/share/doc/slapd/README.DB_CONFIG.gz for more
+ details.
Yes, a significant improvement.
--- openldap2.3.old/debian/control 2007-09-23 07:19:49.238094433 +0200
+++ openldap2.3/debian/control 2007-10-16 07:05:11.171079113 +0200
@@ -18,10 +18,11 @@
Conflicts: umich-ldapd, ldap-server, libltdl3 (= 1.5.4-1)
Replaces: libldap2, ldap-utils (<< 2.2.23-3)
Provides: ldap-server
-Description: OpenLDAP server (slapd)
- This is the OpenLDAP (Lightweight Directory Access Protocol) standalone
- server (slapd). The server can be used to provide a standalone directory
- service and also includes the slurpd replication server.
+Description: OpenLDAP server - server daemon
Er, multiple redundancies that make no sense, I wonder if this wasn't a bad
merge of the comments on the mailing list.
The original is preferable to this by far.
+ This package provides the OpenLDAP (Lightweight Directory Access
+ Protocol) server (slapd). The server can be used to
+ provide a standalone directory service and also includes the slurpd
+ replication server.
I don't think this is an improvement. "This package" is syntactic fluff
(from context it's clear that it's a package).
Dropping "standalone" is fair.
Hmm, we still mention slurpd, I guess that needs fixed...
Package: ldap-utils
Section: net
@@ -32,10 +33,11 @@
Conflicts: umich-ldap-utils, openldap-utils, ldap-client
Replaces: openldap-utils, slapd (<< 2.2.23-0.pre6), openldapd
Provides: ldap-client, openldap-utils
-Description: OpenLDAP utilities
- Utilities from the OpenLDAP (Lightweight Directory Access Protocol)
- package. These utilities can access a local or remote LDAP server
- and contain all the client programs required to access LDAP servers.
+Description: OpenLDAP server - utilities
What is that supposed to mean? The package contains OpenLDAP utilities,
they aren't "server" utilities. In fact, everything included in this
package is an LDAP client. No, the original description is correct.
+ This package provides utilities from the OpenLDAP (Lightweight
+ Directory Access Protocol) package. These utilities can access a
+ local or remote LDAP server and contain all the client programs
+ required to access LDAP servers.
Fixes the first part of the description to be a grammatically correct
sentence, good.
Package: libldap-2.3-0
Section: libs
@@ -44,28 +46,31 @@
Conflicts: ldap-utils (<= 2.1.23-1)
Depends: ${shlibs:Depends}, libldap2
Replaces: libldap2
-Description: OpenLDAP libraries
- These are the run-time libraries for the OpenLDAP (Lightweight Directory
- Access Protocol) servers and clients.
+Description: OpenLDAP server - libraries
+ This package provides run-time libraries for the OpenLDAP
+ (Lightweight Directory Access Protocol) servers and clients.
Again, not a "server" package.
The original long description is grammatically correct, so again no need
for "This package provides".
Package: libldap-2.3-0-dbg
Section: libdevel
Priority: extra
Architecture: any
Depends: libldap-2.3-0 (= ${binary:Version})
-Description: Debugging information for OpenLDAP libraries
- Detached debugging information for the OpenLDAP (Lightweight Directory
- Access Protocol) libraries. It is useful primarily to permit better
- backtraces and crash dump analysis after problems with the libraries.
- GDB will find this debug information automatically.
+Description: OpenLDAP server - debugging information for libraries
idem.
+ This package provides detached debugging information for the OpenLDAP
+ (Lightweight Directory Access Protocol) libraries. It is useful
+ primarily to permit better backtraces and crash dump analysis after
+ problems with the libraries. GDB will find this debug information
+ automatically.
Grammatically necessary change.
Package: slapd-dbg
Section: net
Priority: extra
Architecture: any
Depends: slapd (= ${binary:Version})
-Description: Debugging information for the OpenLDAP server (slapd)
- Detached debugging information for the OpenLDAP (Lightweight Directory
- Access Protocol) standalone server (slapd). It is useful primarily to
- permit better backtraces and crash dump analysis after problems with the
- libraries. GDB will find this debug information automatically.
+Description: OpenLDAP server - debugging information for the server
"server" is duplicated, again I believe the original is better.
+ This package provides detached debugging information for the OpenLDAP
+ (Lightweight Directory Access Protocol) standalone server (slapd).
+ It is useful primarily to permit better backtraces and crash dump
+ analysis after problems with the libraries. GDB will find this debug
+ information automatically.
Good - though this use of "standalone" inconsistently remains. :)
Attached is my counter-proposal patch. Where I've deemed it reasonable,
I've preserved either your proposed revised text or the original template
from the package, to maximize translation reuse.
Christian, I realize this is a frustrating thing for me to do after you (and
the translators) have already spent as much time on this as you have, but if
you're still willing I would certainly welcome your feedback on these
changes so that we make the package as good as possible.
Thanks,
--
Steve Langasek Give me a lever long enough and a Free OS
Debian Developer to set it on, and I can move the world.
Ubuntu Developer http://www.debian.org/
slangasek at ubuntu.com vorlon at debian.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: openldap-template-revisions.patch
Type: text/x-diff
Size: 15054 bytes
Desc: not available
Url : http://lists.alioth.debian.org/pipermail/pkg-openldap-devel/attachments/20080111/22895953/attachment-0001.patch
More information about the Pkg-openldap-devel
mailing list