# Scout/Book/3.9

< Scout‎ | Book

 Scout Wiki Home Website Download • Git Community Forums • Blog • Twitter • G+ Bugzilla Bugzilla

## The Eclipse Scout Book

The Eclipse Scout Book is the attempt to significantly improve the state of the documentation of the Eclipse Scout framework.

The goal of this effort is to have written a substantial part of the book by Kepler release date (June 2013 - the content of the book will target Scout 3.9)

To allow for participation by the community the book will be written in the open from it's very first version (as of now (December 4th 2012) there is hardly more than the proposed table of contents with some pointers to existing forum entries.

The current repository is located at the following github repository. It will be replaced by a more prominent location soon.

There is also a continuous integration environment setup at BSI that is building the book on a regular basis. To check for the current state of the book you may visit tools.bsiag.com/scoutbook/

Each build will create a directory with the following structure

 yyyy-mm-dd_hh_MM-SS
epub
book.epub
html
book.zip (all files in a single zip)
book.html (main html file for online browsing)
... many more files
pdf
book.pdf


The most recent copies of the Scout book are available from directory latest:

## Licencing Terms for Contributions

If you intend to contribute to the Scout book, please note that only material will be accepted, that is explicitely provided under the Creative Commons (CC-BY)/"Eclipse Public Licence (EPL)" terms described below.

Text and illustrations will be published according to Appendix A "Copyright" of the book. Specifically the following text: This work is licensed under the Creative Commons Attribution License. To view a copy of this li- cense, visit http://creativecommons.org/licenses/by/2.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA

Code snippets should only be referenced in the book from complete and working applications. In order to encourage copy/paste of code provided in the book your code needs to be released under the Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available at http://www.eclipse.org/legal/epl-v10.html.

## Scout Book Contribution Workflow

The chosen contribution model for the Scout book is nicely summarized in chapter 5.1 Distributed Git - Distributed Workflows of the book Pro Git. As Github provides public repositories for free and allows for efficient communication between contributors and committers this is setup we will use for the first edition of the Scout book.

The illusatration below (copied from Pro Git) illustrates the setup we will create.

Overview for the Scout book contribution workflow

1. Set up you Github account
2. Fork the Scout book and clone it to your local repository
3. Build the Scout book locally
4. Create a branch for your contribution
5. Do the writing/coding/illustrating
6. Open a pull request for your contribution (expressing your acceptance of the licencing terms)

## Setting Things Up

In case you don't yet have a Github account, this is your first step. The text below provides a quick overview. Some more details are provided

1. The account matthiaszimmermanntest is used in the examples below
2. Install git on your local computer according to GitHub help
1. Installing git using the standard options in all installation steps
2. This should provide two local applications: GitHub and GitShell:

### Fork the Book Project

1. Glance over the github forking procedure
3. Search for the scoutbook project. Once you have found the book project:
4. Click on the fork button (as shown in the picture below).

With the above command you created the light green developer public repository according to the illustration provided here.

For the explanation below, we set Git Bash as our default shell. This can be done in the GitHub app using menu tools, and then options in the section default shell.

### Local Repository and Cloning

Open the GitShell. The black icon:

Create a target directory in the shell and switch into it

 a@1 ~/Desktop/oss/github
$mkdir matthiaszimmermanntest a@1 ~/Desktop/oss/github$ cd matthiaszimmermanntest/


Clone the fork into your local repository

 a@1 ~/Desktop/oss/github/matthiaszimmermanntest
$git clone https://github.com/matthiaszimmermanntest/scoutbook.git Cloning into 'scoutbook'... remote: Counting objects: 568, done. remote: Compressing objects: 100% (263/263), done. Receiving objects: 85remote: Total 568 (delta 157), reused 560 (delta 149) Receiving objects: 100% (568/568), 450.77 KiB | 198 KiB/s, done. Resolving deltas: 100% (157/157), done.  You can copy the link for the git clone command from your github account Then, verify the content  a@1 ~/Desktop/oss/github/matthiaszimmermanntest$ cd scoutbook/

a@1 ~/Desktop/oss/github/matthiaszimmermanntest/scoutbook (master)
$ls -l total 2.0k -rw-r--r-- 1 mzi Administ 132 Nov 29 22:04 README.textile drwxr-xr-x 4 mzi Administ 0 Nov 29 22:04 code/ -rw-r--r-- 1 mzi Administ 2.5k Nov 29 22:04 makefile drwxr-xr-x 5 mzi Administ 0 Nov 29 22:04 out/ drwxr-xr-x 26 mzi Administ 0 Nov 29 22:04 tex/  With the above cloning operation you have added the dark green repository developer private, according to the illustration provided here. ### Linking with the "Blessed" Repository This step adds a link of your local repository to the remote Scout book (that you forked previously).  a@1 ~/Desktop/oss/github/matthiaszimmermanntest/scoutbook (master)$ git remote add upstream https://github.com/matthiaszimmermann/scoutbook.git


With the above command you created the gray arrow from the blessed repository to your local repository according to the illustration provided here. Now, list your remotes for verification. That should look similar to the output below:

 a@1 ~/Desktop/oss/github/matthiaszimmermanntest/scoutbook (master)
$git remote -v origin https://github.com/matthiaszimmermanntest/scoutbook.git (fetch) origin https://github.com/matthiaszimmermanntest/scoutbook.git (push) upstream https://github.com/matthiaszimmermann/scoutbook.git (fetch) upstream https://github.com/matthiaszimmermann/scoutbook.git (push)  ### Building the Book Locally This section holds the necessary installation/setup that is required to build the book out of the sources. It is recommended (but not strictly necessary) to build the book on your own machine to verify your contribution does not break the build. To do this you will need working installations of the following programs • latex (for PDF and HTML version) • calibre (for creation and viewing of EPUB version) • make (for building the book using a make file) • zip/unzip (for packaging of the HTML version into a single zip file) In the sections below, necessary download and installation steps of a working setup are described for Windows (if you have a working setup for Mac or Linux, please consider to amend a corresponding section. #### Windows Installation For Windows, please follow the steps indicated below: • Download and install LaTeX • visit (basic-miktex-2.9.4521-x64) • download the installer file • execute the installer file and take note of the installation path (you will later need to adapt the makefile) • Download and install Calibre • visit (calibre version 0.9.5) • download the installer file • execute the installer file and take note of the installation path (you will later need to adapt the makefile) • Download and install make • visit (GNU Make 3.82) • download the executable and put it into a folder of your preferences • Download and install 7-Zip • visit (7-Zip) • download the installer file • execute the installer file and take note of the installation path (you will later need to adapt the makefile) #### Mac Installation (TODO) #### Linux Installation (TODO) #### Fixing "makefile" Most likely, you will need to update the paths in your makefile to the executable files from your local installation. Specifically, the following variables in the makefile need to be adjusted according to your local setup: • BIN • LATEXROOT • EBOOKCONVERT • ZIP • UNZIP • COPY There might be some other commands that don't work cross platform out of the box. If you are on a mac/linux box you might need to replace the following os-commands in the makefile • rmdir • mkdir • del #### "make" the Book Building the book is done using make in the main folder of your local book repository (make sure to edit the makefile in the root path of the git repository to account for the installation paths of the downloaded software). To create the pdf version of the book use  a@1 ~/Desktop/oss/github/matthiaszimmermanntest/scoutbook (master)$ make pdf


The complete sequence of commands to generate all three output formats is

 make clean
make pdf
make html
make epub


The output will then be moved to the following locations

 out\pdf\book.pdf
out\html\book.zip (containing the html and other necessary files)
out\epub\book.epub


## Create a Topic Branch

### Sync with the "Blessed Repository"

Before you create a new topic-branch it is recommended that you get up to date with the upstream book. For this, switch to your local master branch an pull in the upstream changes.

 a@1 ~/Desktop/oss/github/matthiaszimmermanntest/scoutbook (master)
$checkout master$ git pull upstream master


Next, bring you public repository up to date

 a@1 ~/Desktop/oss/github/matthiaszimmermanntest/scoutbook (master)
$git checkout matthiaszimmermanntest-client_notification  Please use the following naming scheme for your topic branches <githubuser-meaningful_contribution_name>. Managing pull requests will get significantly simpler (In the example above matthiaszimmermanntest is contributing the material to describe the client_notification mechanism of Scout. See here to read more about topic branches. The first two sections are relevant in this context (instead of first branching and then checking out the two commands are folded into a single one: git checkout -b <branchname>). ## Work on your Contribution When you have checked out your topic branch you can start to add and edit the files needed for your contribution. ### Source Organisation Do your writing in the latex source files, and your coding in the java codefiles. Whenever you need to include some code snippets in your text, please do this by reference only using the Listings package. Do not put code directly into the latex sources. This setup helps to ensure that all code snippets come from real projects, that actually compile and run using the described version of Eclipse Scout. The latex and scout sources are roughly organized as follows:  code workspace 1 plugin 1 plugin 2 ... helloworld org.eclipse.scout.helloworld.client src ... ... workspace n tex Chapter1 Chapter1.tex Someincludefile.tex ... Introduction figures sdk_helloworld_messagefield.png Introduction.tex ... Chapter n ... book.tex (the books' root tex)  ### An Example Contribution Let's assume that you will be describing the client notification mechanism of Scout. During browsing of the table of contents you find that this topic is to be covered in a separate chapter in part "User Interface" of the book. Starting with the file book.tex you find the following latex "code":  % --------------------------------------------------------------------------- % \part{The User Interface} % --------------------------------------------------------------------------- % \include{ScoutClient/ScoutClient}  This means, that you have to open latex file ScoutClient/ScoutClient.tex. In that file you find the corresponding chapter:  % =========================================================================== % \chapter{Client Notification} needs text \noindent Existing Documentation \begin{itemize} \item presentation: \url{http://wiki.eclipse.org/images/e/ea/20121022_BahBah_Slides.pdf} \item concept wiki: \url{http://wiki.eclipse.org/Scout/Concepts/Client_Notification} \item forum: \url{http://www.eclipse.org/forums/index.php/t/241053/} \end{itemize}  Obviously, there is a lot of room for improvement. As some initial guideline you find the pointers to existing documentation in the itemized list.  \include{ClientNotification.tex}  ### When you Need Additional Latex Packages First: Try to get away with existing concepts from the current book by looking at the latex source code. If you are concvinced that the Scout book would be geatly improved by making use of additional latex packages please do the following: 1. Consider that the different chapters should have a consistent look at the end 2. Make sure (using your local build infrastructure) that your proposal works for pdf, html, and epub formats 3. Post your proposal to the Scout forum and explain your idea 4. If encouraged, go ahead. ### Save your Work From time to time you want to commit your changes to your local and public repository. For this, you first get the list of changed files and add all those that need to be included in your commit before you commit to the local repository.  a@1 ~/Desktop/oss/github/matthiaszimmermanntest/scoutbook (matthiaszimmermanntest-client_notification)$ git status
# to check the list of files you want to include to your commit

$git add <file1> <file2> <...>$ git commit -m '<your commit message goes here>'


To push your local topic branch (and/or changes in it) to your public remote repository use the following command

 a@1 ~/Desktop/oss/github/matthiaszimmermanntest/scoutbook (matthiaszimmermanntest-client_notification)
 git push origin matthiaszimmermanntest-client_notification


This will make your work visible in the GitHub webui.

## Open a Pull Request

### Initiate a Pull Request

Once you have completed the work on your feature branch (and you are satisfied with the result) you can commit to your local repository and push the current status of your feature branch to your public repository as described above.

Then, login to your GitHub account, and (as shown with the arrows in the screenshot below):

1. Switch to your topic branch
2. Click on the Pull Request button

### Review and Complete your Pull Request

The necessary steps to complete the pull request are described very well in this GitHub article. Please start reading in Section "Previewing The Pull Request".

Once you have submitted your pull request, we will review it and work jointly in refining the contribution before it will be merged into the "Blessed repository".