Ebuilds that install documentation usually do it in /usr/share/doc/${PF}. Since this path changes with every version or revision bumps, this policy makes difficult to keep up-to-date bookmarks to useful local documentation (like programming languages reference manuals for instance). I suggest that such ebuilds create a symlink that would not move on each bump. By default, for non-slotted ebuilds, it would be: /usr/share/doc/${PN} --> ${PF}/${DOCDESTREE} And for slotted ebuilds: /usr/share/doc/${PN}-${SLOT} --> ${PF}/${DOCDESTREE} For instance, the dev-python/python-docs-2.3.4 ebuild would install this symlink: /usr/share/doc/python-docs-2.3 --> python-docs-2.3.4/html That would allow users to bookmark their local python docs on "file:///usr/share/doc/python-docs-2.3/index.html" and have this bookmark still correct after an update to a future python 2.3.5. Despite I understand that this is more a matter of policy than code, I've implemented a simple eclass that provides a function that creates such symlinks, and is meant to be used at the end of src_install(). Reproducible: Always Steps to Reproduce:
Created attachment 41564 [details] eclass/doc-symlink.eclass
Created attachment 41565 [details, diff] python-docs-2.3.4.ebuild--doc-symlink.patch Example of how to use this eclass. Once applied, the python-docs ebuild will install this symlink: /usr/share/doc/python-docs-2.3 -> python-docs-2.3.4/html
Something I forgot to talk about is the possibility to implement this feature at portage level instead of eclass/ebuilds level. Actually, what I first wrote was a patch that was adding a "docsymlink" portage FEATURES flag that was forcing creation of a "/usr/share/doc/${PN}[-${SLOT}] -> ${PF}" for every package that was installing a /usr/share/doc/${PF} directory. I've used it for a few weeks, but that was introducing to much noise in /usr/share/doc for something that is completly useless for 95% of the packages. Hence I've wrote the eclass, to allow packagers to decide when the symlink should be created. But the drawback is that it relies on ebuild modifications, that may never happen. An alternative would be the following: at portage level, create a doc symlink for packages that install some HTML documentation, if a given FEATURES flag is set. I will attach a patch for ebuild.sh that implements that. Detection of HTML documentation is just a test of existence of an "html" subdir in the doc dir: it seems to be enough in most cases, but if needed that could be improved. Pros: - no need to modify ebuilds - won't affect users that dont set the FEATURES flag Cons: - can't be as reliable as the per-ebuild implementation - may create conflicts in case both cat-foo/pkg-name and cat-bar/pkg-name install some html docs
Created attachment 41631 [details, diff] ebuild.sh--htmldoclink_feature.patch The patch described in comment #3.
random notes: I'd prefer if those symlinks would go into a subdir and I don't like adding another FEATURE for it. The symlinks wouldn't take much space and if they are in a subdir they don't clutter the /usr/share/doc listing.
maybe something like /usr/share/doc/perm/ ... then the symlinks would just point to ../${PF}
Created attachment 42383 [details, diff] ebuild.sh--doc_symlink.patch Here is a modified version of the ebuild.sh patch. - there is no more FEATURES flag. - the symlinks location depends on the DOC_SYMLINKS_DIR variable. I've set it to "/usr/share/doc/symlinks" in my make.conf. If not set, then no symlink will be created. - an $HTMLDOC_DIR var can be used in ebuilds to force making a symlink on a dir that is not one of the standard (ie., {$PF,$P}/{html,HTML}) /usr/share/doc subdir.
Created attachment 54376 [details, diff] HEAD--doc_symlink.patch Same patch for portage HEAD (code moved from ebuild.sh to default-functions.sh).
Putting a hold on feature requests for portage as they are drowning out the bugs. Most of these features should be available in the next major version of portage. But for the time being, they are just drowning out the major bugs and delaying the next version's progress. Any bugs that contain patches and any bugs for etc-update or dispatch-conf can be reopened. Sorry, I'm just not good enough with bugzilla. ;)
Reopening since this one is trivial and comes with a patch i've been using for months with no issue.
How are SLOTs handled?
The link name is "$PN" when "$SLOT" is 0 or null, and "$PN-$SLOT" otherwise, thus there should be no conflict beetween slotted packages. For instance, here i have both a "python-docs-2.3" and a "python-docs-2.4" symlinks. The only case of conflict i can think of is if 2 packages with same name in different categories provide some html docs. I've never encountered that case, but it's possible in theory. A way to avoid that would be to create th symlinks in subdirs named by the category. I can add that if you think that's necessary.
Okay, I've taken a close look. I'm thinking that it would probably be better to do it in dodoc rather than having to modify all ebuilds. To cover the namespace collision possibility, maybe make another function to handle it? docalias perhaps. Was there ever a thread about this on -dev@g.o? However it's done, it should be within src_install() so that collision-protect plays properly. Using the DOC_SYMLINKS_DIR is good, by the way. It has the same feel as PORT_LOGDIR. Other than that, everything seems fine.
I've just made a test (of the last attached patch, the "no ebuild modification needed" solution) with collision-protect enabled and two conflicting ebuilds: same name, different category, both installing some html file, and both in SLOT=0. It happens that collision-protect didn't detect this conflict: % emo port-teeeeest/docsymlink <--snip--> >>> Install docsymlink-1 into /var/tmp/portage/docsymlink-1/image/ category port-teeeeest * Symlinking /usr/share/doc/symlinks/docsymlink to the HTML documentation >>> Completed installing docsymlink-1 into /var/tmp/portage/docsymlink-1/image/ processing merge * checking 1 files for package collisions * spent 0.00 seconds checking for file collisions >>> Merging port-teeeeest/docsymlink-1 to / *** Adjusting ccache permissions for portage user... overloading port_env_file setting to /var/tmp/portage/docsymlink-1/temp/environment --- /usr/ --- /usr/share/ --- /usr/share/doc/ --- /usr/share/doc/symlinks/ >>> /usr/share/doc/docsymlink-1/ >>> /usr/share/doc/docsymlink-1/html/ >>> /usr/share/doc/docsymlink-1/html/foo.html >>> /usr/share/doc/symlinks/docsymlink -> /usr/share/doc/docsymlink-1/html <--snip--> % emo port-test/docsymlink <--snip--> >>> Install docsymlink-2 into /var/tmp/portage/docsymlink-2/image/ category port-test * Symlinking /usr/share/doc/symlinks/docsymlink to the HTML documentation >>> Completed installing docsymlink-2 into /var/tmp/portage/docsymlink-2/image/ processing merge * checking 1 files for package collisions * spent 0.00 seconds checking for file collisions >>> Merging port-test/docsymlink-2 to / *** Adjusting ccache permissions for portage user... overloading port_env_file setting to /var/tmp/portage/docsymlink-2/temp/environment --- /usr/ --- /usr/share/ --- /usr/share/doc/ --- /usr/share/doc/symlinks/ >>> /usr/share/doc/docsymlink-2/ >>> /usr/share/doc/docsymlink-2/html/ >>> /usr/share/doc/docsymlink-2/html/foo.html >>> /usr/share/doc/symlinks/docsymlink -> /usr/share/doc/docsymlink-2/html <--snip--> It seems that collision-protect doesn't handle symlinks, at least not those pointing directories (that's what the "checking 1 files for package collisions" seems to indicate too). Is that expected behavior or a bug? Anyway, i've modified the patch to add support for an optionnal DOC_SYMLINK_NAME ebuild variable: if set, then it will be used to name the symlink instead of $PN or $PN-$SLOT. That's enough to workaround such conflicts if they ever happen.
Created attachment 64779 [details, diff] HEAD--doc_symlink.patch
Ah, yes. I forgot that collision-protect presently ignores symlinks. But still, if we don't pretend that it does process symlinks it'll come back as a new bug later on. ;)
*** Bug 83272 has been marked as a duplicate of this bug. ***
Created attachment 71553 [details, diff] portage-2.0-20051024-doc_symlink.patch Updated patch for 2.0 SVN. No change but a code move from ebuild-default-functions.sh back to ebuild.sh.
Created attachment 71554 [details, diff] portage-2.0-20051024-doc_symlink-man.patch man/ebuild.5 documentation of the HTMLDOC_DIR variable (although rather few package would actually need it i think)
Created attachment 71555 [details, diff] portage-2.0-20051024-doc_symlink-cnf.patch cnf/make.conf* documentation of the DOC_SYMLINKS_DIR variable.
Created attachment 71556 [details, diff] portage-2.0-20051024-doc_symlink-man.patch Oops, i had forgoten to document DOC_SYMLINK_NAME in the ebuild.5 patch.
Okay, this patches are candidate for the next portage release round (2.0.54). I think the feature is useful, and code is pretty trivial and non-intrusive.
Created attachment 84208 [details, diff] portage-2.1_pre7-doc_symlink.patch rediffed for http://thread.gmane.org/gmane.linux.gentoo.devel/37295/focus=37295
Is this really needed? I'd favor creating rss feeds from the documentation urls. don't know if some may think it vioates the KISS principle, but it would even allow to point to non-local documentation, instead installing it.
(In reply to comment #24) > Is this really needed? Needed, no, sure, and i think it should stay optional. But after ~1.5 year of usage, i must say i still find it very convenient. I have ~150 symlinks in my /usr/share/doc/symlinks directory, ~20 of which are bookmarked because i use them often enough. That's all i need and all i get. > I'd favor creating rss feeds from the documentation urls. Sounds fun, but I'm not sure i understand how it would help my case. What i want is direct and simple access to my local documentation from my web browser (ie., bookmarks to some file:/// URLs that don't break on every revbump). > it would even allow to point to non-local documentation, instead > installing it. I prefer to actually install the doc, because i code more when offline :) And anyway, for online docs, i've never felt there was anything to improve: the URLs are usualy not moving so often, thus i can already safely bookmark them, and i'm happy with that. But maybe i just don't well understand your idea. Oh, and just FYI, yet another approach is Ed Catmur's src_install hook for auto-generating devhelp books: http://catmur.co.uk/svn/repos/gentoo/phase_hooks.d/post_src_install/ But i don't use devhelp myself, i prefer to have everything in my web browser. (makes me think that i could convert my patch to a phase hook too though, it would be easier if some other people want to use it)
(In reply to comment #25) > Oh, and just FYI, yet another approach is Ed Catmur's src_install hook for > auto-generating devhelp books: > http://catmur.co.uk/svn/repos/gentoo/phase_hooks.d/post_src_install/ > But i don't use devhelp myself, i prefer to have everything in my web browser. > > (makes me think that i could convert my patch to a phase hook too though, it > would be easier if some other people want to use it) Portage phase hooks (never heard of them before) sound like a good place to put doc-symlink-functionality in. When will portage (stable) ship with phase hooks? (Google didn't tell me ;) PS: Just for the record: auto-generation of a /usr/share/doc/index.html listing all found html-docs would be a nice add-on to this :) (As mentioned here: http://article.gmane.org/gmane.linux.gentoo.devel/37296)
(In reply to comment #26) > Portage phase hooks (never heard of them before) sound like a good place > to put doc-symlink-functionality in. Seeing how different is everyone opinions on what would be the right behavior for indexing html doc (symlinks, index.html, devhelp books, rss feed, etc.), I guess that yes, it belongs to hooks, so that it is really user-configurable. For making symlinks as i do, it could be something like this (in /etc/portage/bashrc): post_src_install() { # Where to put the symlinks? # - no category, everything in the same dir. Be aware that this may # lead to conflicts beetween homonym packages: #local symlink_dir="/usr/share/doc/symlinks" # - one subdir per category. Be aware that sometimes packages get # moved from one category to another, so some symlinks may be moved # by an update: local symlink_dir="/usr/share/doc/symlinks/${CATEGORY}" local mydocdir docdir for docdir in "${PF}/html" "${PF}/HTML" "${P}/html" "${P}/HTML" ; do [[ -d "${D}/usr/share/doc/${docdir}" ]] \ && mydocdir="/usr/share/doc/${docdir}" \ && break done if [[ -n "${mydocdir}" ]] ; then local symlink_name="${PN}" [[ -n "${SLOT}" ]] \ && [[ "${SLOT}" != "0" ]] \ && symlink_name="${PN}-${SLOT}" einfo "Symlinking ${symlink_dir}/${symlink_name} to the HTML doc" dodir "${symlink_dir}" dosym "${mydocdir}" "${symlink_dir}/${symlink_name}" fi } But sure, there is a drawback: ebuilds don't care about what people do in their phase hooks. It means that we can't expect they will ease the task of indexing their doc. For instance, with my previos patch, they were able to force the symlink name by setting a $DOC_SYMLINK_NAME variable (needed to avoid conflicts, when two packages with the same name but from two different categories both install some HTML doc). With a non-standard (in phase hook) implementation, there is no more reason they set such a variable, and thus you have to create one subdir per category to avoid this conflicts (with the drawback explained in the function comments). > When will portage (stable) ship with phase hooks? I don't remember whether it exists in latest 2.0.*, but it is in 2.1_pre for sure. As to when 2.1 will become stable, i don't know, but this discussion may help getting an estimation: http://thread.gmane.org/gmane.linux.gentoo.portage.devel/2002/focus=2002
(In reply to comment #25) > > I'd favor creating rss feeds from the documentation urls. > > Sounds fun, but I'm not sure i understand how it would help my case. What i > want is direct and simple access to my local documentation from my web browser > (ie., bookmarks to some file:/// URLs that don't break on every revbump). I don't know what browser you are using, but that's exactly what I want, too. Firefox supports live bookmarks, which is reading bookmarks from a feed source. If you e.g. open kernel.org in Firefox and click on the orange icon, bottom right in the status bar, you'll see. Just subfolders are not supported, so I did file https://bugzilla.mozilla.org/show_bug.cgi?id=332095 > > it would even allow to point to non-local documentation, instead > > installing it. > > I prefer to actually install the doc, because i code more when offline :) > And anyway, for online docs, i've never felt there was anything to improve: > the URLs are usualy not moving so often, thus i can already safely bookmark > them, and i'm happy with that. I didn't mean with non-local access it directly on the internet, but multi-user solutions, having a documentation server, instead installing the docs on every single workstation. I thought about a little tool, so you can write adddocfeed "name" category/package:slot" "one, two,... catchwords" "url" in an ebuild, resulting in a few predefined feeds (whole doc tree, based on the catchwords,...?) as well as the possibility of user defined ones.
*** Bug 143628 has been marked as a duplicate of this bug. ***
Updated for trunk, using per-category dirs.
Thanks. This is in svn r5509 and has been released in 2.1.2_rc4-r8.
*** Bug 498588 has been marked as a duplicate of this bug. ***
*** Bug 916479 has been marked as a duplicate of this bug. ***
