undocumented features - Stupid Portage Tricks - DOC_SYMLINKS_DIR

> Recent Entries
> Archive
> Friends
> Profile
> devspace

June 15th, 2011

11:27 pm - Stupid Portage Tricks - DOC_SYMLINKS_DIR
Ever have a package that installs HTML documentation into /usr/share/doc that you want to create a local bookmark to? For example, I find it useful to keep the quick reference page of the Advanced Bash-Scripting Guide (app-doc/abs-guide) open in a tab, and because I sometimes need to work offline I want to link to the local copy instead of a web page.

One of the headaches you'll quickly encounter trying to do this is that package directories have versioned names, meaning every version bump breaks your links. This gets really old really fast. Fortunately portage has a solution: DOC_SYMLINKS_DIR.

The idea is that if you set DOC_SYMLINKS_DIR to a path, portage will create unversioned symlinks for packages installing HTML docs and update them automatically when the version changes.

So for example after you set DOC_SYMLINKS_DIR="/home/dirtyepic/doc/" and emerge abs-guide:
  $ tree -d ~/doc
  `-- app-doc
      `-- abs-guide -> /usr/share/doc/abs-guide-6.3/HTML

You can then just bookmark file:///home/dirtyepic/doc/app-doc/abs-guide/refcards.html and never have to worry about updating it.

As I mentioned above, portage will create symlinks for any packages installing HTML docs (determined by looking for "html" or "HTML" subdirectories). Personally I don't like my doc directory cluttered up with a bunch of packages I don't care about so I just enable DOC_SYMLINKS_DIR on a per-package basis:
  $ cat /etc/portage/env/app-doc/abs-guide 

Some notes:

- If you want the symlink dir under your home then use the absolute path (ie. /home/someone/doc, not ~/doc). Portage's ~ is ${PORTDIR}.
- This only works if the package's doc dir contains an "html" or "HTML" directory, and it links directly to that directory, which is unfortunate.

(4 comments | Leave a comment)


Date:June 16th, 2011 07:54 am (UTC)
That's great, thanks a lot!

I just wander why Gentoo still installs docs into /usr/share/doc/${PF}, not ${CATEGORY}_${PN}-${SLOT} or something. That'd save a lot of trouble, I'd say.

Diego wrote about it a year ago, too:
Date:June 16th, 2011 10:11 am (UTC)


Excellent tip. Thanks for sharing :)
Date:June 22nd, 2011 10:06 pm (UTC)
[User Picture]
From:Donnie Berkholz
Date:June 28th, 2011 03:01 pm (UTC)

Your evil twin

I found your evil twin: http://dev.gentoo.org/~dberkholz/images/mark.png (one of my friends). Isn't the resemblance eerie?

> Go to Top