Source Mage code commit list

[Justin Boffemmyer <scm AT sourcemage.org>]

GIT changes to master grimoire by Justin Boffemmyer <flux AT sourcemage.org>:

 ChangeLog                          |    2 
 smgl/smgl-setup/BUILD              |    1 
 smgl/smgl-setup/DETAILS            |   16 ++
 smgl/smgl-setup/HISTORY            |    2 
 smgl/smgl-setup/INSTALL            |    4 
 smgl/smgl-setup/PRE_BUILD          |    1 
 smgl/smgl-setup/files/smgl-setup.7 |  284 
+++++++++++++++++++++++++++++++++++++
 7 files changed, 310 insertions(+)

New commits:
commit da9450bd77e0dc925857f60ea756fde2a041e8e1
Author: Justin Boffemmyer <flux AT sourcemage.org>
Commit: Justin Boffemmyer <flux AT sourcemage.org>

    smgl-setup: new spell, smgl intro man page

diff --git a/ChangeLog b/ChangeLog
index 9b03f5f..4201ab5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,5 @@
+2008-12-01 Justin Boffemmyer <flux AT sourcemage.org>
+       * smgl/smgl-setup: new spell, smgl intro man page
 
 2008-11-30 Thomas Orgis <sobukus AT sourcemage.org>
        * audio-soft/meterbridge: New spell, monitoring jack audio.
diff --git a/smgl/smgl-setup/BUILD b/smgl/smgl-setup/BUILD
new file mode 100755
index 0000000..27ba77d
--- /dev/null
+++ b/smgl/smgl-setup/BUILD
@@ -0,0 +1 @@
+true
diff --git a/smgl/smgl-setup/DETAILS b/smgl/smgl-setup/DETAILS
new file mode 100755
index 0000000..dbfad40
--- /dev/null
+++ b/smgl/smgl-setup/DETAILS
@@ -0,0 +1,16 @@
+           SPELL=smgl-setup
+         VERSION=0.1
+   SOURCE_IGNORE=unversioned
+         LICENSE=GPL
+        WEB_SITE=http://www.sourcemage.org/
+     GATHER_DOCS=off
+         ENTERED=20081126
+        KEYWORDS="smgl"
+           SHORT="Source Mage GNU/Linux initial setup manpage"
+cat << EOF
+This is the initial setup manpage for Source Mage GNU/Linux. It will walk you
+through the steps needed to finish setting up and customizing a Source Mage
+system. This is particularly useful after a fresh install of SMGL, but is 
also
+handy when you want to change a setting but don't remember where it would be.
+Experienced SMGL users probably don't need to read this man page.
+EOF
diff --git a/smgl/smgl-setup/HISTORY b/smgl/smgl-setup/HISTORY
new file mode 100644
index 0000000..0c0ebbf
--- /dev/null
+++ b/smgl/smgl-setup/HISTORY
@@ -0,0 +1,2 @@
+2008-11-26 Justin Boffemmyer <flux AT sourcemage.org>
+       * DETAILS, INSTALL: spell created
diff --git a/smgl/smgl-setup/INSTALL b/smgl/smgl-setup/INSTALL
new file mode 100755
index 0000000..c737599
--- /dev/null
+++ b/smgl/smgl-setup/INSTALL
@@ -0,0 +1,4 @@
+SOURCEDIR="$SCRIPT_DIRECTORY"/files
+DESTDIR="$INSTALL_ROOT"/usr/share/man/man7
+
+install -v -m 0644 -D "$SOURCEDIR"/smgl-setup.7 "$DESTDIR"/smgl-setup.7
diff --git a/smgl/smgl-setup/PRE_BUILD b/smgl/smgl-setup/PRE_BUILD
new file mode 100755
index 0000000..27ba77d
--- /dev/null
+++ b/smgl/smgl-setup/PRE_BUILD
@@ -0,0 +1 @@
+true
diff --git a/smgl/smgl-setup/files/smgl-setup.7 
b/smgl/smgl-setup/files/smgl-setup.7
new file mode 100644
index 0000000..820f99f
--- /dev/null
+++ b/smgl/smgl-setup/files/smgl-setup.7
@@ -0,0 +1,284 @@
+.\" To see this man-page formatted, run it through
+.\" groff -man -Tascii | less -r
+.\"
+.\" Change Month, Day, Year to time of editing.
+.TH SMGL-SETUP \
+7 \
+"October 12, 2008" \
+"SMGL User Manual" \
+"Source Mage GNU/Linux User Manual"
+
+.SH NAME
+.B smgl-setup
+- basic introduction to configuring Source Mage GNU/Linux
+
+.SH DESCRIPTION
+.B Welcome to Source Mage GNU/Linux!
+
+This man-page describes the steps that you can/should take for a newly 
installed Source Mage GNU/Linux system. After finishing the minimal 
installation from the ISO itself, there is still a lot of work to be done on 
the part of the user to bring the system to a more usable/polished state. 
This includes configuring the system, setting up networking, etc. Each 
section below will describe different things you can do with your new system.
+
+.SH SYSTEM CONFIGURATION
+The Source Mage installation provides some default settings for a baseline 
system (such as EDITOR=nano). Now would be a good time to configure some of 
those settings to suit your own tastes. Note that you can do these before or 
after updating your system, though it is recommended that you configure some 
of these (such as your text editor and timezone) before doing anything else.
+.\"
+.SS Default Text Editor
+
+You can change the default text editor either globally, by editing the
+.IR /etc/profile.d/editor.sh
+script, or per user, by setting the
+.B $EDITOR
+environment variable in your
+.I .bashrc
+or equivalent. The default text editor set by the installer is
+.BR nano .
+Make sure that you have your preferred text editor installed else you will 
get errors for trying to use an editor that doesn't exist on your system.
+.\"
+.SS System Logger
+
+You may optionally want to install a system logger. You can have more than 
one logger installed at a time, but you can only have one of them running 
(enabled) at a time or they will conflict with each other. Some spells 
(optionally) depend on having a system logger, so it is recommended that you 
install one. You can view the possible system logging providers by running:
+.IP
+.B gaze provides SYSTEM-LOGGER
+.\"
+.SS /etc/sysconfig/
+
+This directory is full of configuration files that provide different 
settings for your entire system. Some files you might want to edit would be:
+.IP
+.B facilities
+- setup which programs should provide different services such as system 
logging and default display manager
+
+.B hwclock
+- set whether the hardware clock stores time in UTC format
+
+.B keymap
+- sets the keymap to use in the console, as well as the font and whether 
UTF-8 should be enabled or not
+
+.B locale
+- define various locale information
+
+.B init
+- configure the init process, such as the default run level
+
+.B shutdown
+- configure whether to power off or just halt when shutting down
+.\"
+.SS Timezone
+
+You can setup your system's timezone by following these steps. Look for your 
timezone in
+.IR /usr/share/zoneinfo.
+Copy or link that timezone to the
+.IR /etc/localtime
+file by running this command as root (using Asia/Manila as an example):
+.IP
+.BR cp " (or" " ln -sf" )
+.I /usr/share/zoneinfo/Asia/Manila /etc/localtime
+.PP
+Verify that everything is working correctly with the
+.BR date (1)
+command.
+
+.SS Networking
+
+Source Mage has recently switched to a simpler system for managing network 
connections using the Debian-based ifupdown interfaces system. This basically 
involves editing the
+.I /etc/network/interfaces
+file to configure what the
+.BR ifup (8)
+and
+.BR ifdown (8)
+commands would do. The
+.BR interfaces (5)
+man page explains how to write the file. Example configurations are also 
provided in the
+.I /usr/share/doc/ifupdown/examples/
+directory, specifically the
+.B network-interfaces
+file.
+
+.SH SYSTEM UPDATE
+
+Once you are able to connect to the Internet, you can start upgrading your 
system to the latest stable versions of the grimoires and sorcery or switch 
to other branches. This is done through the
+.BR scribe (8)
+and
+.BR sorcery (8)
+commands as described below.
+.\"
+.SS Updating Grimoires
+
+A
+.B grimoire
+is Source Mage's repository of spells and is managed using the
+.BR scribe (8)
+command. By default, only the
+.B stable
+grimoire installed, but the version might be a bit dated by the time you 
have installed Source Mage. The command
+.IP
+.B scribe update
+.PP
+will update all
+.B grimoires
+installed on your system. You can add other
+.B grimoires
+like the
+.B test grimoire
+by running:
+.IP
+.B scribe add test
+.PP
+More information about managing
+.B grimoires
+can be found in the
+.BR scribe (8)
+man page.
+.\"
+.SS Updating Sorcery
+.BR sorcery (8)
+is Source Mage's package management suite. Make sure that it is up-to-date 
by running:
+.IP
+.B sorcery update
+.PP
+You can choose which branch of sorcery to use through the
+.B sorcery
+menu. Run
+.IP
+.B sorcery
+.PP
+and go to the
+.I Option
+menu and then select
+.IR "Sorcery Branch" .
+Be sure to update sorcery every time you switch branches. In case something 
causes the update to fail and your sorcery scripts are lost, run the 
following command to restore them:
+.IP
+.B bash
+.I /root/sorcery.restore
+.\"
+.SS Configuring Sorcery Options
+.B Sorcery
+lets you fine-tune compilation options to your hardware and your personal 
preferences. This is easily done through the
+.BR sorcery (8)
+menu. Run the command
+.IP
+.B sorcery
+.PP
+And go to the
+.B Options
+menu. Here you are presented with a lot of options to customize how sorcery 
functions or how spells are cast. There are a few worth mentioning:
+
+.B Optimize Architecture
+
+Here you will be able to choose a microprocessor category, some pre-defined 
optimization options, as well as additional options that you would want to be 
passed to the compiler.
+
+.B Feature Menu
+
+This lists some Sorcery features which you can toggle on or off. For 
example, you can choose whether Sorcery will create archives of installed 
software or whether to use ccache for accelerated upgrade compilations (
+.B ccache
+must be installed for this to work).
+
+.B Prompt Delay
+
+While casting spells, Sorcery will ask you questions regarding features or 
actions to be taken. It will wait for a given amount of time for you to 
answer before continuing the cast, using the default answer (varies from 
spell to spell) if you don't respond before it times out. This feature allows 
you to set how long, in seconds, Sorcery has to wait before proceeding 
(choose 0 to have sorcery just use the default values immediately - you won't 
be able to change any settings when casting spells if you do this though).
+
+.B Tip:
+The status message at the bottom of the screen gives a brief explanation 
about each option. Feel free to play with various options, but be aware that 
if you don't know what you are doing with some of the options, you could end 
up with drastically different results than you might expect. You can leave 
most settings, besides the compile options, at the default and things should 
run just fine.
+.\"
+.SS Rebuilding the system
+After you have updated your
+.B grimoire(s)
+and
+.B sorcery,
+you may choose to rebuild all the spells installed on your system. This step 
is optional, but recommended. If you choose not to rebuild your system, then 
the options you selected for sorcery will not take effect until the next time 
the spell is compiled (either by forcing a recompile of the spell with:
+.IP
+.B cast -c [spell]
+.PP
+or by upgrading to a new version of the spell). You can rebuild every spell 
in the system by issuing the following command:
+.IP
+.B sorcery rebuild
+.PP
+Optionally, you can first rebuild the toolchain before rebuilding the whole 
system. This will ensure that the toolchain will be using whatever 
optimizations you set in
+.BR sorcery (8)
+when it recompiles the rest of the system. You can rebuild the toolchain by 
running:
+.IP
+.B cast -c binutils gcc gettext glibc
+.PP
+After it's done, you can rebuild the system as indicated above.
+
+.SH BEYOND A BASE INSTALL
+
+You should now have fully working and updated base system, ready to be 
expanded to your personal needs, whether for a desktop, a server, or anything 
else. Where you go from here is really up to you. Add more
+.B grimoires
+with
+.BR scribe (8),
+search and view spells using
+.BR gaze (1),
+or install or remove spells using
+.BR cast (8)
+and
+.BR dispel (8).
+Here are a few suggestions you might be interested in.
+.\"
+.SS Command line chatting and surfing
+
+Whether you are a command line type of person, or merely waiting for a 
proper graphical interface to finish casting, you can still enjoy the use of 
your newly set up Internet connection to go online. You can chat on IRC with
+.B irssi
+and browse the web with one of many text browsers, such as
+.B w3m,
+.B elinks,
+or
+.B lynx.
+For example,
+.IP
+.B cast irssi elinks
+.PP
+will install both
+.B irssi
+and
+.B elinks.
+.\"
+.SS X Window System
+
+Most window managers and desktop environments rely on the X Window System 
for graphical capabilities. If you are using the
+.B stable grimoire,
+you can install (monolithic) Xorg by running
+.IP
+.B cast xorg
+.PP
+On the other hand, if you are using the
+.B test grimoire,
+you can get the newer (modular) Xorg with
+.IP
+.B cast xorg-server
+.PP
+Note that you do not have to manually cast X if you are casting a spell that 
depends on X (such as a window manager or desktop environmenkde4-profile
+- for KDE 4
+
+.B xfce4-profile
+- for Xfce 4
+.PP
+To install one of the desktops, for example Xfce 4, run the command
+.IP
+.B cast xfce4-profile
+.PP
+.B Note about KDE 4:
+In order for a user to be able to use KDE 4, that user must belong to the
+.I kde4
+group. Add a user to the kde4 group with this command:
+.IP
+.B gpasswd -a [username] kde4
+.PP
+.\"
+.\" The following commands should be uncommented and
+.\" used where appropriate.
+.\" This next command is for sections 1, 6, 7 and 8 only.
+.\" .SH ENVIRONMENT
+.\" .SH FILES
+.\" .SH EXAMPLES
+.\"
+.SH SEE ALSO
+.BR scribe (8), \ sorcery (8), \ gaze (1), \ cast (8), \ dispel (8)
+.PP
+Visit the Source Mage GNU/Linux website:
+.I http://www.sourcemage.org
+.\"
+.\" .SH STANDARDS
+.\" .SH HISTORY
+.\"
+.SH AUTHORS
+The Tome and Cauldron Teams of Source Mage GNU/Linux
+.\"
+.\" .SH BUGS