Policy Weekly Issue #4/10: Filesystem location of non-english documentation files

[Christian Schwarz <schwarz@monet.m.isar.de>]

Topic 10: Filesystem location of non-english documentation files

STATE: INPUT

Background

There was a discussion about this topic on debian-devel around Nov 96, but
without any decision. Since a lot of package already install non-english
docs, we'll have to find a solution soon. 

The previous discussion on this topic made clear, that we still have two
groups of people, one that prefers having the files in
/usr/doc/LANG/<locale> and symlinks in /usr/doc/<pkg>, and one that
prefers having the files in /usr/doc/<pkg>/<locale>. 

In the past, the policy about doc files has been changed: We used to split
up the doc files into different directories (/usr/doc/copyright,
/usr/doc/examples, /usr/doc/<pkg>, etc.). Now we place all package-related
documentation files below /usr/doc/<pkg>. 

Policy suggestion

In continuation of this policy I suggest to keep all documentation files
in one place: /usr/doc/<pkg>. In case of non-english docs, the files would
be placed into a subdirectory /usr/doc/<pkg>/LANG_<locale>

The locale string can have the form <language> or <language>_<territory>. 
It is the maintainers job to decide which form to be used for a specific
documentation file. 

The LANG_ prefix is used to reduce the possibility of a file name
conflict.  (I don't think an extra LANG/ directory is appropriate here.) 

Any program/script that needs to access documentation files mechanically
should search for the files in the following directories (in exactly this
order): 

     /usr/doc/<pkg>/LANG_<language>_<territory>/
     /usr/doc/<pkg>/LANG_<language>/
     /usr/doc/<pkg>/

Some people suggested to have an extra directory level for the
documentation file format (e.g. 'HTML/'). I suggest to postpone the
discussion about this sub-topic until we discuss the `documentation
policy'. (Until then, maintainers can decide whether they want to use an
extra directory, or not.) 

Feedback

Please tell me what you think about this suggestion. If people agree with
my proposal, I'll prepare the necessary policy changes and present them
here for approval. 

----------------------------------------------------------------------------

--          _,,     Christian Schwarz
           / o \__   schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
           !   ___;   schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
           \  /        
  \\\______/  !        PGP-fp: 8F 61 EB 6D CF 23 CA D7  34 05 14 5C C8 DC 22 BA
   \          /         http://fatman.mathematik.tu-muenchen.de/~schwarz/
-.-.,---,-,-..---,-,-.,----.-.-
  "DIE ENTE BLEIBT DRAUSSEN!"