Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Scout/Book/3.9"
(→Contributing) |
(→Fixing the Makefile) |
||
| Line 159: | Line 159: | ||
* mkdir | * mkdir | ||
* del | * del | ||
| + | |||
| + | == Contributing == | ||
| + | |||
| + | TODO: Describe Contribution Workflow | ||
Revision as of 18:01, 29 November 2012
The Scout documentation has been moved to https://eclipsescout.github.io/.
Contents
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.
Download of Current Status
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
Repository
The current repository is located at the following github repository. It will be replaced by a more prominent location soon.
Setting Things Up
Set up a Github Account and Fork the Book Project
To be able to contribute to the Scout book, please
- Create a github account by
- browsing to "github.com"
- signing up (you may sign up for a free account) (matthiaszimmermanntest)
- Install git on your local computer by
- downloading the latest version of git
- installing git using the standard options in all installation steps
- this should provide two local applications: GitHub and GitShell:
- Fork the Book Project
- Glance over the 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).
Set up the Local Repository
Log into your local GitHub app
Open the GitShell and create a target directory 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/
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 (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)
Fixing the 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
Contributing
TODO: Describe Contribution Workflow