Wiki.eclipse.org

Scout/Book/4.0

2014-05-17

Created page with "{{ScoutPage|cat=Release 4.0}} == The Eclipse Scout Book == The most recent copies of the Scout book are available from here: * [http://tools.bsiag.com/scoutbook/4.0/ continu..."

New page

{{ScoutPage|cat=Release 4.0}}

== The Eclipse Scout Book ==

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

* [http://tools.bsiag.com/scoutbook/4.0/ continuous builds]

The Eclipse Scout Book project described here is an attempt/experiment to significantly improve the state of the documentation of the Eclipse Scout framework.

After publishing the first iteration of the book with the Kepler release, additional content targeting the client side of the Scout framework is provided with the Luna release.

To allow for participation by the community, the book is written in the open. The setup is designed to make contributions both simple and efficient.

[[#Your_Contribution|How do I contribute?]]

== Repository and Download ==

The current repository is located at the following [https://github.com/BSI-Business-Systems-Integration-AG/scoutbook github repository].

There is also a continuous integration environment setup at [http://www.bsiag.com/eclipse BSI] that is building the book on a regular basis. To check for the current state of the 3.9 (Kepler) release of the book you may visit [http://tools.bsiag.com/scoutbook/3.9/ tools.bsiag.com/scoutbook/3.9/]

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

== Download and Run the Scout Sample Applications ==

If you have installed the Eclipse Scout package, you may download the example applications from the Github repository and run them using your Scout SDK.

For this, you need to go through the following step list.

# Create empty directory to hold the workspace

# Start the Eclipse IDE with this new workspace

# Add the 'Git Repository Exploring' perspective

# In this perspective, click on 'Clone a Git Repository'

# Enter the downloadlink 'github (https://github.com/BSI-Business-Systems-Integration-AG/scoutbook.git)' into the corresponding wizard field

# Step through the wizard steps, don't change any default settings and click Finish

# In the view 'Git Repositories' expand the tree down to the node 'scoutbook [master], Working Directory, code, oneDayTutorial'

# On the node 'oneDayTutorial' click on the context menu 'Import Projects ...'

# When prompted by a dialog, create a new rap_target if necessary

# Switch to the Scout Perspective

To get rid of the errors reported in the problems view, follow these steps

# Open the Eclipse package explorer view, expand the plugin node 'org.eclipsescout.contacts.ui.rap' and open its 'ScoutRAP.target' file

# In the Eclipse target editor, click on the 'Set as Target Platform' link

# The errors reported in the problems view should be gone now

Once the errors are gone, we are ready to start the example application

# In the Eclipse ID switch to the 'Scout Explorer' view and expand the top level element 'Scout Projects'

# Click on the main project node 'org.eclipsescout.contacts'

# In the 'Scout Object Properties' view, go to the section 'Product Launchers' and click on the 'Edit Content ...' icon

# In the 'Select Product' editor, tick all development prouducts

# The the 'Product Launchers' section now lists the available products to start

# Start the ''My Contacts'' server first, then a client

When you would like to run a different example application just choose a different folder under the 'code' node in the 'Git Repositories' view.

== Your Contribution ==

Basically there are two forms of contributions. The first one is [https://github.com/BSI-Business-Systems-Integration-AG/scoutbook/issues?state=open reporting issues], and does not require a lot of time.

The second form allows to contribute content to the book.

In case this is of interest to you, we would roughly want to see the following items:

* Acceptance of the licensing terms (detailed below)

* Following the contribution workflow (detailed below)

* A pull request to discuss the topic you write about

* An updated pull request with a couple of pages worth of text

* Text shows understanding of the topic

* Text shows the author cares about the reader

* Text adds new material to the book

* Text is not a random copy paste effort

== Licensing 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 [http://tools.bsiag.com/scoutbook/latest/html/bookap1.html 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/ 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 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 [http://git-scm.com/book/en/Distributed-Git-Distributed-Workflows#Integration-Manager-Workflow 5.1 Distributed Git - Distributed Workflows] of the book [http://git-scm.com/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 illustration below (copied from [http://git-scm.com/book Pro Git]) illustrates the setup we will create.

[[Image:Scoutbook_git_repos_setup.png]]

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 request and explicitly express your acceptance of the licensing 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.

== Why LaTeX? ==

There are many valid approaches to professionally write a book. Our choice of [http://en.wikipedia.org/wiki/LaTeX LaTeX] is primarily based on the following properties:

* Good previous experience with documents significantly larger than 100 pages

* Possibility to have PDF, HTML, EPUB outputs from a single source

* Text based format makes it ideal to use with version control (Git in our case)

* Possibility to link to code snippets directly from project workspaces (this helps to make sure that the code in the book actually compiles)

* Professional quality output for printing

If your are new to LaTeX, think of it as ''Scripting'' language to ''write'' a book. Here are a couple of high-level recommendations:

* If you need to have some specific layout, first try to find an existing example in the book. Then, do the same.

* You might want to have a look at tutorial first. [https://pangea.stanford.edu/computing/unix/formatting/latexexample.php LaTeX by Example] provides some good initial examples

* If you have more time, go through [http://tobi.oetiker.ch/lshort/lshort.pdf ''The Not So Short Introduction to LaTeX'']

* (if you would like to recommend other sources, please add them here).

* Don't try too hard to manipulate the layouting.

* Try to let LaTeX do as much as possible.

== 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

# Browsing to the [https://github.com/signup/free sign up page]"

## The account ''matthiaszimmermanntest'' is used in the examples below

# Install git on your local computer according to [https://help.github.com/articles/set-up-git GitHub help]

## Installing git using the standard options in all installation steps

## This should provide two local applications: GitHub and GitShell: [[Image:Github_gitshell_local.png‎]]

=== Fork the Book Project ===

# Glance over the [https://help.github.com/articles/fork-a-repo github forking procedure]

# Log into your github account

# Search for the ''scoutbook project''. Once you have found the book project:

# Click on the fork button (as shown in the picture below). [[Image:Fork_book_project.png‎]]

With the above command you created the light green ''developer public'' repository according to the illustration provided [http://git-scm.com/book/en/Distributed-Git-Distributed-Workflows#Integration-Manager-Workflow here].

=== Login and Default Shell ===

Log into your local GitHub app. The blue icon: [[Image:Github_gitshell_local.png‎]]

[[Image:Signing_in_on_local_machine.png‎ ]]

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: [[Image:Github_gitshell_local.png‎]]

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

[[Image:Copy_git_link.png‎]]

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 [http://git-scm.com/book/en/Distributed-Git-Distributed-Workflows#Integration-Manager-Workflow 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 git@github.com:BSI-Business-Systems-Integration-AG/scoutbook.git

With the above command you created the gray arrow from the ''blessed repository'' to your local repository according to the illustration provided [http://git-scm.com/book/en/Distributed-Git-Distributed-Workflows#Integration-Manager-Workflow 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 git@github.com:BSI-Business-Systems-Integration-AG/scoutbook.git (fetch)

upstream git@github.com:BSI-Business-Systems-Integration-AG/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 [http://miktex.org/download (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 [http://calibre-ebook.com/download_windows (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 [http://www.equation.com/servlet/equation.cmd?fa=make (GNU Make 3.82)]

** download the executable and put it into a folder of your preferences

* Download and install 7-Zip

** visit [http://www.7-zip.org/ (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)

* Download and install Dia (Diagramming)

** visit [https://live.gnome.org/Dia/Download (Dia/Download)]

** download the installer file

** execute the installer file, step through using default proposals

* Download and install Inkscape

** visit [http://inkscape.org/download/ (inkscape.org/download/)]

** download the installer file

** execute the installer file, step through using default proposals

==== Mac Installation (TODO) ====

==== Linux Installation (TODO) ====

==== Fixing "makefile" ====

Start with copying the platform specific ''makefile.<platform>'' to ''makefile''.

If you are working on a Windows platform this means copying the file [https://github.com/BSI-Business-Systems-Integration-AG/scoutbook/blob/master/makefile.windows makefile.windows] to ''makefile''.

Most likely, you will then 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 push origin master

=== Create your Local Branch ===

Now you can create your topic branch on the up-to-date local master branch as follows:

a@1 ~/Desktop/oss/github/matthiaszimmermanntest/scoutbook (master)

$ git branch matthiaszimmermanntest-client_notification

$ 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 [https://github.com/dchelimsky/rspec/wiki/Topic-Branches 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 [ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/listings/listings.pdf 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 ''./tex/book.tex'' (the root file of the book) you find the following latex "code":

% --------------------------------------------------------------------------- %

\part{The Frontend}

% --------------------------------------------------------------------------- %

\include{ScoutClient/ScoutClient}

Alternatively you can search (grep command) for any string in the GitHub shell as shown below (in the example we search for '''notification''')

a@1 ~/Desktop/oss/github/matthiaszimmermanntest/scoutbook (master)

$ grep -r -i "notification" ./tex | grep ".tex:"

./tex/ScoutClient/ScoutClient.tex:\chapter{Client Notification}

./tex/ScoutClient/ScoutClient.tex: \item concept wiki: \url{http://wiki.eclipse.org/Scout/Concepts/Client_Notification}

This means, that you have to open latex file ''./tex/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. 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:

% =========================================================================== %

\chapter{Client Notification}

\include{ClientNotification.tex}

\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}

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 convinced that the Scout book would be greatly 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.

=== Adding Screenshots ===

Adding screenshots to the book's content is simple for the author and useful for the reader.

Just use any capturing software you like and save the result as a PNG image.

Then, save the image file in the ''figures'' folder of the corresponding include directory.

To include the screenshot in your contribution, you can copy/paste the following snippet

\begin{figure}

\includegraphics[width=14cm]{your_screenshot_file.png}

\caption{The caption for your screenshot goes here.}

\figlabel{this_is_the_label_for_referencing}

\end{figure}

=== Adding Diagrams ===

Diagrams can be very helpful to explain complex content to the reader.

Unfortunately, creating diagrams is no straight forward task.

To get good results you need the diagrams in both in PDF format (for PDF output) and as PNG images (for HTML output).

Good results can be achieved using the ''Dia'' software for the creation of the diagram and exporting the result in the following formats

* PNG (smoothed)

* Scalable Vector Graphics (SVG, cairo)

Using the ''inkscape'' software you can then load the SVG file and export it as a PDF file (using the default settings for PDF export).

Save all diagram files (*.dia, *.png, *.svg, *.pdf) in the ''figures'' folder of the corresponding include directory.

To include the diagram in your contribution, you can copy/paste the following snippet

\begin{figure}

\includediagram{14cm}{scout_app_architecture_desktop}

\caption{The architecture of a typical Scout client server application.}

\figlabel{scout_app_architecture_desktop}

\end{figure}

=== 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 ===

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

[[Image:Example_of_content_for_initial_pull_request.png]]

To achieve 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

[[Image:Switch_to_branch_open_pull_request.png]]

=== Review and Complete your Contribution ===

Make sure that the text in the title of your pull request properly describes the topic of your intended contribution.

Please also state your acceptance of the Scout book's licensing terms that will apply to your contribution.

The necessary steps to complete the pull request are described very well in this [https://help.github.com/articles/using-pull-requests 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.