|
|
| (121 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| − | {{ScoutPage|cat=Releases}}
| + | The Scout documentation has been moved to https://eclipsescout.github.io/. |
| − | == 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 (November 8th 2012) there is hardly more than the proposed table of contents with some pointers to existing forum entries.
| + | |
| − | | + | |
| − | == Repository and Download ==
| + | |
| − | | + | |
| − | The current repository is located at the following [https://github.com/matthiaszimmermann/scoutbook github repository].
| + | |
| − | It will be replaced by a more prominent location soon.
| + | |
| − | | + | |
| − | 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 book you may visit [http://tools.bsiag.com/scoutbook/ 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
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | == 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/ 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 illusatration 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
| + | |
| − | # Do the writing/coding/illustrating
| + | |
| − | # Open a pull request for your contribution (expressing your acceptance of the licencing terms)
| + | |
| − | | + | |
| − | == Set Up 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 Setting the 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 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 [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 https://github.com/matthiaszimmermann/scoutbook.git (fetch)
| + | |
| − | upstream https://github.com/matthiaszimmermann/scoutbook.git (push)
| + | |
| − | | + | |
| − | == Steps for Building Locally ==
| + | |
| − | | + | |
| − | This section holds the necessary installation/setup that is required to build the book out of the sources.
| + | |
| − | | + | |
| − | Most probably, you may want to build the book on your own computer to check your contribution prior to publish them. If so, you need to download and install
| + | |
| − | | + | |
| − | * 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.
| + | |
| − | | + | |
| − | 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):
| + | |
| − | | + | |
| − | 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
| + | |
| − | | + | |
| − | === Installing the software ===
| + | |
| − | | + | |
| − | ==== Windows ====
| + | |
| − | | + | |
| − | 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)
| + | |
| − | | + | |
| − | === Fixing the Makefile ===
| + | |
| − | | + | |
| − | Most likely, you will need to update the paths in your [https://github.com/matthiaszimmermann/scoutbook/blob/master/makefile 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
| + | |
| − | | + | |
| − | == Contributing ==
| + | |
| − | | + | |
| − | TODO: Describe Contribution Workflow
| + | |
