Gaze is a command used for retrieving information from various sorcery-related sources, such as the Grimoire. Gaze is the most complex command in Sorcery, because it has so many different command line options.

For purposes of this discussion, it is worth breaking the Gaze option set into two main categories: those that retrieve information from the Grimoire and those that retrieve information about the system.

Gaze commands that use the ["Grimoire"]:

search

• Usage: "gaze search <phrase>" Gaze search will look through the long descriptions of all the spells in the grimoire for <phrase>. Searches are not case-sensitve; thus "gaze search nvidia" will find the spells NVIDIA_GLX and NVIDIA_kernel, and so will "gaze search nVidia".

what

• Usage: "gaze what <spellname>" Gaze what will print out the long description of the specified spell. For example saying "gaze what w32codec" will print out w32codec contains codecs used for decoding video & audio streams on i386+.

where

• Usage: "gaze where <spellname>" Gaze where prints out the section of the Grimoire that the spell is found in. So "gaze where kdebase" will tell you kde.

website

• Usage: "gaze website <spellname>" Gaze website prints out the URL of the spell's official website. So "gaze website xfree86" says http://www.xfree86.org/.

section

• Usage: "gaze section <sectionname>" Gaze section generates a list of all the spells in a section of the Grimoire. So "gaze section kde" will print out all the spells in the KDE section. For sections with many spells (i.e. most of them), it would be a good idea to say "gaze section <sectionname> | more" unless you can read as fast as your computer can print things to the screen.

sources

• Usage: "gaze sources <spellname>" Prints out a list of the source files for the spell. Does not include dependencies; "gaze sources MPlayer" will print out the main source file, the skins, and so on, but not tell you that it depends on w32codec.

service

• Usage: "gaze service <service-name>" OR "gaze service <port>" Prints out a list of programs that deal with the specified service or port. Thus, "gaze service ftp" will print out a list of FTP server programs, and "gaze service 80" will print out a list of HTTP servers.

grimoire

• Usage: "gaze grimoire" Gaze grimoire shows you the contents of the entire Grimoire, divided up by section. You can scroll up and down the list with the arrow keys. Press "Q" to quit and return to the command line.

html

• Usage: "gaze html" Actually, the generic usage of "gaze html" is not very useful, since it just prints out the entire Grimoire as an HTML file to the screen. Unless you can read really fast -- AND visualize web pages in your head based solely on the source code -- it might be more useful to say "gaze html > ~/grimoire.html" and then look at the file with a web browser.

$SPELL_SCRIPT

• Usage: "gaze $SPELL_SCRIPT <spellname>" This command displays the $SPELL_SCRIPT for the given spell. $SPELL_SCRIPT is the filename of the particular script you wish to view. e.g: "gaze DETAILS gcc"

maintainer

• Usage: "gaze maintainer <sectionname>" This command displays the maintainer for the given section.

history

• Usage: "gaze history <spellname>" This command displays the HISTORY file for the given spell.

Gaze commands that gather info from the system:

alien

• Usage: "gaze alien" Gaze alien searches out files on the computer that were NOT installed by Sorcery (e.g. not with a cast or sorcery update). Depending on what all you've installed, this list could be quite long. A recent "gaze alien" on my box found 5,844 non-sorcery files, so it might be a good idea to say "gaze alien > ~/alien.txt" instead and then look at it with your favorite editor. __ Currently gaze alien will list all of the files under /var/lib/sorcery/grimoire as alien files. I suspect this has to do with the recent upheaval, and will probably change before long.

from

• Usage: "gaze from /path/to/filename" Gaze from tells you which spell installed a file. If the file was not installed by sorcery, it will not say anything; it will simply exit back to the command line.

install

• Usage: "gaze install <spellname>" Gaze install will display the install log of the spell. The log consists of a list of all files and directories that were created by the spell. You can scroll up and down the list with the arrow keys. Press "Q" to quit back to the command prompt.

installed

• Usage: "gaze installed" Gaze installed displays a list of all the programs that have been sorcerously installed on the system. You can scroll up and down the list with the arrow keys. Press "Q" to quit back to the command prompt.

compile

• Usage: "gaze compile <spellname>" Gaze compile lets you view the compile log of the spell, which consists of all of the commands issued to compile the program. This is particularly useful for de-bugging spells you are writing. Arrows scroll up and down, Q quits.

export

• Usage: "gaze export" Gaze export creates a snapshot of the current system configuration, in a file called:

• ~/snapshot-<HostName>-<Year><Month><Date>.tar.bz2

  • The snapshot contains information about the current system setup and how to duplicate it later. The file can get large -- mine is 9 MB. I suspect this is meant to be used by sysadmins setting up many identical boxen. You create a system snapshot on one machine, copy it to the other systems, import, and there you go -- a clone of the original box.

import

• Usage: gaze import <snapshot-file> Gaze import restores a system from a snapshot taken with gaze export. I have not tried it, so I can't tell you how well it works.

voyeur

• Usage: "gaze voyeur <spell>" If [voyeur mode] is turned off, this allows you to look at the compilation messages of the spell.

pam

• Usage: "gaze pam" Prints out a list of installed spells that use PAM. PAM=Pluggable Authentication Modules (see http://www.kernel.org/pub/linux/libs/pam/FAQ).

orphans

• Usage: "gaze orphans" Gaze orphans generates a list of all the installed programs which are not dependencies of other programs.

md5sum

• Usage: "gaze md5sum <spellname>" Gaze md5sum will print out the md5 sums of all of the files that the spell installed. Presumably this information could be used to verify the integrity of those files, though I don't see how without an original sum to compare against. With large spells, it's best to redirect the output: "gaze md5sum <spellname> > ~/<spellname>sums.txt".

  Note: This command is used internally to generate the files used to verify integrity.

And there are some gaze options that don't fit clearly into the two categories above:

prune

• Usage: "gaze prune" Gaze prune deletes all old sources from /var/spool/sorcery and all old backups from /var/cache/sorcery. If you use this, you will have to download fresh copies of the source code if you suddenly need to recompile a spell. However, it can be useful for freeing up disk space.

newer

• Usage: "gaze newer yyyymmdd" This returns the name of all spells in the [Grimoire] with an ENTERED date greater than the supplied date. "gaze --help" shows the syntax as "gaze newer 20020521" - This is an example usage to show spells with an

  • ENTERED date greater than the 21st May 2002.

  Perhaps the bashers can look at this as my first thought is that it should be checking against the UPDATED field not the ENTERED one. It might also be an idea to make the --help clearer using the yyyymmdd description. (Mark Andrews)

older

• Usage: "gaze older <yyyymmdd>" This returns all spells that were [Cast] prior to the supplied date. "gaze --help" shows the syntax as "gaze older 20010521" - This is an example usage to show spells [Cast] prior

  • to the 21st May 2002. Again, this could be made clearer in the --help.

    It seems odd that these two commands (older and newer) select from different places. Maybe there should be :-

    • >speculative commands below<

      • "gaze newer <yyyymmdd>" (for [Grimoire]) "gaze older <yyyymmdd>" (for [Grimoire]) "gaze after <yyyymmdd>" (for [Cast] spells) "gaze prior <yyyymmdd>" (for [Cast] spells)

      • >speculative commands end<

  Something else for the bashers to consider (Mark Andrews)

version

• Usage: "gaze version <spellname>" gaze version will print out the version of the specified spell in the currently used grimoire.

sum

• Usage: "gaze sum <spellname>" Gaze sum prints out a list of the filenames installed as part of that spell. Each one is preceded by two numbers, whose significance are not defined. I have no idea what this is supposed to be for. Something about disk usage, maybe? Somebody please elaborate. When using this command on a large spell, it's best to redirect the output to a file, for example "gaze sum <spellname> > sum-output.txt" -- a recent sum of xfree86 on my machine generated 10,478 lines of output.