Re: DEBIAN POLICY WEEKLY, #4 (October 23, 1997)

["Oliver Elphick" <olly@lfix.co.uk>]

Christian Schwarz wrote:
  >
  >DEBIAN POLICY WEEKLY, #4 (October 23, 1997)
  >...
  >Topic 10: Filesystem location of non-english documentation files
  >...
  >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>
  >

I think this should be /usr/doc/LANG_<locale>/<pkg>.

The reason is, to make things more convenient for users of the documentation.
Someone who reads documentation in some language other than English is likely
to want to read all possible documentation in that language.  Therefore it will
be very inconvenient for them to have to negotiate an extra LANG_<locale> sub-
directory for every package, and more complicated for writers of documentation
browsers, such as dwww. (Not that I know whether dwww knows about locales.)

For consistency, the default location ought to be LANG_C so that the hierarchy
is properly balanced; then dwww can choose the hierarchy on the basis of the
current user's locale, and present default documentation if there is none for
the current user's 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.

Perhaps we should be more directive about this.  The main reason I can think
of for having documentation differentiated by locale is language.  It would be
rather excessive for me to demand separate British documentation with proper
spelling, so I think we should reduce the choice to language alone, _unless_
there is a compelling reason to distinguish by territory as well.  The only
example I can think of at the moment is an accounting package handling the tax
rules of different countries.

  >
  >The LANG_ prefix is used to reduce the possibility of a file name conflict.

This would not occur if you accept my suggestion. However, I think it would be
a good thing to keep the prefix, in case extraneous rubbish ends up in /usr/doc
by accident.

  >(I don't think an extra LANG/ directory is appropriate here.)

I agree.

  >
  >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>/
  >

This would then become:

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

I believe these suggestions would make the hierarchy easier to understand and 
tidier to handle.

-- 
Oliver Elphick                                Oliver.Elphick@lfix.co.uk
Isle of Wight                                  http://lfix.co.uk/oliver

PGP key from public servers; key ID 32B8FAA1




--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-request@lists.debian.org . 
Trouble?  e-mail to templin@bucknell.edu .