From: he Date: Sun, 1 Jun 2008 15:47:07 +0000 (+0000) Subject: Fix several typesetting errors and typos noticed by Sandro Tosi, X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=9c55352f61aeb85e523b2f2347b43533f7aeb1f7;p=developers-reference.git Fix several typesetting errors and typos noticed by Sandro Tosi, thanks for the notes! Closes: #483223 git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@5199 313b444b-1b9f-4f58-a734-7bb04f332e8d --- diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk index e91c78d..43cf469 100644 --- a/best-pkging-practices.dbk +++ b/best-pkging-practices.dbk @@ -34,7 +34,7 @@ usually the file maintainers spend the most time on. The rationale for using helper scripts in debian/rules is that they let maintainers use and share common logic among many packages. Take for instance the question of installing menu entries: you need to put the file -into /usr/lib/menu (or /usr/lib/menu +into /usr/share/menu (or /usr/lib/menu for executable binary menufiles, if this is needed), and add commands to the maintainer scripts to register and unregister the menu entries. Since this is a very common thing for packages to do, why should each maintainer rewrite all @@ -548,21 +548,24 @@ inserting the title of each different bug.
Supplementing changelogs with NEWS.Debian files -Important news about changes in a package can also be put in NEWS.Debian files. +Important news about changes in a package can also be put in +NEWS.Debian files. The news will be displayed by tools like apt-listchanges, before all the rest of the changelogs. This is the preferred means to let the user know about significant changes in a package. It is better than using debconf notes since -it is less annoying and the user can go back and refer to the NEWS.Debian file -after the install. And it's better than listing major changes in -README.Debian, since the user can easily miss such notes. +it is less annoying and the user can go back and refer to the +NEWS.Debian file after the install. And it's better than listing +major changes in README.Debian, since the user can easily +miss such notes. The file format is the same as a debian changelog file, but leave off the asterisks and describe each news item with a full paragraph when necessary rather than the more concise summaries that would go in a changelog. It's a -good idea to run your file through dpkg-parsechangelog to check its formatting -as it will not be automatically checked during build as the changelog is. Here -is an example of a real NEWS.Debian file: +good idea to run your file through dpkg-parsechangelog to +check its formatting as it will not be automatically checked during build as +the changelog is. Here is an example of a real NEWS.Debian + file: cron (3.0pl1-74) unstable; urgency=low @@ -575,16 +578,18 @@ cron (3.0pl1-74) unstable; urgency=low -- Steve Greenland <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 -0500 -The NEWS.Debian file is installed as -/usr/share/doc/<package>/NEWS.Debian.gz. It is compressed, and always -has that name even in Debian native packages. If you use debhelper, -dh_installchangelogs will install debian/NEWS files for you. +The NEWS.Debian file is installed as +/usr/share/doc/package/NEWS.Debian.gz. +It is compressed, and always has that name even in Debian native packages. +If you use debhelper, dh_installchangelogs + will install debian/NEWS files for you. -Unlike changelog files, you need not update NEWS.Debian files with every -release. Only update them if you have something particularly newsworthy that -user should know about. If you have no news at all, there's no need to ship a -NEWS.Debian file in your package. No news is good news! +Unlike changelog files, you need not update NEWS.Debian +files with every release. Only update them if you have something particularly +newsworthy that user should know about. If you have no news at all, there's no +need to ship a NEWS.Debian file in your package. No news +is good news!
@@ -746,7 +751,7 @@ translated by translation teams or even individuals. Please use gettext-based templates. Install po-debconf on your development system and read its -documentation (man po-debconf is a good start). +documentation (man po-debconf is a good start). Avoid changing templates too often. Changing templates text induces more work @@ -758,9 +763,9 @@ templates, the translator's name and e-mail addresses are mentioned in the po files headers. -The use of the podebconf-report-po from the po-debconf -package is highly recommended to warn translators which have incomplete -translations and request them for updates. +The use of the podebconf-report-po from the po-debconf package is highly recommended to warn +translators which have incomplete translations and request them for updates. If in doubt, you may also contact the translation team for a given language @@ -1485,8 +1490,9 @@ sections, to hunt down unused libraries. But when passed the right argument, it tries to catch other useless packages. -For example, with --guess-dummy, deborphan tries to search all transitional -packages which were needed for upgrade but which can now safely be removed. +For example, with --guess-dummy, deborphan +tries to search all transitional packages which were needed for upgrade but +which can now safely be removed. For that, it looks for the string dummy or transitional in their short description. @@ -1508,7 +1514,7 @@ upstream source. Pristine source The defining characteristic of a pristine source tarball is that the -.orig.tar.gz file is byte-for-byte identical to a tarball officially +.orig.tar.gz file is byte-for-byte identical to a tarball officially distributed by the upstream author. We cannot prevent upstream authors from changing the tarball they distribute without also incrementing the version number, so there can be no guarantee that a pristine @@ -1517,8 +1523,8 @@ distributing at any point in time. All that can be expected is that it is identical to something that upstream once did distribute. If a difference arises later (say, if upstream notices that he wasn't using maximal comression in his original distribution and then -re-gzips it), that's just too bad. Since there is no good -way to upload a new .orig.tar.gz for the same version, there is not even any +re-gzips it), that's just too bad. Since there is no good +way to upload a new .orig.tar.gz for the same version, there is not even any point in treating this situation as a bug. This makes it possible to use checksums to easily verify that all changes between Debian's version and upstream's are contained in the Debian diff. Also, if the original @@ -1572,12 +1578,12 @@ gzipped tar at all, or if upstream's tarball contains non-DFSG-free material that you must remove before uploading. -In these cases the developer must construct a suitable .orig.tar.gz file -himself. We refer to such a tarball as a repackaged upstream source. Note -that a repackaged upstream source is different from a Debian-native package. A -repackaged source still comes with Debian-specific changes in a separate -.diff.gz and still has a version number composed of -<upstream-version> and +In these cases the developer must construct a suitable .orig.tar.gz + file himself. We refer to such a tarball as a repackaged upstream +source. Note that a repackaged upstream source is different from a +Debian-native package. A repackaged source still comes with Debian-specific +changes in a separate .diff.gz and still has a version +number composed of <upstream-version> and <debian-revision>. @@ -1590,7 +1596,7 @@ archive. Use your own discretion here, but be prepared to defend your decision if you repackage source that could have been pristine. -A repackaged .orig.tar.gz +A repackaged .orig.tar.gz @@ -1724,18 +1730,19 @@ example, debugging symbols for /usr/bin/foo go in /usr/lib/debug/usr/lib/libfoo.so.1. -The debugging symbols can be extracted from an object file using objcopy ---only-keep-debug. Then the object file can be stripped, and objcopy ---add-gnu-debuglink used to specify the path to the debugging symbol file. +The debugging symbols can be extracted from an object file using +objcopy --only-keep-debug. Then the object file can be stripped, +and objcopy --add-gnu-debuglink used to specify the path +to the debugging symbol file. objcopy 1 explains in detail how this works. -The dh_strip command in debhelper supports creating debug packages, and can -take care of using objcopy to separate out the debugging symbols for you. If -your package uses debhelper, all you need to do is call dh_strip ---dbg-package=libfoo-dbg, and add an entry to debian/control for the debug -package. +The dh_strip command in debhelper supports creating debug +packages, and can take care of using objcopy to separate +out the debugging symbols for you. If your package uses debhelper, all you +need to do is call dh_strip --dbg-package=libfoo-dbg, and +add an entry to debian/control for the debug package. Note that the Debian package should depend on the package that it provides diff --git a/beyond-pkging.dbk b/beyond-pkging.dbk index 0d27668..77a9739 100644 --- a/beyond-pkging.dbk +++ b/beyond-pkging.dbk @@ -124,8 +124,8 @@ many problems as possible. They are announced on &email-debian-devel-announce; and the announcement explains which area will be the focus of the party: usually they focus on release critical bugs but it may happen that they decide to help finish a major upgrade -(like a new perl version which requires recompilation of all the binary -modules). +(like a new perl version which requires recompilation of all +the binary modules). The rules for non-maintainer uploads differ during the parties because the @@ -190,11 +190,11 @@ There is a simple system (the MIA database) in which information about maintainers who are deemed Missing In Action is recorded. When a member of the QA group contacts an inactive maintainer or finds more information about one, this is recorded in the MIA database. This system is available in -/org/qa.debian.org/mia on the host qa.debian.org, and can be queried with a -tool known as mia-query. Use mia-query --help -to see how to query the database. If you find that no information has been -recorded about an inactive maintainer yet, or that you can add more -information, you should generally proceed as follows. +/org/qa.debian.org/mia on the host qa.debian.org +, and can be queried with the mia-query tool. +Use mia-query --help to see how to query the database. +If you find that no information has been recorded about an inactive maintainer yet, +or that you can add more information, you should generally proceed as follows. The first step is to politely contact the maintainer, and wait a reasonable @@ -211,11 +211,12 @@ maintainer in question as possible. This includes: -The echelon information available through the echelon information available through the developers' LDAP database, which indicates when the developer last posted to a Debian mailing list. (This includes -uploads via debian-*-changes lists.) Also, remember to check whether the -maintainer is marked as on vacation in the database. +mails about uploads distributed via the &email-debian-devel-changes; list.) +Also, remember to check whether the maintainer is marked as on vacation in +the database. @@ -237,11 +238,11 @@ groups. A bit of a problem are packages which were sponsored — the maintainer is not -an official Debian developer. The echelon information is not available for -sponsored people, for example, so you need to find and contact the Debian -developer who has actually uploaded the package. Given that they signed the -package, they're responsible for the upload anyhow, and are likely to know what -happened to the person they sponsored. +an official Debian developer. The echelon information is not +available for sponsored people, for example, so you need to find and contact the +Debian developer who has actually uploaded the package. Given that they signed +the package, they're responsible for the upload anyhow, and are likely to know +what happened to the person they sponsored. It is also allowed to post a query to &email-debian-devel;, @@ -272,9 +273,9 @@ someone with more time. If you are interested in working in the MIA team, please have a look at the -README file in /org/qa.debian.org/mia on qa.debian.org where the technical -details and the MIA procedures are documented and contact -&email-mia;. +README file in /org/qa.debian.org/mia on +qa.debian.org where the technical details and the MIA procedures are +documented and contact &email-mia;. diff --git a/debian/changelog b/debian/changelog index 929fc65..fa8d821 100644 --- a/debian/changelog +++ b/debian/changelog @@ -19,6 +19,8 @@ developers-reference (3.4.0) UNRELEASED; urgency=low release codenames in * Remove reference to upload queue on auric in section 5.6.5, auric doesn't exist anymore. + * Fix several typesetting errors and typos noticed by Sandro Tosi, + thanks for the notes! Closes: #483223 -- Marc 'HE' Brockschmidt Sun, 01 Jun 2008 16:26:33 +0200 diff --git a/l10n.dbk b/l10n.dbk index c3c7f56..92bf3b9 100644 --- a/l10n.dbk +++ b/l10n.dbk @@ -18,7 +18,7 @@ According to Introduction to i18n from Tomohiro KUBOTA, I18N (internationalization) means modification of a software or related technologies so that a software can -potentially handle multiple languages, customs, and so on in the world. while +potentially handle multiple languages, customs, and so on in the world, while L10N (localization) means implementation of a specific language for an already internationalized software. @@ -33,7 +33,7 @@ character encodings is a really hard problem. Setting aside the i18n problems, where no general guideline can be given, there is actually no central infrastructure for l10n within Debian which could be -compared to the dbuild mechanism for porting. So most of the work has to be +compared to the buildd mechanism for porting. So most of the work has to be done manually.
diff --git a/pkgs.dbk b/pkgs.dbk index 38ab0dd..1f35c35 100644 --- a/pkgs.dbk +++ b/pkgs.dbk @@ -72,7 +72,7 @@ already is a volunteer, so efforts may be shared. It lets the rest of the maintainers know more about the package than the one line description and the usual changelog entry ``Initial release'' that gets -posted to debian-devel-changes. +posted to &email-debian-devel-changes;. @@ -436,8 +436,9 @@ see section .
Other upload queues -The scp queues on &ftp-master-host;, and security are mostly -unusable due to the login restrictions on those hosts. +The scp queues on &ftp-master-host;, and +security.debian.org are mostly unusable due to the login restrictions +on those hosts. The anonymous queues on ftp.uni-erlangen.de and ftp.uk.debian.org are currently @@ -805,7 +806,7 @@ Due to their sensitive nature, security-related bugs must be handled carefully. The Debian Security Team exists to coordinate this activity, keeping track of outstanding security problems, helping maintainers with security problems or fixing them themselves, sending security advisories, and maintaining -security.debian.org. +security.debian.org. @@ -1104,11 +1105,12 @@ uploads as well. -Unless the upstream source has been uploaded to security.debian.org before (by -a previous security update), build the upload with full upstream source -(dpkg-buildpackage -sa). If there has been a previous -upload to security.debian.org with the same upstream version, you may upload -without upstream source (dpkg-buildpackage -sd). +Unless the upstream source has been uploaded to security.debian.org + before (by a previous security update), build the upload with full +upstream source (dpkg-buildpackage -sa). If there has been +a previous upload to security.debian.org with the same +upstream version, you may upload without upstream source ( +dpkg-buildpackage -sd). @@ -1140,9 +1142,10 @@ package does not exactly meet the team's requirements, it will cause many problems and delays in dealing with the unwanted upload. -Do NOT upload your fix to proposed-updates -without coordinating with the security team. Packages from security.debian.org -will be copied into the proposed-updates directory automatically. If a package +Do NOT upload your fix to +proposed-updates without coordinating with the security team. +Packages from security.debian.org will be copied into +the proposed-updates directory automatically. If a package with the same or a higher version number is already installed into the archive, the security update will be rejected by the archive system. That way, the stable distribution will end up without a security update for this package @@ -1166,7 +1169,7 @@ problems that cannot be disclosed yet. If a member of the security team accepts a package, it will be installed on -security.debian.org as well as proposed for the proper +security.debian.org as well as proposed for the proper distribution-proposed-updates on &ftp-master-host;. @@ -1702,7 +1705,7 @@ also enable Debian to recompile entire distributions quickly. The buildds admins of each arch can be contacted at the mail address -$arch@buildd.debian.org. +arch@buildd.debian.org.
@@ -2275,9 +2278,9 @@ shows build dependencies which are not considered by britney. For the testing migration script, outdated means: There are different versions in unstable for the release architectures (except for the architectures in fuckedarches; fuckedarches is a list of -architectures that don't keep up (in update_out.py), but currently, it's -empty). outdated has nothing whatsoever to do with the architectures this -package has in testing. +architectures that don't keep up (in update_out.py), but +currently, it's empty). outdated has nothing whatsoever to do with the +architectures this package has in testing. Consider this example: @@ -2622,7 +2625,7 @@ is normally required. If you are having problems with complicated groups of packages like this, -contact debian-devel or debian-release for help. +contact &email-debian-devel; or &email-debian-release; for help.