From: Russ Allbery <rra@debian.org>
Date: Wed, 5 Mar 2008 02:38:57 +0000 (+0000)
Subject: Standardize manual page encoding
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=f587c402075905e38ffbe5aaabd11aa321c87bc5;p=debian%2Fdebian-policy.git

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 404dd06..21a9e5e 100644
--- 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 ad4fec3..262db3c 100644
--- 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 0be5ddc..e3eedd2 100644
--- 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]