Note
This documentation reflects the legacy implementation of stl. See Status Logger Use and Operation for the current implementation.
This document provides an overview of stl from the perspective of the user concerning both the script itself as it exists in “stock” format, and how many will choose to customize the script. See “zsh stl Internals (Legacy)” for more information on the underlying functions, operation, and the code paths of the script.
This section describes the invocation and purpose of various stl commands, ignoring most of the internals of the script.
Note
While you may want to set up interfaces for calling stl directly, in most cases stl will run fairly regularly as a cron job.
stl commands take the following basic form:
stl [domain] [worker] [project] [options]
The elements of this command are:
You may omit this layer in some cases, but is useful if you need to maintain two separate log files, with two separate sets of projects.
If this term does not match one of the defined commands, then the program exits with help text.
In the default implementation this is either “make”, “stats”, report”, or “output” and defines the major fork in the behavior of the program. “make” will build a project, while “stats” provides access to word count and latest build times, “report” displays the output of the last build, while “output” is responsible for modifying the default output style.
The default worker option is “stats”.
A keyword that defines each project. stl requires this option for successful output. The make worker only accepts one argument, while stats can handle multiple projects in some cases.
Some workers, accept additional arguments or messages.
The stats worker is the default and returns statistics about your projects. The options are:
The entry worker provides the capacity for recording arbitrary message to the log. The options are:
The make worker runs a specific build routine for a project, you will configure options by default when setting up the project. For sphinx projects, the make worker provides the following options:
These correspond directly to a target in the default Makefile that sphinx-quickstart generates. You may specify multiple options to generate multiple outputs. The ikiwiki builder uses the remainder of the command line argument as string that becomes the commit message for the wiki’s git repository.
The report worker provides an interface to view the build reports generated by previous runs of the make worker. report always displays only the last build for whatever project you specify. You must specify one of the following log viewers.
The example stl included here is reasonably generic, but all users will need to customize the code at least a little. All user customizable code resides at the bottom of the file. Continue for more detail on these customizations.
At the very end of the file the following “main” function, which is the user’s entry into the code, which resembles the following:
main(){
ARG=($@)
case $ARG[2] in
( make ) ACTION=make ;;
( stat* ) ACTION=stats ;;
( entry* ) ACTION=entry ;;
( report ) ACTION=report ;;
( * ) ACTION=stats ;;
esac
domain=$ARG[1]
ARG[1]=()
case $domain in
( tycho ) tycho-worker $ARG; exit 0 ;;
( job ) job-worker $ARG; exit 0 ;;
( * ) echo "help text"; exit 1 ;;
esac
}
main $@
The first case statement sets a variable that the action-handler function uses. The second case statement selects the domain.
If you modify the first statement, add corresponding code to the action-handler function. action-handler calls the functions that do something (i.e. “actions.”) The second case statement simply passes arguments to the next user customizeable function, which is the “domain-selector.”
For the the first case statement, it’s important to set a good default (i.e. stats) as most invocations of the program will be “stats” operations, and the action function itself can handle errors more clearly. For the second operation, it makes sense to produce an error, because if one there is no domain, there is no way to proceed.
See “tycho-selector”, which is an example “domain-selector” function:
tycho-selector(){
PROJECT=projects
LOG_TAG=tycho
for argument in $ARG; do
case "$argument" in
( ae ) queue=($queue al-edarian); shift ;;
( mars ) queue=($queue knowing-mars); shift ;;
( admin ) queue=($queue cyborg-admin); shift ;;
( gmg|mg ) queue=($queue mediagoblin);
WC_PATH=~/projects/mediagoblin/docs/source
shift ;;
( rhizome ) queue=($queue rhizome); shift
PROJECT_PATH=~/assemblage/rhizome/
WC_PATH=$PROJECT_PATH
BUILD_TYPE=wiki; EXTENSION=mdwn
;;
( assemblage|ass ) queue=($queue assemblage); shift
PROJECT_PATH=~/assemblage/
WC_PATH=$PROJECT_PATH
BUILD_TYPE=wiki; EXTENSION=mdwn
;;
( wikish|wiki ) queue=($queue wikish); shift
PROJECT_PATH=~/wikish/
WC_PATH=$PROJECT_PATH
BUILD_TYPE=wiki; EXTENSION=mdwn
;;
( * ) # continue silently ;;
esac
done
action-handler $@;
}
The “domain-selector” functions set variables that describe the sub-projects in the domain that the “actions” use. The main reason to have separate projects is to be able to log statistics into separate files.
There are two constants set at the beginning of the “domain-selector.” Consider them and their purpose:
The initial version of the script assumed each “domain” would refer to a group of projects that were sub-directories of a single “domain” folder. This is why the “ae”, “mars”, and “admin” projects only set the $queue variable. However, it’s not practical to force projects into such a rigid hierarchy, and as a result, these defaults can be overridden, which is what happens in the other sub-projects.
The key variables here are:
$queue is an array that holds lists of sub-projects. For many workers, as long as you don’t mix Sphinx and Ikiwiki builds, you can specify multiple projects and, and stl will report or act on all of them.
Note
While script uses this basic “queue” structure in a number of places, given the way that the shell (and I) have set up the variables, means that this functionality is not as robust as it ought to be. In the interests of reliability over correctness, the script should always “do the right thing” if you only specify one project in an invocation.
$WC_PATH is the location of the source files. By default, the script will look for source files in “$PROJECT/source/$queue.item” (where $queue.item is an element in the $queue array.) Set WC_PATH to override this.
$PROJECT_PATH is the path of the project files. Unless set this defaults to “~/project”.
$BUILD_TYPE specifies which “build method” to use. Current options are wiki for Ikiwiki instances (stored using git), and sphinx. The default is sphinx.
$EXTENSION specifies the file extension of the files. Defaults to rst. Used to ensure that the word counts do not include extraneous files.
Set any or all of these variables in each case statement. You may now begin using stl to track the stats of your task.