1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
<html xmlns="http://www.w3.org/1999/xhtml">
7
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
9
<title>Editing or Translating This Book — The SchoolTool Book</title>
11
<link rel="stylesheet" href="_static/flourish.css" type="text/css" />
12
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
14
<script type="text/javascript">
15
var DOCUMENTATION_OPTIONS = {
18
COLLAPSE_INDEX: false,
23
<script type="text/javascript" src="_static/jquery.js"></script>
24
<script type="text/javascript" src="_static/underscore.js"></script>
25
<script type="text/javascript" src="_static/doctools.js"></script>
26
<script type="text/javascript" src="_static/jquery.colorbox-min.js"></script>
27
<script type="text/javascript" src="_static/flourish.js"></script>
28
<link rel="shortcut icon" href="_static/favicon.ico"/>
29
<link rel="author" title="About these documents" href="about.html" />
30
<link rel="top" title="The SchoolTool Book" href="index.html" />
31
<link rel="next" title="Glossary of SchoolTool" href="glossary.html" />
32
<link rel="prev" title="Translating SchoolTool.org" href="translation-web.html" />
33
<link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Ubuntu:regular,bold&subset=Latin" />
37
<div class="schooltool">
40
<a href="http://www.schooltool.org/">
41
<span class="school">school</span><span class="tool">tool</span>
42
<img alt="Logo" src="_static/logo-small.png" />
45
<ul class="navigation">
47
<a href="http://schooltool.org/">
52
<a href="features.html">
57
<a href="http://launchpad.net/schooltool-project/+announcements">
62
<a href="screenshots.html">
67
<a href="system-requirements.html">
82
<script type="text/javascript">
83
$(document).ready(function() {
84
$(window).scroll(function() {
85
var scrollTop = $(window).scrollTop();
87
$('div.related').css('position', 'fixed');
88
$('div.related').css('top', '0');
90
$('div.related').css('position', 'absolute');
91
$('div.related').css('top', '64px');
100
<li class="right" style="margin-right: 10px">
101
<a href="glossary.html" title="Glossary of SchoolTool"
102
accesskey="N">next</a></li>
104
<a href="translation-web.html" title="Translating SchoolTool.org"
105
accesskey="P">previous</a> |</li>
106
<li><a href="index.html">The SchoolTool Book</a> »</li>
110
<div id="search-box">
111
<form class="search-form" id="google-appliance-search-form" method="get"
112
accept-charset="UTF-8"
113
action="search.html">
115
<div id="edit-keys-wrapper" class="form-item">
116
<input type="text" class="form-text"
117
onfocus="if(this.value=='Type to search'){this.value=''}"
118
onblur="if(this.value==''){this.value='Type to search';}"
119
value="Type to search" size="20" id="edit-keys" name="q"
121
<input type="hidden" value="yes" name="check_keywords" />
122
<input type="hidden" value="default" name="area" />
124
<img src="_static/arrow.png" class="form-submit"
125
onclick="$(this).closest('form').submit()"
126
style="cursor: pointer" />
130
<!-- End Search Bar -->
134
<div class="document">
135
<div class="documentwrapper">
136
<div class="bodywrapper">
139
<div class="section" id="editing-or-translating-this-book">
140
<span id="translate-book"></span><h1>Editing or Translating This Book<a class="headerlink" href="#editing-or-translating-this-book" title="Permalink to this headline">¶</a></h1>
141
<div class="section" id="rationale">
142
<h2>Rationale<a class="headerlink" href="#rationale" title="Permalink to this headline">¶</a></h2>
143
<p>We have given a lot of thought to setting up this documentation in a way that will make it easy to maintain translations, allow modification for specific sites, and offer a clear process for potential contributors to submit changes to the official version.</p>
144
<p>A wiki would be one obvious way to make editing easy – but for managing multiple versions, languages and formats over a long period of time, maintaining text files in version control gives us more control and flexibility than a set of wikis stuffing text in databases. Using files in revision control facilitates including scripts to automatically reproduce the steps in demonstrations in the documentation, like <a class="reference external" href="http://seleniumhq.org/">Selenium</a> scripts. Also, it fits in nicely with the rest of our project management systems and code documentation practices.</p>
145
<p>Even if this system sounds intimidating, please give it a chance. After you get through the initial setup, the actual editing is very wiki-like. If you decide you can’t deal with the revision control part, go ahead and just email <a class="reference external" href="mailto:hoffman%40schooltool.org">Tom Hoffman</a> with changes, and I’ll try to handle your contributions from there. Simple changes can simply be <a class="reference external" href="https://bugs.edge.launchpad.net/schooltool">filed as bugs on SchoolTool</a>.</p>
147
<div class="section" id="getting-the-sources">
148
<h2>Getting the Sources<a class="headerlink" href="#getting-the-sources" title="Permalink to this headline">¶</a></h2>
149
<p>For non-programmers, the weird part will be using the <a class="reference external" href="http://bazaar-vcs.org/">Bazaar version control system</a> (aka bzr).</p>
150
<p>To install bzr on Ubuntu do:</p>
151
<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install bzr
154
<p>For all other platforms see <a class="reference external" href="http://bazaar-vcs.org/Download">Bazaar downloads</a>. The rest of the instructions will assume you’re using Ubuntu, other platforms should be similar. Of course, if you’d like to add instructions for other platforms to this document, just follow these editing process described herein.</p>
155
<p>Then, to fetch the source:</p>
156
<div class="highlight-python"><div class="highlight"><pre>bzr branch lp:schooltool-book
159
<p>This will create a directory called <strong>schooltool-book</strong>, which contains a <strong>source</strong> directory with all the marked up text files and images which make up the book, and a Makefile and associated files which automate the process of turning the sources into a publishable document.</p>
161
<div class="section" id="building-an-html-version">
162
<h2>Building an HTML Version<a class="headerlink" href="#building-an-html-version" title="Permalink to this headline">¶</a></h2>
163
<p>The set of scripts which turn the sources into a finished product is called <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a>.</p>
164
<p>You’ll need some basic software development tools, if you don’t have them already:</p>
165
<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install build-essential python-dev python-virtualenv
168
<p>Within the <strong>schooltool-book</strong> directory, do:</p>
169
<div class="highlight-python"><div class="highlight"><pre>make html
172
<p>This will first make a sandbox containing the Python packages needed for the process, create a <strong>build/html</strong> directory, and put finished web pages in it.</p>
173
<p>If you open <strong>build/html/index.html</strong> from your browser, you’ll be able to read the book in web form. You can publish this directory to the web like any other set of HTML pages.</p>
175
<div class="section" id="building-a-pdf-version">
176
<h2>Building a PDF Version<a class="headerlink" href="#building-a-pdf-version" title="Permalink to this headline">¶</a></h2>
177
<p>The PDF output from this process is usable. Because there are a lot of large screengrab images in the book, and we can’t (or don’t know how to) control the page breaks, the layout isn’t that great. Hopefully we’ll be able to improve that in the future.</p>
178
<p>Also, as of May 2009 there was a unicode bug that bombed out near the end of the book, but most of the content made it into the PDF. We have not confirmed that this PDF rendering bug is fixed, so your mileage may vary. If you manage to make a beautiful PDF by following the instructions below, feel free to let us know how you accomplished it!</p>
179
<p>Grab the TeX libraries:</p>
180
<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install texlive-full
183
<p>First, from the <strong>schooltool-book</strong> directory do:</p>
184
<div class="highlight-python"><div class="highlight"><pre>make latex
188
<div class="highlight-python"><div class="highlight"><pre>cd build/latex
192
<p>This should create a schooltool-book.pdf file in the <strong>build/latex</strong> directory.</p>
193
<p>For a more complete explanation of the above, see <a class="reference external" href="http://jimmyg.org/blog/2009/sphinx-pdf-generation-with-latex.html">Sphinx PDF Generation with LaTeX</a>.</p>
201
<div class="sphinxsidebar">
202
<div class="sphinxsidebarwrapper">
203
<h3><a href="index.html">Table Of Contents</a></h3>
205
<li><a class="reference internal" href="#">Editing or Translating This Book</a><ul>
206
<li><a class="reference internal" href="#rationale">Rationale</a></li>
207
<li><a class="reference internal" href="#getting-the-sources">Getting the Sources</a></li>
208
<li><a class="reference internal" href="#building-an-html-version">Building an HTML Version</a></li>
209
<li><a class="reference internal" href="#building-a-pdf-version">Building a PDF Version</a></li>
214
<h4>Previous topic</h4>
215
<p class="topless"><a href="translation-web.html"
216
title="previous chapter">Translating SchoolTool.org</a></p>
218
<p class="topless"><a href="glossary.html"
219
title="next chapter">Glossary of SchoolTool</a></p>
222
<div class="clearer"></div>
225
<p class="copyright">
226
© Copyright 2014, the Shuttleworth Foundation. This work is licensed under the Creative Commons Attribution 3.0 Unported License.
229
Last updated on May 22, 2014.
230
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2.2.
231
<a href="_sources/editing-this-book.txt"
232
rel="nofollow">Show Source</a>
b'\\ No newline at end of file'