Background
When I was learning Pharo Smalltalk, I found the Pharo By Example book a great help. It was well written and available at a good price ;). However as Pharo advances at great speed and the original authors are busy documenting and implementing new and advanced features – this learning resource has become out of date with some of its examples. So I thought I’d contribute back to help update it to the latest release.
For those that came in late, Smalltalk is a programming development environment that has been around since the 1970s. Derived from the original Smalltalk-80, Apple Computer released Squeak around 1996 as a platform for developing educational software. In 2006 Squeak was released open source. This was later forked to focus on business software development and released in 2009 as Pharo 1.0. At this time the 2007 book Squeak By Example was updated and published as Pharo By Example. Since then there have been several revisions of Pharo, with the most recent release in April 2012 of Pharo 1.4.
Pharo has a goal of refurbishing a lot of the inherited infrastructure, so it is uncertain how closely the book aligns with the current release. Now I could just mark changes and submit for someone else to integrate these into the document, but that is really only half the job and creating work for someone else. Since the LaTeX source of the PBE1 book has open access on github, I’ll decided I would have a crack editing the source direct – except I haven’t used LaTeX or git before. So here I am documenting my setup for two reasons: One is that some adept might point out improvements in my process; the other is to see if I can spark an interest in anyone else to come along for the ride. Now lets see what I’m getting into…
Getting started
The PBE1 book is written in LaTeX , the source of which is managed on github. This is my first experience with both LaTeX and git, so I’ll be happy to update this post with any hints from readers. The README describes an overview of the contribution process. What I document here is my particular circumstance of doing this with Windows 7 – as much for my own reference as trying to draw in an army of willing helpers.
The README specifies use of TeX Live, for which I first used the Windows installer. Serge Stinckwich suggested starting with help.github.com which I found useful create an account and install Git For Windows as instructed here – and also play with some tutorials. However while I successfully cloned the PBE1 repository to my local machine, when I went to do my first build to reproduce the existing book prior to any changes, the lack of make on the Windows platform became problematic.
To get make, I ended up choosing Cygwin. However it seemed awkward to get the make from inside Cygwin to play well with TeX Live outside its root in Windows. Since Git For Windows was only a text shell anyway, I chose to discard the Windows versions of git and TeX Live and use these both from inside Cygwin. So my Cygwin install (currently version 1.7.14-2) went like this:
- Logged in as admin user (since my daily use is under a non-admin account)
- Download and run setup.exe
- Install from Internet
- All Users ; Root Directory=C:\Apps\Cygwin\root
- Local Package Directory=C:\Apps\Cygwin\installer
- Direct Connection & Download Site – ftp://mirror.aarnet.edu.au
- Selecting packages…
- searched “make” and selected “Devel > make”
- searched for “git” and selected “Devel > git, git-completion” (I did wonder about git-gui & gitk but wasn’t sure about about the operation of a gui from Cygwin and what dependencies would be loaded)
- searched “texlive” and selected every “Publishing > texlive” package that did not have a foreign language in it. I did this by changing Publishing from “Default” to “Install” then searching on “live-collection-do” and “live-collection-lan” and deselecting all but English packages.
- searched “ssh” and selected “Net > openssh”
- search “vim” and selected “Editors > vim” (since I know ‘vi’ from long ago, but you might like something else if you browse the whole list of Editors – actually ‘lyx’ looks interesting to try later so I selected that also)
- searched “time” and selected “Utils > time”
- Ticked “select required packages to resolve dependencies.”
The install took quite a while (upwards of 20 minutes with most of that being TexLive) after which I switched back to my non-admin user.
Github setup and practice
After running Start > Programs > Cygwin > Cygwin Terminal, I followed the instructions for linux-set-up-git jumping in at “Set Up SSH Keys.” I then created directory ~/dev and changed into it before doing all parts of Create a Repo for Hello-World. For this learning experience I unticked “Initialize this repository with a README”. I followed up doing the fork-a-repo tutorial to test creating a fork of the “spoon-knife” project.
So now it was time to get my own local fork of PBE1 to work on. 
Serge Stinckwich had already created a 1.4 branch seen on the right and here. This is where I first thought I needed to fork from, so I first selected the branch to 1.4 at (1) below and then created the fork from that by clicking at (2)….
…but actually it doesn’t seem to operate that way. Doing the following clone ended up with my repository having both master and 1.4 branches.
$ cd ~/dev
$ git clone git [at] github [dot] com:bencoman/PharoByExample-english.git
(which downloads about 70MB)
$ cd PharoByExample-english
$ git branch -a
* master
remotes/origin/HEAD -> origin/master
remotes/origin/master
remotes/origin/pharo1.4
So it seems that I only select a particular branch for editing on my local machine. After reading ‘man git-remote’ and ‘man git-branch’ from the Cygwin shell, I continue with the tutorial…
$ git remote add upstream git://github.com/SquareBracketAssociates/PharoByExample-english.git
$ git fetch upstream
$ git branch -a
* master
remotes/origin/HEAD -> origin/master
remotes/origin/master
remotes/origin/pharo1.4
remotes/upstream/master
remotes/upstream/pharo1.4
So at this point I’m not sure if I should checkout remotes/upstream/pharo1.4 or just pharo1.4, or create my own pharo1.4 branch. However I try this, which you can see moves the current-marker from master to pharo1.4…
$ git branch pharo1.4
$ git checkout pharo1.4
Switched to branch ‘pharo1.4′
$ git branch -a
master
* pharo1.4
remotes/origin/HEAD -> origin/master
remotes/origin/master
remotes/origin/pharo1.4
remotes/upstream/master
remotes/upstream/pharo1.4
Now at this stage, the upstream/pharo1.4 changes have have not been merged into my pharo1.4. For example, I know that Serge Stinckwich has updated worldMenu.png in the upstream/pharo 1.4 branch – but at the moment if I browse Windows Explorer to “C:\Apps\Cygwin\root\home\Ben\dev\PharoByExample-english\QuickTour\figures” I see worldMenu.png looks like “Old World Menu” below.
To get the New World Menu above, I executed the following line the reopen worldMenu.png from Windows Explorer.
$ git merge upstream/pharo1.4
Removing QuickTour/figures/SqueakMap.png
Merge made by the ‘recursive’ strategy.
QuickTour/figures/SqueakMap.png | Bin 23867 -> 0 bytes
QuickTour/figures/worldMenu.png | Bin 36937 -> 27729 bytes
QuickTour/figures/yellowButtonMenuOnWorkspace.png | Bin 36518 -> 38602 bytes
pbe1-examples.txt | 2 +-
4 files changed, 1 insertions(+), 1 deletions(-)
delete mode 100644 QuickTour/figures/SqueakMap.png
Producing the book
Before starting making any changes of my own and potentially break something in the build I thought should confirm I could produce the existing book. This is actually its pretty damn simple. I just tried the obvious and this worked….
$ pwd
~/dev/PharoByExample-english
$ make
[lots of stuff]
Output written on PBE1.pdf (338 pages, 13825502 bytes).
Transcript written on PBE1.log.
real 0m45.536s
So now browsing Windows Explorer to…
C:\Apps\Cygwin\root\home\Ben\dev\PharoByExample-english
and opening PBE1.pdf to page 6 shows the updated WorldMenu.
Making a change, commitment, collaboration
(Note this section will change slightly when hopefully my addition of file gitDummyPlay.txt is accepted into the upstream/pharo1.4.)
File gitDummyPlay.txt file in ~/dev/PharoByExample-english is proposed for new contributors to practice pushing changes back to github. If it does not currently exist, do this…
$ touch githubDummyPlay.txt
$ git add githubDummyPlay.txt
$ git commit -m ‘Added dummy file to experiement with while learning git’
$ git push
Now edit the file ~/dev/PharoByExample-english/githubDummyPlay.txt. Compare this to the same file currently on github.com/{your username} under PharoByExample-english/tree/pharo1.4. Now do the following and compare both again…
$ git commit -m ‘Test pushing changes to github’
$ git push
This produces the following network graph, which will disapper when the changes are merged into the mainline.
Now the idea would be to issue a Pull Request to the upstream project, but I am waiting on some feedback.
I wonder if it would be useful to take a git branch for each chapter. This would be similar to one git usage of having a branch for each new feature – perhaps allow more independent updates by multiple editors.
Conclusion
So you can see it is not too difficult to participate at the level of helping out with documentation. Particularly if you are new to Pharo, you may pick up gaps in the doucmentation that are missed by others more familiar with it, so your input here can be valuable. Now that I have this process reasonably sorted out in my mind, I just need to learn LaTeX better.
