Re: Policy Weekly Issue #4/10: Filesystem location of non-english documentation files
For semplicity, I've moved the "conclusion" of my proposal on top of
this message. Rationale discussion follows below.
* distinguish between docs "about" a package and docs that "are" the
package.
* for "docs-about-the-package" use Schwarz's proposal:
/usr/doc/<pkg>/LANG_<language>_<territory>/
or /usr/doc/<pkg>/LANG_<language>/
or /usr/doc/<pkg>/
* for "docs-that-are-the-package" I suggest using:
/usr/doc/<doc-name>/<lang>/<format>/<type>/...
This need policy or at least cooperation between involved maintainers.
Rationale:
Christian Schwarz wrote:
>
> 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>.
If I remember well, that discussion was about some particular docs, and
not for the general things we put in /usr/doc/<pkg> .
In fact, I think we should distinguish on the "docs-about-the-package"
that _must_ reside in /ust/doc/<pkg> and "docs-that-are-the-package"
that installs in a "for-purpose" /usr/doc/<name> directory, like HOWTOs
do.
For "docs-about-the-package" I think that your proposal is optimal:
> /usr/doc/<pkg>/LANG_<language>_<territory>/
> /usr/doc/<pkg>/LANG_<language>/
> /usr/doc/<pkg>/
In case of "docs-about-the-package" there's no need for
/usr/doc/LANG/<locale>/<pkg> hierarchy or symlink.
But when the package installs a huge amount of docs, or when the main
purpose of the package is to only install docs, maybe splitted in more
than one package, then we should consider a different structure.
For example, we have several packages that installs HOWTOs (as well that
debian-manuals, RFCs, etc.); each package should install the
/usr/doc/<pkg> as usual with its copyright, changelog and debian.readme
(as well as other files, with their proper names :-), descriptions and
example, as well as their translations using the above scheme.
All packages that installs docs related between them should agree on a
<doc-name> to be used to build the hierarchy /usr/doc/<doc-name> to
carry the docs, and all should use the same structure for the hierarchy,
set by policy.
HOWTOs actually follow this one (although maybe recently this has
changed, but I don't know how, at the moment):
doc-linux uses "HOWTO" as <doc-name> and make his hierarchy in
/usr/doc/HOWTO
doc-linux-<lang> uses "LANG/<lang>/HOWTO" as <doc-name> and puts files
in /usr/doc/LANG/<lang>/HOWTO plus a symlink pointing from
/usr/doc/HOWTO/<lang> to his own hierarchy.
This was due to the fact that each package should have full control on
the dirs he creates under /usr/doc .
I suggest that all those packages use a common <doc-name> to put under
/usr/doc (could be "linux" for HOWTOs and FAQs, "debian" for all debian
manuals, "something-else" for RFCs, USENET-archives, etc.), and the
hierarchy divided in <lang>/<format>:
/usr/doc/linux/<lang>/<format>/<type>
where <lang> includes en for english, <format> are "html", "text", "ps",
"sgml" where appropriate, and <type> are particular for each group of
package: "HOWTO", "FAQ", "mini-howto" for "linux", "policy",
"developer", "user" for "debian", etc.
<type> names, as well as <doc-names> are choosen collectively by
maintainers of those packages, maybe after discussion on some list.
Then each package installs each singular file in its proper place, in a
way similar to that we already do for manpages.
So, for example, we could have:
/usr/doc/debian/
/usr/doc/debian/en/
/usr/doc/debian/en/text/
/usr/doc/debian/en/text/policy.text
/usr/doc/debian/en/text/developers-reference.text
/usr/doc/debian/en/sgml/
/usr/doc/debian/en/sgml/policy.sgml
/usr/doc/debian/en/sgml/developers-reference.sgml
/usr/doc/debian/en/html/
/usr/doc/debian/en/html/policy/
/usr/doc/debian/en/html/policy/index.html
/usr/doc/debian/en/html/developers-reference/
/usr/doc/debian/en/html/developers-reference/index.html
...etc...
as well as other languages.
Note that some <format> holds files, while others hold directories.
Obviously if a user installs only one format, the other <format> dirs
will not be installed, as for languages.
I know that the presence of the "en" language is annoying for most
english users, but we need a polite structure in which every level has
one and only one meaning.
In fact I don't like the compromise that fsstnd permits for man
hierarchy (and that debian adopted, because fsstnd didn't mandate) of
having an "empty" english-language level. I would much more like an
esplicit "en" level; it makes things simpler also for programs, and it's
POSIX compliant.
>
> 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>.
>
> In continuation of this policy I suggest to keep all documentation
> files in one place: /usr/doc/<pkg>.
I agree for package-related docs (because man's copyright belongs to man
and not to "copyright"), but I am very annoyed because I never remember
the <pkg> name of each debian-manual: I read them using the "file:"
protocol, and I have both hamm and bo hierarchies mounted on my machine,
and those manuals changed package name between bo and hamm, so I always
have to search using dpkg -S :-)
Fabrizio
--
| fpolacco@icenet.fi fpolacco@debian.org fpolacco@pluto.linux.it
| Pluto Leader - Debian Developer & Happy Debian 1.3.1 User - vi-holic
| 6F7267F5 fingerprint 57 16 C4 ED C9 86 40 7B 1A 69 A1 66 EC FB D2 5E
> Just because Red Hat do it doesn't mean it's a good idea. [Ian J.]
Reply to: