Arch Linux

Please read this before reporting a bug:
https://wiki.archlinux.org/title/Bug_reporting_guidelines

Do NOT report bugs when a package is just outdated, or it is in the AUR. Use the 'flag out of date' link on the package page, or the Mailing List.

REPEAT: Do NOT report bugs for outdated packages!
Tasklist

FS#22798 - Adopt a documentation handling policy

Attached to Project: Arch Linux
Opened by Greg (dolby) - Monday, 07 February 2011, 12:08 GMT
Last edited by Andreas Radke (AndyRTR) - Saturday, 03 November 2012, 09:31 GMT
Task Type Feature Request
Category Documentation
Status Closed
Assigned To No-one
Architecture All
Severity Low
Priority Normal
Reported Version
Due in Version Undecided
Due Date Undecided
Percent Complete 100%
Votes 1
Private No

Details

Arch Linux doesnt have a plan of proper handling the documentation provided by upstream projects.
It has been 2 years since JGC had said:
"Our policy for documentation is a bit weird at this moment. Take a look in /usr/share/doc -> you'll find directories named after the package name, directories with capitals in it, directories with versions, etc. Another thing is the name of the copyright file in /usr/share/licenses/$pkgname. If we want to change this, we should take some steps:..." on https://bugs.archlinux.org/task/12688#comment37047 yet very little has being done towards that direction.

Obviously Arch has come a long way.
From the "man pages all the way" moto, to including and handling info files and of course not stripping out the documentation which is being built by the packages by default.
But the truth is, you cant rely on upstream to build and install all the useful documentation part of their sources. In many occasions example configuration files, example usage files and many other immensly helpful and valuable resources that accompany the sources Arch Linux distributes are unavailable in the package due to this lack of plan and users are forced to download the upstream sources themselves to read them. Unlike eg. man pages, those resources are not available anywhere else.

I would like to request for packages to get built with such useful documentation included.
The documentation that gets built by default is rarely useful. COPYING and AUTHORS files is documentation hardly anyone needs to consult.
Obviously what gets in the package will be pretty much up to its maintainer and probably will require manual intervention and judgement on what to include and what not.
It is my firm belief though, that improving the situation with documentation will benefit the Arch Linux in numerous ways.
This task depends upon

Closed by  Andreas Radke (AndyRTR)
Saturday, 03 November 2012, 09:31 GMT
Reason for closing:  None
Additional comments about closing:  documentation is boring for most devs and not something essential until you want to sell a product or declare docs part of our bsd-like perfection...

I suggest to file one bug per per one pkg when something needs to be improved.

Boring!
Comment by Allan McRae (Allan) - Tuesday, 08 February 2011, 01:05 GMT
I hate to say it, but this is the type of bug that will sit open for multiple years until someone gets bored with it and closes it... There are just too many points being made that are all far too vague to action.

Comment by Greg (dolby) - Tuesday, 08 February 2011, 04:47 GMT
"the type of bug that will sit open for multiple years" true
"too many points being made that are all far too vague to action" I don't think that is true.
The only point being made is that all packages could have a /usr/share/doc/$pkgname directory containing either just the license, or accompanied by other useful documentation part of the source as well.
One step towards this direction might be namcap and makepkg warning for the lack of such a directory and a copyright file for example.
Comment by Allan McRae (Allan) - Tuesday, 08 February 2011, 05:23 GMT
Why bother with /usr/share/doc/$pkgname containing just a licence? As you said in the original report "COPYING and AUTHORS files is documentation hardly anyone needs to consult". If no-one needs to consult the COPYING file (which is probably the license), why include it? I also do not see the point of moving this (or duplicating it) from /usr/share/licenses. Making all packages have a /usr/share/licenses/$pkgname folder may be another option.

As far as including "useful" documentation in /usr/share/doc/$pkgname goes, as a packager I would maintain that if upstream does not install it there and no user opens a bug report requesting it to be added, then it is not useful. Therefore I would do nothing to my packages...

Comment by Greg (dolby) - Saturday, 16 April 2011, 00:59 GMT
Here are some arguments about why Arch should handle documentation somehow:
I checked around 40 packages from community:
 FS#23727   FS#23689   FS#23684   FS#23669   FS#23227   FS#22997 
And there is of course post install messages like this one:
http://projects.archlinux.org/svntogit/community.git/tree/newsbeuter/repos/community-x86_64/newsbeuter.install

While one may argue that these are caused by bad packaging the fact is that people dont read the documentation, not even packagers the one thats included in the application sources, and whats worst of all, theres a need for users to be instructed to look into provided documents.

I don't have a plan, but my recommendation has always been whats in  FS#12688  , copy the documentation manually, but Aaron didnt like the fact that it cant be automated.
Comment by Greg (dolby) - Sunday, 21 October 2012, 07:46 GMT
Some other points in favour of my awesome proposal, regarding killing the licenses package and handling documentation in general.
a) Now that Arch does build the documentation, the license the documentation itself is under is hardly ever included in the license field in PKGBUILDs.
b) Allan now seems to be in favour of this https://bugs.archlinux.org/task/29737#comment93785

PS. currently open bugs related to licensing:  FS#27655  (OFL),  FS#27853  (ISC),  FS#29737  (many of them!),  FS#31547  (MPL)

EDIT: i dont know if implementing this would have any impact on pacman and makepkg regarding the license field.
& also namcap of course.
Comment by Greg (dolby) - Sunday, 21 October 2012, 14:56 GMT
An example i just bumped into (im sure theres hundreds or even thousands like this one in the repos) is libtorrent which doesnt include a license in the package and the PKGBUILD states the license as being GPL.
The libtorrent README [0] states:
"LICENSE

GNU GPL, see COPYING. "libtorrent/src/utils/sha_fast.{cc,h}" is
originally from the Mozilla NSS and is under a triple license; MPL,
LGPL and GPL. An exception to non-NSS code has been added for linking
to OpenSSL as requested by Debian, though the author considers that
library to be part of the Operative System and thus linking is allowed
according to the GPL.
Use whatever fits your purpose, the code required to compile with
Mozilla's NSS implementation of SHA1 has been retained and can be
compiled if the user wishes to avoid using OpenSSL."

In conjuction here is Debian's copyright file:
http://packages.debian.org/changelogs/pool/main/libt/libtorrent/libtorrent_0.13.2-1/libtorrent14.copyright
Far too complex but at least accurate.

[0]: https://github.com/rakshasa/libtorrent/blob/master/README

Loading...