= Proposed System Wide Change: Unversioned Docdirs = https://fedoraproject.org/wiki/Changes/UnversionedDocdirs
Change owner(s): Ville Skyttä ville.skytta@iki.fi
Install package specific documentation to an unversioned subdir in /usr/share/doc.
== Detailed description == Change the per package documentation directory in /usr/share/doc to unversioned, just containing the package's name (previously it contained both the package's name and its version). rpmbuild already has support for this, by setting the %_docdir_fmt macro to %{name} we cover most of the cases. Other cases can be grepped through from package specfiles/patches -- grepping for _docdir, _defaultdocdir, usr/share/doc and _datadir.*doc should catch almost everything. Packages for which multiple versions are intended to be installed need to be changed to install their docs into appropriately versioned subdirs, for example explicitly using the previous NAME-VERSION scheme. Some of these cases, if unaddressed, will also manifest themselves as build failures due to files not found at expected locations.
== Scope == Proposal owners: take care of having the %_docdir_fmt macro set to %{name} in rpm or redhat-rpm-config, grep through package specfiles and patches identifying cases needing special attention.
Other developers: see if their package explicitly refers to a NAME-VERSION subdir in /usr/share/doc, and change those to NAME.
Release engineering: mass rebuild is required after the %_docdir_fmt macro change.
Policies and guidelines: all documentation referring to NAME-VERSION subdirs in /usr/share/doc needs to be changed to NAME instead. _______________________________________________ devel-announce mailing list devel-announce@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/devel-announce
On 07/16/2013 12:28 PM, Jaroslav Reznik wrote:
== Detailed description == Change the per package documentation directory in /usr/share/doc to unversioned, just containing the package's name (previously it contained both the package's name and its version). rpmbuild already has support for this, by setting the %_docdir_fmt macro to %{name} we cover most of the cases. Other cases can be grepped through from package specfiles/patches -- grepping for _docdir, _defaultdocdir, usr/share/doc and _datadir.*doc should catch almost everything. Packages for which multiple versions are intended to be installed need to be changed to install their docs into appropriately versioned subdirs, for example explicitly using the previous NAME-VERSION scheme. Some of these cases, if unaddressed, will also manifest themselves as build failures due to files not found at expected locations.
Why?
This will allow to have foo-9.8.4 installed together with foo-doc-1.0.0. In other words, user can have pretty outdated documentation. Or new documentation and outdated code. Do we want that?
On Tue, Jul 16, 2013 at 1:55 PM, Miroslav Suchý msuchy@redhat.com wrote:
Why?
See the "Benefit to Fedora" section.
This will allow to have foo-9.8.4 installed together with foo-doc-1.0.0. In other words, user can have pretty outdated documentation. Or new documentation and outdated code.
I don't think whether the doc dir names are versioned or not has anything to do with the above. It is already now possible, and it continues to be possible after this change.
Do we want that?
If you don't want the above mix of versions to be possible, use versioned rpm dependencies to enforce it, just like needs to be done today.
On Tue, Jul 16, 2013 at 06:55:37PM +0800, Christopher Meng wrote:
What's the advantages exactly?
If a package installs HTML docs into /usr/share/doc/<name>-<version> and you want to bookmark that in your web browser, then your bookmarks break everytime the RPM is updated :-( You could of course fix this by keeping the existing versioned directories, and then adding a symlink from /usr/share/doc/<name> to the versioned directory. I have no strong opinion on which way is best. I'd just like to see a stable pathname for the docs so you can bookmark them
Regards, Daniel
在 2013-7-16 PM7:00，"Daniel P. Berrange" berrange@redhat.com写道：
On Tue, Jul 16, 2013 at 06:55:37PM +0800, Christopher Meng wrote:
What's the advantages exactly?
If a package installs HTML docs into /usr/share/doc/<name>-<version> and you want to bookmark that in your web browser, then your bookmarks break everytime the RPM is updated :-( You could of course fix this by keeping the existing versioned directories, and then adding a symlink from /usr/share/doc/<name> to the versioned directory. I have no strong opinion on which way is best. I'd just like to see a stable pathname for the docs so you can bookmark them
But from the dir name I can quickly know the version.
How many packages are needed for bookmarks?
On Tue, Jul 16, 2013 at 2:00 PM, Daniel P. Berrange berrange@redhat.comwrote:
If a package installs HTML docs into /usr/share/doc/<name>-<version> and you want to bookmark that in your web browser, then your bookmarks break everytime the RPM is updated :-(
Yes, and like said in the proposal, it's not limited to HTML and browser bookmarking. Cross referencing other packages' docs (from other HTML or plain text docs, scripts, code, systemd unit Documentation= or whatever) is similarly affected.
On 07/16/2013 01:15 PM, Ville Skyttä wrote:
Yes, and like said in the proposal, it's not limited to HTML and browser bookmarking. Cross referencing other packages' docs (from other HTML or plain text docs, scripts, code, systemd unit Documentation= or whatever) is similarly affected.
For one data point, try running this on your system:
$ zgrep '/usr/share/doc/[^0-9]*/' /usr/share/man/man1/*
Some packages fail to rewrite the paths in their manual pages. :-(
-
Christopher Meng -
Daniel P. Berrange -
Florian Weimer -
Jaroslav Reznik -
Miroslav Suchý -
Ville Skyttä