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.

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

Set up you Github account

Fork the Scout book and clone it to your local repository

Build the Scout book locally

Create a branch for your contribution

Describe your planned contribution including approx size and content

Open a pull requestand explicitly express your acceptance of the licencing terms

Do the writing/coding/illustrating

Regularly interact to make sure your contribution will find its way into the Scout book

The contribution workflow outlined above is explained step-by-step in the reminder of this article. It would be great if you would find the time to contribute to the Scout book and help us to foster a healthy and growing community around Eclipse Scout.

Setting Things Up

Create your Github Account

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

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:

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.

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

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.

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 ./tex/book.tex you find the following latex "code":

Obviously, there is a lot of room for improvement. As some initial guideline you find the pointers to existing documentation in the itemized list. It will make sense to have read and understood the listed items to make sure that your suggested content will reflect the already existing information.

To contribute to an initially empty chapter/section, please use the latex include mechanism to put your contribution into an additonal file. As an example we create a new (and intially empty) file ClientNotification.tex in directory ScoutClient that we can include as follows:

In this file ClientNotification.tex you can then write our latex code.
To help later refinement/merging please try to put each sentence on a separate line as shown with the "dummy" ClientNotification.tex file:

% =========================================================================== %
% Chapter Client Notification
% =========================================================================== %
% start your contribution by stating the following in a box
\fbox{
\parbox{12cm}{
The goal of this section is ...
The approximate size of this contribution is ... n words - or m pages
Necessary links/prerequisites with other parts of the book
Proposed links to external material
}
}
Here comes the content of the contributed chapter.
This sentence is awfully long, of course this has its reasons, as for this topic we need to describe a many different aspects, interfaces, and classes - but most likely it is just bad style to do such long sentences.
Third sentence goes here.
% =========================================================================== %

Considering the above example, please try to keep sentences to readable lengths.
If its getting too long, you need to rephrase.

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:

Consider that the different chapters should have a consistent look at the end

Make sure (using your local build infrastructure) that your proposal works for pdf, html, and epub formats

Post your proposal to the Scout forum and explain your idea

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.

Open a Pull Request

Initiate a Pull Request

As soon as you have some working code and/or a clear picture of the intended content of your contribution document that intent
in your contribution, commit to your local repository and push the current status of your feature branch to your public repository as described above.

Your first content to initiate a pull request might look similar to the example provided below

To achive this the following latex code was used

% --------------------------------------------------------------------------- %
\section{Java SE Basics}
\applabel{javase_basics}
\fbox{
\parbox{12cm}{
Section waiting for contribution (2'000-3'000 words)
The goal of this section is to provide the reader with a solid overview of the non-trivial
Java concepts relevant for scout applications and central aspects of the framework itself.
The focus of this section is on the Java Standard Edition (Java SE).
Where appropriate, provide links to high quality online material, that is likely to exist for at least the next year or two.
}
}

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

Switch to your topic branch

Click on the Pull Request button

Review and Complete your Contribution

Make sure that the text in the titel of your pull request properly describes the topic of your intended contribution.
Please also state your acceptance of the Scout book's licencing terms that will apply to your contribution.

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".

Once the pull request becomes visible, we can start the discussion about goal, content, code etc. of your contribution.
This process provides as much information as early as possible.
This will help others to see who is intending to contribute where and how far the writing has progressed.
It also helps to minimize frustration as we can avoid having to argue with you over content and quality after a significant effort from your side.