Home
$Id$
This is the README file for “Squeak By Example” book, containing an overview
of the project and instructions for processing or modifying the text.
For current status of the chapters and pending actions, see the TODO file.
This project is an open-source book on Squeak, loosely modeled after
Alec Sharp’s “Smalltalk By Example” book.
The svn repository lives here:
https://www.iam.unibe.ch/scg/svn_repos/SqueakByExample/
The home page for the book is here:
http://SqueakByExample.org/
License
This work is licensed under
Creative Commons Attribution-ShareAlike 3.0 Unported
http://creativecommons.org/licenses/by-sa/3.0/
You are free:
to Share — to copy, distribute and transmit the work
to Remix — to adapt the work
Under the following conditions:
Attribution. You must attribute the work in the manner specified by the author or
licensor (but not in any way that suggests that they endorse you or your use of the work).
Share Alike. If you alter, transform, or build upon this work, you may distribute
the resulting work only under the same, similar or a compatible license.
For any reuse or distribution, you must make clear to others the license terms of
this work. The best way to do this is with a link to this web page.
Any of the above conditions can be waived if you get permission from the copyright holder.
Nothing in this license impairs or restricts the author’s moral rights.
Disclaimer
Your fair dealing and other rights are in no way affected by the above.
This is a human-readable summary of the Legal Code (the full license).
Makefile
To build the PDF of the book, simply run “make” in the Book folder.
Be sure you have texlive installed (see below).
Printing
The book has been reformatted to 6"x9" (for Lulu). If you want to print any
part of the book, you will find that printing 2 up at 140% works well.
File structure
The main file is SBE.tex. Chapters are in subdirectories.
You can latex either the entire book, or each individual chapter.
Each chapter file starts and ends with the same incantation
which will optionally include macros or end the document if it is
latexed individually.
Use the \ct{} macro for in-line code.
Use the {method} {classdef} {example} and {script} environments for
multi-line code.
If you add a new chapter:
- please be sure to include it from SBE.tex.
- Remember to include its /figures/ subdirectory in the graphicspath,
which is set in the preamble to SBE.tex. Don't forget the trailing /
- Please make sure the chapter compiles with latex both from the main book
and as a separate chapter.
- Set the svn:ignore property on the chapter's directory. The command to do
this is svn propset svn:ignore -F .svnignore <directory name>
IMPORTANT: Please check out a fresh copy of the book and compile the book
to verify that you have added all the dependent files (e.g., figures).
Image
Please use the final 3.9 image:
– http://ftp.squeak.org/3.9/Squeak3.9-final-7067.zip
To do: set up a SqueakSource project …
Testing
Tests are automatically generated from the LaTeX sources.
To run the tests, load the following package, and save the image to the same location as the SBE.tex main file.
MCHttpRepository
location: 'http://www.squeaksource.com/SBEtesting'
user: ''
password: ''
This package will automatically extract and run the tests in the LaTeX sources of the Squeak by Example book.
Required packages: VB-Regex
Tests are automatically generated from the LaTeX sources.
To run the tests, load this package in an image in the same location as the SBE.tex main file and evalaute:
SBEmain new runTests
This will parse (using Regex) the SBE.tex to locate the included chapter files, parse each chapter file to search for @TEST annotations, generate test case classes for each chapter with tests in a new category SBE-GeneratedTests, and generate a test method (numbered by the line number in the chapter) for each test found. (NB: Any old generated tests are removed before new ones are generated.) Finally, by sending “runTests”, a TestRunner is opened on the new category, and all those tests are run.
A sample test in the BasicClasses looks like this:
=\begin{code}{@TEST}
=a1 := { { ‘harry’ } } .
=a2 := a1 shallowCopy.
=(a1 at: 1) at: 1 put: ‘sally’.
=(a2 at: 1) at: 1 —> ‘sally’
=\end{code}
The “print it” invocation (—>) will generate an assertion.
The generated source code looks like this:
=test204
= a1 := { { ‘harry’ } } .
= a2 := a1 shallowCopy.
= (a1 at: 1) at: 1 put: ‘sally’.
= self assert: [ (a2 at: 1) at: 1 ] value printString = ‘’‘sally’‘’
You may also silently declare or initialize variables immediately after @TEST,
and you may now place comments after the test string:
=\begin{code}{@TEST |a b|}
=a := b := ‘hello’.
=a == b —> true “two variables but one object”
=\end{code}
The generated testCase subclass is SBEBasicClassesTestCase.
The generated tests can be removed by evaluating “SBEmain removeOldTestCategory”. This is done automatically whenever you do “SBEmain new runTests”.
LaTeX version
Please use at least texlive 2005.
http://www.tug.org/texlive/
If you are using TeXshop or another GUI, be sure to set the path to the tex executables. E.g., in TeXShop>Preferences>Engine set the path to:
/usr/local/texlive/2005/bin/powerpc-darwin
For intel macs you will need texlive 2007. The path should be
/usr/local/texlive/2007/bin/i386-darwin
OmniGraffle files
Please be sure to use Lucida Sans, not Helvetica, or you may have problems
uploading the PDF to Lulu. See the font embedding FAQ on lulu.com
Style files
To inform latex about the location of local style files, set the following
environment variable (tcsh):
setenv TEXINPUTS ./local//:../local//:
or (bash):
export TEXINPUTS=./local//:../local//:
If you are using a GUI like TeXshop, you must set the environment variable in ~/.MacOSX/environment.plist :
<?xml version=“1.0” encoding=“UTF-8”?>
<!DOCTYPE plist PUBLIC “–//Apple Computer//DTD PLIST 1.0//EN” “http://www.apple.com/DTDs/PropertyList-1.0.dtd”>
<key>TEXINPUTS</key>
<string>./local//:../local//:</string>
NB: You may need to logout and login again after creating or modifying this file.
Note colon at end of TEXINPUTS that means “append current value here”
(eg local has higher priority). Double slash means search recursively.
Bibliography
The bibliography file scg.bib is available from a separate subversion repository:
https://www.iam.unibe.ch/scg/svn_repos/scgbib/
https://www.iam.unibe.ch/scg/svn_repos/scgbib/scg.bib
