\: vim:syntax=tex
\: This file is maintained at http://git.mdcc.cx/draai
\: This is a manpage in zoem format.  See http://micans.org/zoem/, pud(7)
\: and /usr/share/doc/zoem/mac/buzzz.azm.gz

\import{pud/man.zmm}
\import{./include.zmm}

\begin{pud::man}{
  {name}{dr_symlinks}
  {html_title}{dr_symlinks}
  {section}{1}
  \man_share
}

\: \${html}{\"man::maketoc"}

\sec{name}{NAME}
\NAME{dr_symlinks}{maintain a symlink forest}

\sec{synopsis}{SYNOPSIS}
  \par{dr_symlinks}

\sec{description}{DESCRIPTION}

For each pair directory/subdirectory under each word in DR_SL_TARGETS, a
directory and symlink DR_SL_SOURCE/directory/symlink is created (or adjusted).
The script is implemented as a wrapper around oggsymlinks, by Wessel Dankers.

\sec{example}{EXAMPLE}

If, in the configuration file $HOME/.draai/symlinksrc, DR_SL_SOURCE is set to
/srv/audio and DR_SL_TARGETS is set to "../data/a ../data/b", while directories

\verbatim{
 /srv/data/a/And_You_Will_Know_Us_By_the_Trail_of_Dead/Source_Tags_And_Codes/
 /srv/data/a/And_You_Will_Know_Us_By_the_Trail_of_Dead/The_Century_of_Self/
 /srv/data/a/John_Coltrane/A_Love_Supreme/
 /srv/data/b/John_Coltrane/Giant_Steps/
 /srv/data/b/Tinariwen/Amassakoul/
}

exist, the following directories holding the following symlinks will get created
in /srv/audio/ :

\verbatim{
 And_You_Will_Know_Us_By_the_Trail_of_Dead/Source_Tags_And_Codes ->
  ../../../a/And_You_Will_Know_Us_By_the_Trail_of_Dead/Source_Tags_And_Codes/
 And_You_Will_Know_Us_By_the_Trail_of_Dead/The_Century_of_Self -> 
  ../../../a/And_You_Will_Know_Us_By_the_Trail_of_Dead/The_Century_of_Self/
 John_Coltrane/A_Love_Supreme -> ../../../a/John_Coltrane/A_Love_Supreme/
 John_Coltrane/Giant_Steps -> ../../../b/John_Coltrane/Giant_Steps/
 Tinariwen/Amassakoul -> ../../../b/Tinariwen/Amassakoul/
}

All dangling symlinks and empty directories (if any) under /srv/audio/ will get
removed.  This script is idempotent.

\sec{another example}{ANOTHER EXAMPLE}

\verbatim{
joostvb@hille:~% ls media/usb/audio/200504/Al_Green                 
The_Very_Best_Of/

joostvb@hille:~% ls media/usb/audio/               
200504/  200708/  200801/  200805/  200807/  200812/  200910/  201005/  201009/
200609/  200712/  200803/  200806/  200808/  200905/  201004/  201006/

joostvb@hille:~% cat .draai/symlinksrc.usb 

DR_SL_SOURCE=~/media/audio
DR_SL_TARGETS="$( cd $DR_SL_SOURCE && ls -d ../usb/audio/* )"

joostvb@hille:~% DR_SL_RCFILE=.draai/symlinksrc.usb dr_symlinks 

joostvb@hille:~% ls -l media/audio/Al_Green 
total 0
lrwxrwxrwx 1 joostvb joostvb 48 2011-03-11 09:12 The_Very_Best_Of -> ../../usb/audio/200504/Al_Green/The_Very_Best_Of/
}

\sec{environment}{ENVIRONMENT}

dr_symlinks honors booleans: DR_SL_VERBOSE, DR_DEBUG and DR_DRYRUN and strings:
DR_SL_RCFILE, DR_SL_TARGETS and DR_SL_SOURCE.

\sec{files, configurarion}{FILES, CONFIGURATION}

All configuration variables (see ENVIRONMENT) can be set in
\tt{~/.draai/symlinksrc}.  This rc-file is sourced as a shell script.
If DR_SL_RCFILE is set, its value is assumed to be the dr_symlinks rc-file.

\sec{copyright and license}{COPYRIGHT AND LICENSE}

This manpage is copyright 2009, 2011 \"man::author".

Draai is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License, as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.  This program is distributed WITHOUT ANY WARRANTY.  You should have
received a copy of the GNU General Public License along with draai.  If not,
see \httpref{http://www.gnu.org/licenses/}.

\sec{author}{AUTHOR}

\"man::author"

\end{pud::man}