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
/home/dirtyepic/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
DOC_SYMLINKS_DIR=/home/dirtyepic/doc
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.
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
/home/dirtyepic/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
DOC_SYMLINKS_DIR=/home/dirtyepic/doc
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.