Standardize manual page encoding

Standardize manual page encoding to either the legacy encoding for a
locale or UTF-8.  Country names should not be included in locale-specific
directory names unless there is a significant difference in language.
Characters in the manual page must be representable in the legacy encoding
for now.

Patch from Colin Watson.  Closes #440420.

git-archimport-id: rra@debian.org--lenny/debian-policy--devel--3.7--patch-31

diff --git a/debian/changelog b/debian/changelog
index 404dd065be5137915243d0677dc68a7b397c9fc3..21a9e5ead87d873d66a309d64771e5ef8f5a24ac 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,5 +1,7 @@
 debian-policy (3.7.4.0) unstable; urgency=low
 
+  * Bug fix: "[AMENDMENT 11/02/2008] Manual page encoding", thanks to
+    Colin Watson                                             (Closes: #440420).
   * Bug fix: "support for wrapped Uploaders should now be mandatory"
                                                              (Closes: #431813).
   * Bug fix: "Examples of dpkg frontends should mention apt now", thanks

diff --git a/policy.sgml b/policy.sgml
index ad4fec319e0a4c9bb98ac7350b2cbf78abe3c4e8..262db3cb406f1c1c4ad29083c3e3d4af90f52edd 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -8519,6 +8519,40 @@ name ["<var>syshostname</var>"]:
              be present in the future.
          </footnote>
        </p>
+
+       <p>
+         Manual pages in locale-specific subdirectories of
+         <file>/usr/share/man</file> should use either UTF-8 or the usual
+         legacy encoding for that language (normally the one corresponding
+         to the shortest relevant locale name in
+         <file>/usr/share/i18n/SUPPORTED</file>). For example, pages under
+         <file>/usr/share/man/fr</file> should use either UTF-8 or
+         ISO-8859-1.<footnote>
+           <prgn>man</prgn> will automatically detect whether UTF-8 is in
+           use. In future, all manual pages will be required to use
+           UTF-8.
+         </footnote>
+       </p>
+
+       <p>
+         A country name (the <tt>DE</tt> in <tt>de_DE</tt>) should not be
+         included in the subdirectory name unless it indicates a
+         significant difference in the language, as this excludes
+         speakers of the language in other countries.<footnote>
+           At the time of writing, Chinese and Portuguese are the main
+           languages with such differences, so <file>pt_BR</file>,
+           <file>zh_CN</file>, and <file>zh_TW</file> are all allowed.
+         </footnote>
+       </p>
+
+       <p>
+         Due to limitations in current implementations, all characters
+         in the manual page source should be representable in the usual
+         legacy encoding for that language, even if the file is
+         actually encoded in UTF-8. Safe alternative ways to write many
+         characters outside that range may be found in
+         <manref name="groff_char" section="7">.
+       </p>
       </sect>
 
       <sect>

diff --git a/upgrading-checklist.html b/upgrading-checklist.html
index 0be5ddcb10a58afa596fa662a6edcd79398f60a7..e3eedd2aab297d93f31ea292bd7eec2582bef952 100644 (file)
--- a/upgrading-checklist.html
+++ b/upgrading-checklist.html
@@ -55,6 +55,13 @@ picking your way through this list.
 <pre>
 3.7.4.0                        unreleased
      * The Uploaders field in debian/control may be wrapped.     [5.6.3]
+     * Manual pages in locale-specific directories should use either the
+       legacy encoding for that directory or UTF-8.  Country names should
+       not be included in locale-specific manual page directories unless
+       indicating a significant difference in the language.  All
+       characters in the manual page source should be representable in the
+       legacy encoding for a locale even if the man page is encoded in
+       UTF-8.                                                    [12.1]
 3.7.3.0                        Dec 2007
      * Package version numbers may contain tildes, which sort before
        anything, even the end of a part.                         [5.6.12]