The Milling Toolset User Guide

  1. Overview
  2. MillScript
  3. The "website" Command
  4. The "build" Command
  5. The "millscript" Command
  6. The Startup Environment

Overview

First and foremost, the Toolset is a small group of programs for automatically building static web sites from the Open World data sources. In an abstract sense, building web sites is a compilation process similar to the compilation of a program written in an ordinary programming language. Compiling web sites in this way is sometimes called "milling" - hence the name. The Toolset is deployed on a single Linux server at the Bath Studios. To get started you should read the How to Get Started guide. To learn how to use the Toolset to build web sites you can read the (slightly outdated) guide How to Make Web Sites with the Toolset. The components of the Toolset are :-
  1. A simple but effective scripting language called MillScript. Scripts written in this special-purpose language are the core of the Milling system. It is implemented as an interpreter written in Java. For an introduction read the MillScript Language Summary.
  2. Three command-line programs, "website", "build" and "millscript", that are used for various administrative tasks. The use of the "millscript" command-line program is to start the Millscript Interpreter.

    Some of the uses of the "website" command-line program is to check the load of the machine, create a new website, etc. To see all the options of the "website" command-line program you can type: 
    website --help
    One of the uses of the "build" command-line program is to run the site.ms. To see all the options of the "build" command-line program you can type: 
    build --help
  3. A web server for viewing the Milling Filing system which includes the output of scripts and all documentation. [In the future this should ideally be configured to be a clone of the public web server so all services can be locally previewed prior to upload (i.e. An alpha site).]
  4. A standard working environment which is established by sourcing the the startup file 
    ${millscript}/etc/rc.startup
    The environment variable ${millscript} holds the name of the central directory from which all the files can be found. In a typical installation this will be /home/millscript/millscript.

MillScript

Because MillScript is a programming language it has its own documentation set. This is comprised of the following documents which are listed in natural reading order - although the first two can be tackled in either order.
  1. The MillScript Language Summary
  2. How to Write MillScript Templates

The "website" Command

website [options]
The website command takes a list of options and executes them serially. Options always have a long form, starting with two hypens (--), but they may also have a short form, prefixed by a single hypen (-). The short form supports compact options i.e. a sequence of characters prefixed by a single hypen are expanded into a sequence of short options. For example, "-qun" would be expanded into "-q -u -n". These short forms would then be further expanded into their longer equivalent "--quiet", "--unattended", and "--new".
Long form Short form Description
--average-load -a Print 1, 5, and 15 minute load average of the machine
--find [dir name] -f [dir name] Find all websites in directory
--help -h Prints this list of options.
--new [dir name] -n [dir name] Creates new website directory
--purge [dir name] -p [dir name] Purges the output directory. This means deleting all files and directories in ${millscript}/websites/website/output/.
--quiet -q Quiet mode
--status [dir name] -s [dir name] Show status of websites
--unattended -u Run without asking questions
--who -w Show who is logged on

The "build" command

Long form Short form Description
--help -h Prints this list
--quiet -q Quiet mode
--unattended -u Run without asking questions
--verbose -v Verbose mode

The "millscript" command

If you type "millscript" on the command line, you start the Millscript interpreter. All the commands end with a semi-colon. The interpreter will print the number of results returned by any expression.

Example

Type 
:-) var a=0;
The interpreter prints: 
There are 0 results
Then type: 
:-) if a > 5 then println("a was bigger than 5")
:-) endif;
By pressing enter the interpreter runs the expression and it prints: 
a was bigger than 5
There are 0 results

Example

:-) for c from 1 to 5 do c endfor;
After hitting return, the interpreter prints: 
There are 5 results
1
2
3
4
5
:-)

The Startup Environment

The Layout of a website directory

Below there are one-line summaries of all the contents of any website directory - Using a browser you'll get one-line summaries for all the contents. These one-line summaries are supplied by the ".htaccess" files. However, for more of an overview of the file structure you may well find the the ASCII art diagram to be helpful. 
${millscript}                   root of the Project (/home/millscript/millscript)
    websites                    directory for the web sites
        www.foobar.com          scripts for fictious hotel "Foo Bar"
            FooBar.java         typically Java extensions for "Foo Bar"
            cache               saved datastructures are put here
            classes             directory for class files
                FooBar.class    typical Java class file for "Foo Bar"
            output              directory for placing output
            inventory           page templates & other resources
                page1.tp        imaginary template page 1
                page2.ms        imaginary millscript page 2
                page3.gif       imaginary image page 3
            site.jar            extensions to the specification languages
            site.xml            folder structure for the web site
            var
                dirty.log       "sticky" log for failed runs
                done.log        log for initial successful run
                mill.pid        currently running process ID (lock file)
To explore the structure of the MillScript Project further use the UNIX find command. For example, to see all the directories use the command find ${millscript} -type d. Coupled with the xargs command this is capable of very powerful searches. For example, to find all MillScript files that have the text "inventory" in them you would write find ${millscript} -type f | xargs grep -il inventory. To delete all files that have the extension ".class" (don't!) you would write find ${millscript} -type f -name "*.class" | xargs rm. So, even though they are ludicrously arcane, these commands are well worth mastering.