Added a LaTeX version of GrimoireGuruHandbook. I find this easier to organize and output to different formats (text, PDF, HTML, etc.)

1 files changed, 1202 insertions, 0 deletions

diff --git a/GrimoireGuruHandbook.tex b/GrimoireGuruHandbook.tex
new file mode 100644
index 0000000..d51b8bd
--- /dev/null
+++ b/GrimoireGuruHandbook.tex
@@ -0,0 +1,1202 @@
+\documentclass[a4paper,10pt]{book}
+
+
+\begin{document}
+\title{Grimoire Guru Handbook v3.0}
+\begin{titlepage}
+
+\begin{center}
+\begin{Huge}
+Grimoire Guru Handbook v3.0
+\end{Huge}
+
+\begin{LARGE}
+for Source Mage GNU/Linux (http://www.sourcemage.org/)
+\end{LARGE}
+
+\end{center}
+\end{titlepage}
+
+\chapter{Introduction}
+Welcome to helping to improve Source Mage! As a contributing member you are
+entitled to filing bugs, submitting patches, and cleaning up our packages.
+Below you will find instructions and tips on how to be the most helpful you
+may be. You will soon be a bug hunting army of one.
+
+Subscribe to all the freshmeat pages for the software in your section of
+the grimoire, and also appropriate email lists for that software, and also
+subscribe to sm-spell-submit@lists.ibiblio.org for our own notifications.
+You probably have this covered already.
+
+You will be responsible for taking newly contributed spells from new spell
+submissions assigned to you via bugzilla\footnote
+{http://bugs.sourcemage.org/}, reviewing, correcting and submitting for
+inclusion in the grimoire. You may recruit as many people to help you with this
+as you want. You can reject, decline or otherwise ignore a newly contributed
+spell for any reason. You may delay reviewing spells for as long as you like.
+
+\chapter{Bug tracking}
+We are currently using Bugzilla, which is accessible from
+http://bugs.sourcemage.org/.
+\section{Creating an account}
+\section{Searching for bug reports}
+\section{Creating a bug report}
+\section{Taking ownership of a bug}
+\section{Requesting integration to stable(-rc)}
+
+\chapter{Patch creation}
+We prefer patches to be submitted with the diff options -Naur.
+
+\chapter{SCM Usage}
+\section{Requesting an account}
+Here I am assuming you have been invited to obtain write permissions to our
+repositories.
+
+Send an e-mail to emrys@sourcemage.org requesting an SCM account with which
+products (test grimoire, devel Sorcery, cauldron, etc.) you wish to have
+write access to as well as your public RSA key. If you do not have a RSA
+key, you may generate one by running:
+
+\begin{verbatim}
+$ ssh-keygen
+\end{verbatim}
+
+And include the contents of \~/.ssh/id\_rsa.pub (assuming you only have one RSA
+key).
+
+You may view the repositories via a web browser at
+http://scmweb.sourcemage.org/.
+\section{Checking out the repositories}
+Now that you have an SCM account, you are ready to checkout the repository
+you wish to work on. The following repositories are currently available:
+\begin{itemize}
+\item[cauldron] ISO scripts and configuration files
+\item[grimoire] Master grimoire repository
+\item[grimoire/games] Games grimoire repository
+\item[grimoire/xorg-modular] Development work on modular X.org
+\item[grimoire/z-rejected] Grimoire for binary packages and ones with licensing
+issues
+\item[misc/archspecs] Architecture specifications
+\item[misc/prometheus] Spell QA script
+\item[misc/quill] Spell updater/creator script
+\item[sorcery] Our package manager
+\item[tome/rdp] Rogue Documentation Project
+\end{itemize}
+
+Most Grimoire Developers will only work on with grimoire (which contains
+devel, test, stable-rc, and stable grimoires), so you will check it out
+with:
+\begin{verbatim}
+$ git clone ssh://scm.sourcemage.org/smgl/grimoire
+\end{verbatim}
+
+This will create a directory called 'grimoire' in your current directory.
+
+\section{Setting up your information}
+In each cloned repository, there is a .git/config file where you will
+provide some information (mainly for the commit messages):
+Assuming you are Eric Sandall, you will want to add the following
+information:
+
+\begin{verbatim}
+[user]
+   name = Eric Sandall
+  email = sandalle@sourcemage.org
+\end{verbatim}
+
+\section{Keeping clones up-to-date}
+To grab the latest changes from the SCM, you will 'pull' them to you with
+the following command, run from inside your clone (e.g. ~/grimoire/)
+\begin{verbatim}
+$ git pull
+\end{verbatim}
+Note that all but the `git clone` command need to be run from this
+directory.  If you receive a message saying "fatal: Not a git repository:
+'.git'", then you did not follow my instruction above.
+\section{Selecting your working branch}
+The main grimoire that you have checked out has many branches. You may view
+the available branches by running:
+\begin{verbatim}
+$ git branch
+\end{verbatim}
+And you will see output similar to this:
+
+\begin{verbatim}
+devel
+* master
+origin
+stable-0.3
+stable-0.4
+stable-rc-0.4
+stable-rc-0.5
+stable-rc-0.6
+\end{verbatim}
+
+The "*" before "master" means that this is the currently checked out branch.
+To checkout another branch (say devel), you would run:
+\begin{verbatim}
+$ git checkout devel
+\end{verbatim}
+Unless you know what you are doing, only work in the master (a.k.a. test)
+branch.
+
+You will *never* touch the 'origin' branch, as this is used by git
+internally to check your changes against.
+\section{Making changes}
+Before making any changes, it is a good idea to make sure your clone is
+up-to-date (though this is not required, it does make submitting easier).
+Now that you are up-to-date, let us do a practice update.
+
+Example: git 1.4.3.5 has just been released
+\begin{enumerate}
+\item Make sure we are up-to-date with upstream
+\begin{verbatim}
+$ git pull
+\end{verbatim}
+\item Make necessary changes to the git files
+\begin{verbatim}
+$ cd devel/git
+$ vi DETAILS HISTORY
+\end{verbatim}
+Change VERSION from 1.4.3.4 to 1.4.3.5
+Add update entry to HISTORY
+\item Mark the files you wish to update
+\begin{verbatim}
+$ git update-index DETAILS HISTORY
+\end{verbatim}
+\item Check which files are slated to be committed
+\begin{verbatim}
+$ git status
+# Updated but not checked in:
+#   (will commit)
+#
+#       modified: devel/git/DETAILS
+#       modified: devel/git/HISTORY
+#
+\end{verbatim}
+\end{enumerate}
+
+\section{Committing changes}
+Now that we have made our modifications, we should submit them. To commit
+all of your flagged files (from `git status`), run:
+\begin{verbatim}
+$ git commit
+\end{verbatim}
+
+This will open up your favorite editor (as defined in the variable EDITOR)
+with a file describing the files to be updated, where you briefly describe
+what changes you made.
+
+You may also commit only specific files by specifying them on the command
+line:
+\begin{verbatim}
+$ git commit DETAILS HISTORY
+\end{verbatim}
+
+This will only commit the DETAILS and HISTORY files in our current
+directory.
+
+If you wish to specify your message log on the command line, rather than in
+your favorite editor, you may do so with the -m flag:
+\begin{verbatim}
+$ git commit -m "Updated git to 1.4.3.5"
+\end{verbatim}
+
+If ever you make changes you wish to undo, before running `git commit`, you
+may run the following:
+\begin{verbatim}
+$ git checkout -f <list of files to revert to origin>
+\end{verbatim}
+
+Note that `git commit` only updates your local copy of the repository, not
+the server repository where everyone pulls from.
+\section{Pushing changes upstream}
+You may do as many commits as you like before pushing your changes back to
+the repository so everyone may see them. To push your changes to the server
+repository, run:
+\begin{verbatim}
+$ git push <destination> <source>
+\end{verbatim}
+
+Since we are working in master, we would run:
+\begin{verbatim}
+$ git push origin master
+\end{verbatim}
+
+Note that destination will almost always be 'origin'.
+
+\section{Resolving conflicts}
+When you receive a conflict (usually denoted by the lines):
+\begin{verbatim}
+ERROR: Merge conflict in {file}
+fatal: merge program failed
+After resolving the conflicts, mark the corrected paths with
+`git-update-index <paths>` and commit the result.
+\end{verbatim}
+
+Inside the conflicting file you will see the line \begin{verbatim}<<<<<
+.merge_file_stuff\end{verbatim},
+which begins the new changes, and a \begin{verbatim}>>>>>>
+.merge_file_otherstuff\end{verbatim}, which
+ends the new changes. Once you resolve the conflict by editing the file
+and remove what should not be there, you will run \textdollar git update-index
+<file>
+and then commit your changes.
+\section{Creating your own local branch}
+\section{Creating your own remote branch}
+\section{Checking out other branches}
+\section{Integrating between branches}
+\section{Updated a stable-rc or stable grimoire}
+
+These grimoires are special, in that you never modify them directly
+(similar to how you treat the origin branch). To update one of these (say
+stable-rc-0.6), you will use the following steps:
+\begin{enumerate}
+\item Switch to the stable-rc-0.6 branch.
+\begin{verbatim}
+$ git checkout stable-rc-0.6
+\end{verbatim}
+\item Create a branch of the current stable-rc-0.6 called my-stable-rc-0.6 and
+switch to it.
+\begin{verbatim}
+$ git checkout -b my-stable-rc-0.6
+\end{verbatim}
+\item Merge (cherry-pick) the commit id you want into the current branch
+\begin{verbatim}
+$ git cherry-pick 093af91834hf8a8df90238928f920023
+\end{verbatim}
+\item Synchronize stable-rc-0.6 with upstream
+\begin{verbatim}
+$ git pull origin stable-rc-0.6
+\end{verbatim}
+\item Push your changes from my-stable-rc-0.6 into stable-rc-0.6 and then up to
+the server (origin).
+\begin{verbatim}
+$ git push origin my-stable-rc-0.6:stable-rc-0.6.
+\end{verbatim}
+\end{enumerate}
+
+\section{Fetching a new remote branch}
+The need for this most commonly occurs when a new stable branch is released,
+but may be used for any other remote branches you wish to retrieve.
+
+Let's say that stable-0.6 was just released, and your current local branches
+look like this:
+\begin{verbatim}
+$ git branch
+devel
+* master
+origin
+stable-0.3
+stable-0.4
+stable-rc-0.4
+stable-rc-0.5
+stable-rc-0.6
+\end{verbatim}
+
+To grab the new stable-0.6 and stable-rc-0.7 (the next stable release
+candidate)
+you would do the following:
+\begin{verbatim}
+$ git fetch ssh://scm.sourcemage.org/smgl/grimoire.git stable-0.6:stable-0.6
+\end{verbatim}
+
+This tells git to fetch the remote branch named stable-0.6 (before the ":") and
+call it stable-0.6 (after the ":") into the current git repository.
+
+If you want this branch to be updated on a pull, you will also need to add
+the branch information to .git/remotes/origin:
+\begin{verbatim}
+Pull: refs/heads/stable-0.6:refs/heads/stable-0.6
+Pull: refs/heads/stable-rc-0.7:refs/heads/stable-rc-0.7
+\end{verbatim}
+
+These two lines will add pull information for stable-0.6 and stable-rc-0.7.
+
+\chapter{Writing a spell}
+\section{PREPARE}
+Even before DETAILS, this file is sourced and cane be used to setup variables
+for use in DETAILS.
+
+There are cases where a spell writer wants to allow a choice of version in a
+spell. Most of the times this is about pulling the current version from a
+source code management system like CVS of Subversion. There are other cases
+where an upstream project releases stable and development versions.
+
+First rule for allowing such a version choice is that all dependencies of the
+spell need to work with all versions, otherwise the spell should be split.
+
+The version choice is done in PREPARE using the usual config\_query functions.
+If there are more than two different versions to choose from, this should be
+done using config\_query\_list, always defaulting to the version upstream
+recommends as stable.
+
+For versions downloading from a source code management system, the spell should
+also ask the user whether she wants to update that spell automatically on every
+sorcery [system-update|queue] (defaulting to 'n') and setting the version to
+a timestamp.
+
+Example: Setting up VERSION ahead of time for a multi-version spell
+PREPARE:
+\begin{verbatim}
+config_query  SPELL_CVS  "Use CVS for latest development version?"  n  &&
+
+if  [[  "$SPELL_CVS" == "y"  ]];  then
+  config_query  SPELL_CVS_AUTOUPDATE  "Update on every system update?"  n
+  if  [[  "$SPELL_CVS_AUTOUPDATE"  ==  "y"  ]];  then
+        PREPARE_VERSION=$(date +%Y%m%d)
+  PREPARE_SOURCE_URL[0]=cvs://:pserver:anonymous@fun.org:/cvsroot/spell:main
+          SOURCE_IGNORE=volatile
+         FORCE_DOWNLOAD="on"
+  else
+        PREPARE_VERSION="cvs"
+  fi
+  else
+    # Default version
+        PREPARE_VERSION="2.1.3"
+            SOURCE_HASH=<some sha512 hash of the 2.1.3 tarball>
+fi
+\end{verbatim}
+
+DETAILS:
+\begin{verbatim}
+      VERSION=${PREPARE_VERSION:-"2.1.3"}
+       SOURCE=$SPELL-$VERSION.tar.bz2
+SOURCE_URL[0]=${PREPARE_SOURCE_URL[0]:-http://www.fun.org/download/$SOURCE}
+\end{verbatim}
+
+Note: The \$\{VAR``:-string\}  syntax means if \$VAR is not empty, then use
+\$VAR,
+if it is empty, then use the string.
+
+Note: We keep all of the checks out of DETAILS and use PREPARE for the
+ugliness.
+
+The following variables are available in PREPARE:
+\begin{itemize}
+\item[SOURCE\_CACHE] the directory where the sources reside:
+/var/spool/sorcery
+\item[SCRIPT\_DIRECTORY] the spell script directory in the codex:
+/path/to/grimoire/section/spell
+\item[SPELL\_DIRECTORY] this is the same as \textdollar SCRIPT\_DIRECTORY and
+is deprecated
+\item[SECTION\_DIRECTORY] path/to/grimoire/section
+\item[GRIMOIRE] /path/to/grimoire
+\end{itemize}
+
+For more info on these variables, check /var/lib/sorcery/modules/libcodex
+An important usecase for PREPARE is in multi version spells.
+
+\section{DETAILS}
+This file contains information about the application which the spell is for.
+\subsection{SPELL}
+SPELL
+	This specifies the name of the spell you are creating. It must be
+	lower case. (We let the developers of the application choose the way
+	they'd like it spelled).
+
+Example:
+\begin{verbatim}
+SPELL="xzgv"
+\end{verbatim}
+
+\subsection{VERSION}
+VERSION
+	This specifies the current version number of the application in
+	question. Please be exact.
+
+Example:
+\begin{verbatim}
+VERSION="0.7"
+\end{verbatim}
+
+\subsection{SOURCE}
+SOURCE
+	Specifies the name of the source file of the application. Must be the
+	full name not including any path information.
+
+Example:
+\begin{verbatim}
+SOURCE="$SPELL-$VERSION.tar.gz"
+\end{verbatim}
+
+SOURCEn
+	Specifies the names of additional source files for the application.
+	The numbering starts with 2.
+
+Example:
+\begin{verbatim}
+SOURCE2="xzgv-addons.tar.gz"
+\end{verbatim}
+
+\subsection{SOURCE\_DIRECTORY}
+SOURCE\_DIRECTORY
+	Used to specify the location where the source will be unpacked. You
+	must pay special attention to the naming of the directory when
+	unpacking the source file. (i.e. if the subdirectory is
+	\textdollar SPELL-\textdollar VERSION, or perhaps just \textdollar
+SPELL etc.). \textdollar BUILD\_DIRECTORY is a
+	special variable which is set by the sorcery tools to allow you to
+	not have to worry about where sorcery will unpack the source from,
+	currently sorcery uses /usr/src to begin the unpacking of the
+	application's source.
+
+Example:
+\begin{verbatim}
+SOURCE_DIRECTORY=$BUILD_DIRECTORY/$SPELL-$VERSION
+\end{verbatim}
+
+\subsection{SOURCE_URL}
+SOURCE\_URL[*]
+	An array where you specify as many targets of where to download the
+	source from. Must specify the full path (including filename) of the
+	application source, so it is known where to download the spell from.
+	Incrementing the number in the []'s will add additional entries,
+	attempted in numerical order.
+
+Example:
+\begin{verbatim}
+SOURCE_URL[0]=http://xzgv.browser.org/$SOURCE
+\end{verbatim}
+
+SOURCEn\_URL[*]
+	Arrays specifying the download links for additional SOURCEn entries.
+	The numbering starts with 2 (SOURCE2\_URL).
+
+Example:
+\begin{verbatim}
+SOURCE2_URL[0]=http://xzgv.browser.org/$SOURCE2
+\end{verbatim}
+
+\subsection{FORCE\_DOWNLOAD}
+FORCE\_DOWNLOAD=on
+	When set to 'on', the source will be downloaded by sorcery,
+	regardless of it being present in the spool directory.
+
+Example:
+\begin{verbatim}
+FORCE_DOWNLOAD=on
+\end{verbatim}
+
+Example:
+\begin{verbatim}
+FORCE_DOWNLOAD[2]=on
+\end{verbatim}
+for SOURCE2 not SOURCE[2]!
+
+Example:
+\begin{verbatim}
+FORCE_DOWNLOAD[n]=on
+\end{verbatim}
+for SOURCEn not SOURCE[n]!
+
+\subsection{SOURCE\_HASH}
+SOURCE\_HASH/SOURCEn\_HASH
+	The hash of the source file. Consists of
+	<algorithm>:<hash>:<verification level>. The algorithm we currently
+	use is sha512. verification level can be either WORKS\_FOR\_ME (no
+	verification done) or UPSTREAM\_HASH (source was checked against an
+	upstream provided hash).
+
+Example:
+\begin{verbatim}
+SOURCE_HASH=sha512:<hash>:UPSTREAM_HASH
+(actual hash ommited due to insane length)
+\end{verbatim}
+
+\subsection{SOURCE_GPG}
+SOURCE\_GPG/SOURCEn\_GPG
+	A signature used to verify the source file. Consists of
+	<key file>:<signature file>:<verification level>. The key file has to
+	exist in either the spell, the section or the grimoire the spell is
+	in. The signature should be in the spell or downloaded by the spell.
+	Verification level can be WORKS\_FOR\_ME, UPSTREAM\_HASH,
+UPSTREAM\_KEY,
+	ESTABLISHED\_UPSTREAM\_KEY, VERIFIED\_UPSTREAM\_KEY or
+	ID\_CHECK\_UPSTREAM\_KEY (see libunpack in sorcery for a description of
+	those levels). See Spell\_GPG\_Checking for details about how to
+	generate a key.
+
+Example:
+\begin{verbatim}
+SOURCE_GPG="gurus.gpg:$SOURCE.sig:WORKS_FOR_ME"
+\end{verbatim}
+
+\subsection{SOURCE\_IGNORE}
+SOURCE\_IGNORE/SOURCEn\_IGNORE
+	This can be used instead of SOURCE\_GPG or SOURCE\_HASH to tell sorcery
+	not to check the file. The content of this variable states the reason
+	why it shouldn't be checked. It can be one of signature (that source
+	is an upstream gpg signature), unversioned (the source changes
+	without changing its filename) or volatile (source is downloaded from
+	a version control system like cvs or subversion).
+
+Example:
+\begin{verbatim}
+SOURCE2_IGNORE=signature
+\end{verbatim}
+
+\subsection{WEB\_SITE}
+WEB\_SITE
+	Used to document the applications "official" website (if there is one).
+
+Example:
+\begin{verbatim}
+WEB_SITE=http://xzgv.browser.org/
+\end{verbatim}
+
+\subsection{ENTERED}
+ENTERED
+	This is a numerical string indicating the date this spell was
+	"officially" created. Set this to the day you submit the spell for
+	approval.
+
+Example:
+\begin{verbatim}
+ENTERED=20020406
+\end{verbatim}
+
+\subsection{UPDATED}
+UPDATED
+	This is a numerical string indicating the date this spell was last
+	changed. Used as a reference for the sorcery scripts to know if a
+	spell has been updated. (This forces a recompile so only update for
+	non-version updates that need a recompile. Version updates and
+	non-recompile-needed changes should not touch this variable.)
+
+Note: This is still supported, but shouldn't be used anymore. Instead use
+PATCHLEVEL or SECURITY\_PATCH as applicable.
+
+Example:
+\begin{verbatim}
+UPDATED=20020406
+\end{verbatim}
+
+\subsection{PATCHLEVEL}
+PATCHLEVEL
+	The number of revisions a spell has gone through without changing
+	VERSION. This defaults to 0 if ommited. Any change to a spell that
+	should trigger a rebuild on all systems using that spell should have
+	PATCHLEVEL updated. On a VERSION change PATCHLEVEL should be removed.
+
+Example:
+\begin{verbatim}
+PATCHLEVEL=2
+\end{verbatim}
+
+\subsection{SECURITY\_PATCH}
+SECURITY\_PATCH
+	The number of security related spell changes or version updates the
+	spell has gone through. This number is used by sorcery queue-security
+	to determine what spells need to be rebuilt for security reasons.
+	SECURITY\_PATCH must never be reset.
+
+Example:
+\begin{verbatim}
+SECURITY_PATCH=3
+\end{verbatim}
+
+\subsection{LICENSE}
+LICENSE[*]
+	Specifies the licenses this application has been released under.
+	Please use the acronym where applicable. The array elements
+	correspond to the different source files in the same way as the MD5
+	array elements.
+
+Example:
+\begin{verbatim}
+LICENSE[0]=GPL
+\end{verbatim}
+
+\subsection{KEYWORDS}
+KEYWORDS
+
+\subsection{SHORT}
+SHORT
+	A brief description of the spell. What it is, it's purpose etc. Used
+	primarily by the 'gaze' command of the sorcery tools.
+
+Example:
+\begin{verbatim}
+SHORT="xzgv is a GTK+/Imlib-based picture viewer for X."
+\end{verbatim}
+
+\subsection{DOCS}
+DOCS Optional tag used to override the implicit DOCS variable to change what
+docs are installed.
+
+Example:
+Implicit DOCS:
+\begin{verbatim}
+DOCS="README* FAQ* CHAN* doc* DOC* conf SETUP LICENSE COPYING NEWS"
+\end{verbatim}
+
+New DOCS:
+\begin{verbatim}
+DOCS="README* BUGS NEWS COPYING data/COPYING.* docs/html docs/example.lircrc"
+DOCS="$DOCS etc/*.conf"
+\end{verbatim}
+
+\subsection{DESCRIPTION}
+	After all of the entries have been made for the DETAILS file. The
+	last thing should be the long description for this spell. Used to
+	give a more lengthy description of what this spell is and it's common
+	uses etc. The description must be aligned to 80 characters (no line
+	should exceed 80th character).
+
+Example:
+\begin{verbatim}
+cat << EOF
+xzgv is a GTK+/Imlib-based picture viewer for X, which supports most popular
+image formats. It provides a thumbnail-based file selector, and allows panning
+and fit-to-window methods of viewing. It has mouse support as well, but can be
+used solely from the keyboard.
+EOF
+\end{verbatim}
+
+\section{CONFIGURE}
+The CONFIGURE script is sourced during a cast, after DETAILS and before DEPENDS
+and CONFLICTS. It is used to take care of more complex spells for which extra
+information must be gathered and stored. This can be needed when there are
+option ./configure switches that don't require any extra spells, or for doing
+extra things in the BUILD script. The query can be made in the CONFIGURE and
+then the flags stored can be used in any of the spell scripts.
+
+Sorcery provides a way to store and later re-store environment variables
+between different Spellbook scripts. The environment variable you want to
+persist must be marked by function persistent\_add
+
+Example:
+\begin{verbatim}
+persistent_add VAR BLAH SPELL_OPTION
+\end{verbatim}
+
+This way you marked the three variables so that they will be persisted
+
+Moreover sorcery gives you tools for querying user for information. Four
+functions are provided for your convenience:
+\begin{itemize}
+\item[config\_query]
+\item[config\_query\_string]
+\item[config\_query\_list]
+\item[config\_query\_option]
+\item[config\_query\_multi]
+this is GRIMOIRE FUNCTIONS specific for the time being
+\end{itemize}
+
+These functions do have three parameters; variable name, question presented to
+the user and default (preselected) answer. All questions will be asked in the
+positive (e.g. "Allow X", "Enable X").
+
+Example:
+\begin{verbatim}
+config_query         RMRF          "Enable forced removal?"  y              &&
+config_query_string  NAME          "What is your name?"  $USER              &&
+config_query_list    MTA           "Which mta would you like to use?"       \
+                                   qmail sendmail postfix                   &&
+config_query_option  SPELL_OPTION  "Use X?"  y  "--with-x"  "--without-x"   &&
+config_query_multi   SOMETHING     "What do you want?"                      \
+                                   all none something1 something2
+\end{verbatim}
+
+config\_query\_option is a bit different, it does not overwrite content of
+\textdollar SPELL\_OPTION, rather the result is appended to it.
+config\_query\_multi is
+different from config\_query\_list in that it makes available multiple options
+instead of just one. To use it one has to add
+\begin{verbatim}
+source $GRIMOIRE/config_query_multi.function
+\end{verbatim}
+before calling it.
+
+All config\_query* functions also mark the variable to be persistent
+automatically, and if that variable allready exists it won't ask again, just
+print out the answer from last query. If it isn't apparent then you should know
+that if you change the config\_query* call you'll also want to change the
+variable name.
+
+For more examples and functions look into /var/lib/sorcery/modules/libapi.
+
+\section{DEPENDS}
+\section{CONFLICTS}
+This file lists other spells that conflict against the spell being installed,
+which default to 'n' when asked to dispel a currently installed spell.
+
+Example:
+\begin{verbatim}
+conflicts freeglut
+\end{verbatim}
+
+and for multiple conflicts:
+\begin{verbatim}
+conflicts  freeglut
+conflicts  openglut
+\end{verbatim}
+
+You may also set the default (e.g. for a spell which conflicts with itself).
+
+Example: Set the default to 'y' when asked to dispel freeglut
+\begin{verbatim}
+conflicts  freeglut  y
+\end{verbatim}
+
+\section{PRE\_BUILD}
+The PRE\_BUILD file is executed by cast before the BUILD file.
+
+Anything necessary to prepare the spell to be built should be done here, like
+patching or unpacking additional sources. Usually this is done by adding
+commands after default\_pre\_build, which unpacks the first source
+automatically.
+
+Example:
+\begin{verbatim}
+default_pre_build                            &&
+cd  $SOURCE_DIRECTORY                        &&
+unpack_file 2                                &&
+patch  -p0  <  $SCRIPT_DIRECTORY/gcc4.patch
+\end{verbatim}
+
+Another use for this file is for spells using badly packaged sources that don't
+unpack into a directory.
+
+Example:
+\begin{verbatim}
+mk_source_dir   $SOURCE_DIRECTORY  &&
+cd              $SOURCE_DIRECTORY  &&
+unpack_file
+\end{verbatim}
+
+Many checkouts from an SCM (e.g. CVS) require you to run some setup before
+building.
+
+Example:
+\begin{verbatim}
+default_pre_build              &&
+NOCONFIGURE="X"  ./autogen.sh
+\end{verbatim}
+
+The 'NOCONFIGURE="X"' variable to autogen.sh tells autogen.sh to *not* run
+./configure, since ./configure will be run in default\_build.
+
+\section{DOWNLOAD}
+
+\section{BUILD}
+\section{PRE\_INSTALL}
+PRE\_INSTALL is responsible for removing the old version of the spell.
+Overriding the default is only necessary in very few special cases.
+
+Example:
+\begin{verbatim}
+# this is needed because save_libraries (in prepare_install) breaks because
+# valgrind has its own libpthread.so
+message  "${MESSAGE_COLOR}Preparing to install"    \
+         "${SPELL_COLOR}${SPELL}${DEFAULT_COLOR}"  &&
+
+lock_resources "libgrimoire" "install"
+
+if  spell_ok  valgrind;  then
+dispel --notriggers --nosustain $SPELL
+fi
+\end{verbatim}
+
+\section{PRE\_REMOVE}
+PRE\_REMOVE is used to prepare a spell for removal. This is only necessary in a
+few special cases.
+
+Example:
+\begin{verbatim}
+#Restore /etc/passwd when dispelling shadow
+${INSTALL_ROOT}/usr/sbin/pwunconv &&
+${INSTALL_ROOT}/usr/sbin/grpunconv
+\end{verbatim}
+
+Done in PRE\_REMOVE because those commands are installed by shadow, thus aren't
+available after the dispel.
+
+\section{POST\_REMOVE}
+POST\_REMOVE is used to do any cleanup that might be necessary after a spell is
+dispelled.
+
+As an example, gstreamer 0.8 requires plugins to be registered/unregistered to
+work, so gst-plugins has the following POST\_REMOVE:
+
+Example:
+\begin{verbatim}
+gst-register-0.8
+\end{verbatim}
+
+\section{INSTALL}
+This file controls the actual install process.  If the INSTALL file is not
+present in the spell, cast uses default\_install:
+
+Example:
+\begin{verbatim}
+make  install
+\end{verbatim}
+
+
+\section{FINAL}
+Often used to display some important follow-up action that the sys-admin may
+need to take. Also used to clean up special build directories or other cruft
+needed during the cast. You use it if you really need to do something while
+sorcery isn't looking.
+
+Example:
+\begin{verbatim}
+local  LOG=/var/log/clam-update.log  &&
+touch  $LOG                          &&
+chown  clamav  $LOG                  &&
+chmod  600     $LOG                  &&
+
+echo -e "\033[1mThis is a test of the virus scanner\033[0m"  &&
+clamscan -r -i $SOURCE_DIRECTORY/test                        &&
+echo -e "\033[1mTest complete\033[0m"
+\end{verbatim}
+
+\section{PRE\_RESURRECT}
+\section{POST\_RESURRECT}
+\section{TRIGGERS}
+Triggers are a solution to the problem that spells might need to act upon
+events happening to other spells.
+
+To this end, four triggers have been created:
+\begin{itemize}
+\item on\_cast
+\item on\_pre\_cast
+\item on\_dispel
+\item on\_pre\_dispel
+\end{itemize}
+
+And four actions that can be triggered:
+\begin{itemize}
+\item cast\_self
+\item dispel\_self
+\item check\_self
+\item run\_script <file>
+\end{itemize}
+
+These triggers are acted upon by sorcery when the events specified in the
+triggers happen. The \_pre\_ triggers are executed before the spell is cast or
+dispelled, and the others after the spell is cast or dispelled.
+
+Each line in TRIGGERS consists of
+\begin{enumerate}
+\item the trigger
+\item the spell to watch for
+\item the action to be triggered:
+\begin{verbatim}
+<trigger> <spell> <action>
+\end{verbatim}
+\end{enumerate}
+
+Or, when using action run\_script:
+\begin{verbatim}
+<trigger> <spell> run_script <file>
+\end{verbatim}
+
+Take for example the following line in nvidia\_driver's TRIGGERS file:
+
+Example:
+\begin{verbatim}
+on_cast  linux  cast_self
+\end{verbatim}
+
+If nvidia\_driver is installed and linux is cast, the above trigger causes
+nvidia\_driver to cast itself after linux is done casting.
+
+New triggers are only registered for a spell when it is cast. They are not
+automatically registered during grimoire update. If you are adding a new
+TRIGGERS file, or a line to an existing one, you may also want to update
+PATCHLEVEL in DETAILS. Most of the times, however, a new trigger shouldn't
+force a rebuild. If something breaks, cleanse will identify problems and
+suggest a recast, causing new triggers to be registered.
+
+\section{UP\_TRIGGERS}
+\section{PRE\_SUB\_DEPENDS}
+\section{SUB\_DEPENDS}
+\section{HISTORY}
+The format of HISTORY entries is as follows (all lines should be wrapped
+to <80 columns):
+\begin{verbatim}
+<date>[space]<name>[space]<e-mail address>
+[tab]*[space]<modified filename>[colon][space]<description>
+[tab][space][space]<extra description for this file>
+[tab]*[space]<modified filename>[colon][space]<description>
+[tab][space][space]<extra description for this file>
+[newline]
+\end{verbatim}
+
+Example:
+\begin{verbatim*}
+2006-11-13 Eric Sandall <sandalle@sourcemage.org>
+	* DETAILS: Updated to 1.4.3.5
+	  Changed SHORT description to not mention spell name (shorter now)
+
+2006-10-13 Eric Sandall <sandalle@sourcemage.org>
+	* DETAILS: Updated to 1.4.3.4
+	* DEPENDS: Added optional dependency on foo
+	  Removed dependency on bar (bogus entry)
+\end{verbatim*}
+
+\section{PROVIDES}
+The PROVIDES file is used to contain information about what generic
+dependencies a spell provides.
+
+The format of this file is a simple list of provider names, seperated by
+newlines.
+
+Example:
+\begin{verbatim}
+MOZILLA-BROWSER
+EMAIL-CLIENT
+WEB-BROWSER
+GRAPHICAL-WEB-BROWSER
+GECKO
+\end{verbatim}
+
+When adding a spell to an existing provider (e.g. adding a new provider for
+GECKO), *all* spells using that provider have to work with the new spell or
+need
+to be fixed.
+
+Note: due to historical reasons, another syntax using 'provides \textdollar
+NAME' is also
+supported, but should not be used.
+
+\section{Deprecation}
+(copied from http://wiki.sourcemage.org/Spell\_Deprecation)
+
+Sometimes spells need to be removed in favor of other spells, e.g. when an
+application gets renamed. This should happen automatically for users that
+have the spell installed.
+
+"old" is the spell to be removed, "new" is the spell that replaces it:
+\begin{enumerate}
+\item Create old/PRE\_BUILD, old/BUILD and old/INSTALL containing only
+	'true'.
+\item Edit old/DETAILS and comment out all SOURCE, SOURCE\_URL and HASH/GPG
+	lines.
+\item Change the PATCHLEVEL field of old/DETAILS to old PATCHLEVEL+1.
+\item Create old/DEPENDS containing only 'depends new'.
+\item Create old/TRIGGERS with 'on\_cast old dispel\_self'.
+\item Add new/CONFLICTS containing 'conflicts old y', the y makes sure the
+	spell will cast without user intervention.
+\item Put a comment into old/HISTORY that the spell is deprecated and why
+	(e.g. * Deprecated in favour of... or * Deprecated because...).
+\item If this was a spell rename, document that rename in the Grimoire
+	ChangeLog.
+\end{enumerate}
+
+When this process is used, a user casting the deprecated old will get new
+installed, removing old in the process.
+
+Change all the spells that depended in any way on the deprecated spell to
+either point to the new one or simply remove the depends if it isn't needed
+anymore.
+
+Deprecated spells should be removed from the test grimoire once the
+deprecation has made its way to stable.
+
+If the deprecation is a rename, and the old spell had some persistent
+variables from configuration settings (CONFIGURE or PREPARE), you should
+transfer those settings as defaults to the new spell. Basically, no user
+settings should be lost. So how do you do that?
+\begin{enumerate}
+\item Create old/EXPORTS and put all persistent variables you want to
+	transfer in it, one variable name per line.
+\item Create old/REPAIR\^none\^EXPORTS with the exact same content (as the
+	EXPORTS file gets read from the tablet, see REPAIR FILES).
+\item Use persistent\_read old OLD\_VARIABLE VARIABLE\_DEFAULT in new/PREPARE
+	or new/CONFIGURE.
+\item Use \textdollar{VARIABLE\_DEFAULT:-new\_default} as default setting for
+the
+	corresponding variable in the new spell.
+\end{enumerate}
+
+\section{ChangeLog}
+Any addition/deletion/move of a spell in a grimoire(s) requires a ChangeLog
+entry in the affected grimoire(s). Modifying any of the grimoire generic
+files (e.g. FUNCTIONS) or non-spell specific files (such as section-wide
+files) also requires a ChangeLog entry.
+
+The reason to include new spells in the ChangeLog, although they technically
+have their own change logs (the spell HISTORY files) is that sorcery will offer
+to show the grimoire ChangeLog on a scribe udpate. With new spells in there
+it's easy to see what's been added.
+
+The format of ChangeLog entries is as follows (all lines should be wrapped
+to <80 columns):
+\begin{verbatim}
+<date>[space]<name>[space]<e-mail address>
+[tab]*[space]<modified filename>[colon][space]<description>
+[tab][space][space]<extra description for this file>
+[tab]*[space]<modified filename>[colon][space]<description>
+[tab][space][space]<extra description for this file>
+[newline]
+\end{verbatim}
+
+Example:
+\begin{verbatim*}
+2006-11-13 Eric Sandall <sandalle@sourcemage.org>
+	* FUNCTIONS: Modifyed nspr_update to not fail if the patch doesn't
+	  exist	since firefox 2.0 does not require the nss security patch.
+
+2006-10-13 Andrew Stitt <astitt@sourcemage.org>
+	* groups: Added smgl:158 group for SMGL services
+	* accounts: Added sorcery:157:157 user for building Sorcery as a non-
+	  priviledged user.
+\end{verbatim*}
+
+\section{API\_VERSION}
+This file defines which API version a package, section, or entire grimoire
+uses. All packages below where this is defined use the stated API version
+unless a package or section below overrides it.
+
+\section{Repair files}
+Repair files are used for replacing spell files or section/grimoire libraries
+in the tablet.
+
+REPAIR files can be in spell directories, section directories or the grimoire
+base.
+
+The format of the filename is: REPAIR\^ID\^FILENAME
+
+FILENAME can be anything, its not limited to spell files, you can replace a
+patch file if you really want to.
+
+ID can be one of the four things:
+\begin{itemize}
+\item a spell's version
+\item a spell's UPDATED field
+\item the md5sum of FILENAME
+\item the exact string 'none'
+\end{itemize}
+
+The first two are relatively straightforward, if FILENAME exists in the
+spell/section/grimoire dir and the spell's version or updated field matches ID,
+then the file is replaced. If the md5sum of the file in the tablet is the same
+as ID then the file is replaced. (remember that theres a section/grimoire dir
+for each spell).
+
+If the file does NOT exist in the tablet, AND the value of ID is 'none' the
+file is added.
+
+So, you can replace any spell file, or section/grimoire library very easily
+now. It doesnt make a whole lot of sense to use the version or updated values
+for section and grimoire files, but they're there if you want it.
+
+An optimization is put in place such that if we are going to replace the file
+and the file's md5sum is the same as the repair file we skip the replace since
+the replace has presumably already been done.
+
+Cache files are not updated at this time.
+
+The entire tablet is scrubbed after each scribe update. `cleanse --tablet` also
+will do this. There is an additional option to cleanse, --tablet\_spell which
+takes a single parameter as a spell name to scrub so you can quickly verify
+that things are working without scrubbing the entire tablet.
+
+\subsubsection{TODO}
+\begin{itemize}
+\item[all]
+Allow special keyword 'all' to unconditionally update a file in the tablet, bug
+10869
+\item anything else that changed
+\end{itemize}
+
+Repair files dont apply to trigger registration, which is done during cast,
+they repair files that will be executed at a later date. So there is little
+point in repairing TRIGGERS or UP\_TRIGGERS.
+
+\section{FUNCTIONS}
+A grimoire library for commonly used functions and readability functions.
+Functions may be added if they are used in more than one package (e.g.
+mozilla\_remove\_nspr\_nss is used for all Mozilla products).
+
+\chapter{Filters}
+\section{excluded}
+
+Example:
+\begin{verbatim}
+	^/home
+\end{verbatim}
+
+\section{protected}
+
+Example:
+\begin{verbatim}
+	^/bin/awk$
+\end{verbatim}
+
+\section{volatiles}
+This filter contains a list (can be regular expressions) of files that are
+known to change (e.g. gconf configuration files, modified by almost every
+GNOME package). We know these files will change and that they are supposed
+to change, so here we mark them so `cleanse` is aware and will not report
+them as broken.
+
+Example:
+\begin{verbatim}
+	^/etc
+\end{verbatim}
+
+This marks all files in /etc as known to be changeable and still be
+considered okay.
+
+\chapter{Compatibility}
+\section{libcompat}
+This library is used for forward compatibility with the next release of
+Sorcery. Dummy functions for future Sorcery functions are added here so
+that the grimoire developers may work in advance to have these features
+supported once the new features are available in a stable Sorcery release.
+
+\section{libgcc}
+This library adds multi-gcc version support (used to set which gcc version
+a package is compiling with).
+
+\chapter{Accounts}
+\section{libaccount}
+This grimoire library contains functions for creating, checking, and
+retrieving information about account and group information.
+
+\section{accounts}
+Accounts used by programs (usually daemons) during their operation. When
+adding an account with a group, add the group first as you will need to
+know the group id (GID) in advance. The format of account entries is:
+	<account>:<UID>:<Primary GID>:<GID>:<GID>:... etc.
+where UID is the prior listed UID + 1.
+
+Example:
+\begin{verbatim}
+musicdaemon:155:29
+iplog:156:156  <--- This is the one we just added
+(note that the GID is from the groups example below)
+\end{verbatim}
+
+\section{groups}
+Groups used by programs (usually daemons) during their operation. The format
+of group entries is:
+\begin{verbatim}
+<group>:<GID>:
+\end{verbatim}
+where GID is the prior listed GID + 1.
+
+Example:
+\begin{verbatim}
+powerdev:155:
+iplog:156:  <--- this is the one we just added
+\end{verbatim}
+
+\chapter{Appendix}
+\begin{itemize}
+\item File Hierarchy Standards
+	See http://www.pathname.com/fhs/2.2/
+\item Keywords
+	See http://wiki.sourcemage.org/Keywords
+\item Licenses
+	See http://wiki.sourcemage.org/LicenseList
+\item Linux Standards Base
+	See http://www.freestandards.org/en/LSB
+\end{itemize}
+
+\end{document}