This is the wiki version of the Source Mage intro document (draft) soon to be shipped on and installed by our ISOs. Soon to be on p4. For now, feel free to comment and/or edit

Please try to wrap lines at 80 characters, this is:

1234567890123456789012345678901234567890123456789012345678901234567890123456789X
                                                                          here ^

---

Comments / ToDo

• Should the sorcery part stay where it is?

• We need sections on scribe and cleanse

---

Structure Plan

Here's how the manual should be constructed so it will be clear and easy to follow:

1. Welcome & intro text. * Done!

2. Basic terms. Small introduction to how the following terms are relevant. * Done!

   • Spell. Short description: "Spells are Source Mage packages, which..."

   • Grimoire. "Grimoires are collections of spells..."

   • Codex. "The Codex is made up of different grimoires..."

3. Sorcery. "Sorcery is a set of tools used to administer a Source Mage system... The most relevant are:"

   • sorcery - Short description.

   • scribe - Short description.

   • gaze - Short description.

   • cast - Short description.

   • dispel - Short description.

   • cleanse - Short description.

4. Here follows a step-by-step example of a cast (of some spell many users actually need after install). It should also include example actions of the tools listed above.

Notice: Above sketch is still unfinished and unpolished. One problem is where to include info about a system rebuild. Should it belong in this document at all? If not, where? If yes, where? Will the small reminder displayed after install be sufficient in the future also?

---

New text according to above plan

Introduction

Welcome to Source Mage GNU/Linux and congratulations on a succesful install!

This is a brief introduction to Source Mage (SMGL). It will only cover those subjects required for basic use. For a more in-depth look, please see the manpages, the wiki at http://wiki.sourcemage.org, and the SM-Users mailing list at http://lists.ibiblio.org/mailman/listinfo/sm-users. You are also welcome to join our IRC channel #sourcemage on irc.freenode.net, where you'll find active support for most of the time.

Basic Terminology

The Source Mage tagline is: Linux so advanced, it may as well be magic. Basic terminology is similarily magic-oriented. Program packages are called spells, and a collection of spells is called a grimoire. All installed grimoires likewise make up the codex.

Installing a spell is called casting, and removing it is called dispeling. Such terms are not only figures of speech, though: cast and dispel are also the programs used to perform the said tasks.

Spells

A spell is simply a directory containing script files that are used for downloading, unpacking, configuring, compiling, and installing a program. The actual source is not included in the spell, but is downloaded directly from the program's own website.

Spells are stored in section directories inside the grimoire directories. The grimoires themselves are located in the codex directory /var/lib/sorcery/codex. For instance, the spell from stable grimoire for the GNU C compiler, called gcc, is located in /var/lib/sorcery/codex/stable/gnu/gcc.

Different grimoires exist for different kinds of spells. The stable and test grimoires contain spells for most programs. Non-Free and/or binary spells belong in the z-rejected grimoire, and games belong in the games grimoire.

The Sorcery Suite of Scripts

The Source Mage collection of system tools is called Sorcery. It contains utilities for different system management tasks whose names reflect SMGL's "magical" theme. The main program, used for modifying core system behavior, is also named sorcery.

The utilities you'll need the most in everyday use are:

• sorcery

  • The command sorcery opens a menu where you can modify the behavior and appearance of all Sorcery tools. Also available are e.g. compiler optimization settings, as well as a menu-based interface for spell management. sorcery also has command-line options that are used e.g. for doing system updates.

• cast

  • Casting spells, an activity most other distributions refer to as "installing packages", is done with cast. Generally this means typing 'cast spellname', answering a some queries pertaining to the spell, and allowing the cast to download, compile, and install the program.

• dispel

  • Uninstalling spells is done with dispel. It operates like cast, with the difference that there usually aren't any queries to answer, and it takes a lot less time than casting.

• gaze

  • Gaze is used to retrieve information about spells or about your system. For example you can use gaze search phrase and gaze will search all available packages for mention of the phrase you entered. You can read any spell's description by doing gaze what spellname.

• scribe

  • Scribe is a utility for controlling the grimoires in your codex, and the spells in your grimoires. For example, you can use scribe add stable to add stable to your grimoires. scribe remove stable would then remove it. Scribe is also used for updating the spells in your grimoire using the command scribe update.

You can see all available options for each utility by typing '<program> --help'.

---

The old text

Welcome to Source Mage GNU/Linux and congratulations on successfully
installing it!

This is just a quick intro to Source Mage (SMGL). Now that you've
installed it, let's learn how to get through daily work in SMGL. We'll
just cover the essentials here, for a more thorough discussion see
the manpages, the wiki at wiki.sourcemage.org, our mailing lists at
sm-users@lists.ibiblio.org (subscribe before asking questions), or
ask on our channel #sourcemage on the network irc.freenode.net.

1. Basic terms

grimoire        
codex           
spell           
sorcery         

2. sorcery

Sorcery is the main program of the SMGL package manager. Calling just
"sorcery" brings up a menu where you'll usually go on to Options and
configure things.
"sorcery update" updates /only/ the sorcery package manager, but not
the package listings (the codex, or grimoires).
"sorcery system-update" updates the package manager, the package lists,
and rebuilds all packages that need updating.

3. cast

Cast is the main workhorse in SMGL. Its main use is installing spells.

For example, running "cast irssi" will ask a few questions how you want
"your" irssi built, and then compile the irssi IRC client.

4. dispel

Now that we've learned how to install spells, maybe it would be nice to
know how we can remove them again. The command for this is "dispel".

For example, "dispel irssi" will remove irssi again.

5. gaze

Okay, we can install and remove spells. But how do we know which spells
we want to install? This is where "gaze" comes in.

Gaze is the main tool to retrieve information about your SMGL system.
To get a (long) list of all the available packages, grouped by section,
use "gaze grimoire".
If you've found a cool-sounding name and wonder what it is, use
"gaze what".

For example, "gaze what irssi" gives you a description of the irssi spell.

6. cast revisited

If you've played around with cast a bit, you may notice two things:

 - If you installed a spell sometime before, cast will often just
   "resurrect" it instead of recompiling.

This is a sorcery feature called "archive". Cast will create a compressed
tar archive of all the files a spell installs in /var/cache/sorcery/.
If it should install a spell when you already have a so-called "cache" file
in there, it will just unpack the cache.
To avoid this, pass the parameter -c to cast ("cast -c irssi" for example)

 - If you cast a spell you cast before, some of the questions will
   just be skipped and your previous answers filled in.

Cast remembers the answers you gave previously. To avoid bombarding you
with questions again, it will just quietly re-use answers you gave before.
Of course, this may be bothering sometimes, if you want to change one
of the parameters. Just pass -r as a parameter.

7. prompting

Oh, while we're on the subject: The prompts in cast and other tools do
time out (accept the default) after some time, but the delay for that
is set quite high by default. To change it, run "sorcery", go to "Options"
and "Prompt Delay", and enter a new value.

You may also not want/need the queries "do you want to view the compile
log for XY" at the end of a cast, or "do you want to add -- options to
./configure" at the beginning of one.
To turn those off, go to "Feature Menu" in the options menu, and turn off
"VIEW_REPORTS" (for viewing compile logs) and/or "CONFIG_LOC" for
./configure options.

8. gaze revisited

What if you want to find a spell for a certain task? You either look
through the spells in the section that the task would belong to, or use
the "gaze search" command. There's two ways to use this:

gaze search <term>
  This will search in all spell descriptions for the given term. This
  takes a while, although searching for something else shortly afterwards
  is quite a bit faster, due to the way linux does disk caching.
  Example:
    "gaze search gopher" for programs that understand the "gopher" protocol.

gaze search -name <term>
  This will just search for a term in all spell names. This is considerably
  faster than searching all descriptions.
  Example:
    "gaze search -name vorbis" for programs for the ogg vorbis audio codec.