wiki:UserManual

The SHR User Manual

This page describes where to find pre build versions of SHR User Manual and how to build it yourself.

Download or browse pre build manuals

Pre build manuals are generated on a Jenkins build host.

Download a PDF version

The generated PDF manuals are (will be) available for different devices. Here are the links:

Browse a html version

The generated html manuals are (will be) available for different devices. Here are the links:

Download a ziped html version

The ziped html manuals are (will be) available for different devices. Here are the links:

Build the manuals yourself

This chapter describes how to build the SHR User Manuals.

Prerequesites

To build the manuals you need

  • a GIT client
  • Java 6 SDK
  • ANT

installed on you build system. The build system is platform independent (as Java 6 is) so builds can be performed under different operating systems (like GNU/Linux, MAC OS) or under Windows.

Get the sources of the manual

mkdir GIT-SHR-DOCS
cd GIT-SHR-DOCS
git clone http://git.shr-project.org/repo/shr-docs.git

If you already got the sources, an update is made by:

git pull

Extract the build toolchain

This must be done only once for the first time or if the toolchain changes.

cd shr-docs/docbook/external
ant

The toolchain can be removed with this command in external directory(only necessary on update problems, please do not remove the toolchain if you want to compile the manual):

ant clean

Now build the manuals

leave the external directory, so your working directory will be shr-docs/docbook and start building the manuals

cd ..
ant

The generated manuals can be found in OUTPUT.

Edit the manual

This section describes how to edit the manual.

What is DocBook?

The whole manual is written in XML files (DocBook? XML). The different manuals are generated by XSL Transformations (DocBook? XSL). But what does it mean ?

The content of our manual is located in XML files. The different target types of manuals like PDF, HTML are provided by XSL Style Sheets. DocBook? distinguishes strictly between content and layout. So the concept is a little bit comparable to LaTex?. The output could be generated by the XSL Style Sheets provided by DocBook? XSL but we decided to change the output a little bit so that it becomes the typical SHR corporate design. Changing the style of output can be done in an so called DocBook? XSL customization layer. This concept is comparable to bitbake layers.

For the beginning or adding content it is not necessary to know something about XSL style sheets or customization layers.

Understanding the repository structure

~/GIT-SHR-DOCS/shr-docs/docbook$ ls 
build.xml  configurations  external  OUTPUT  readme.txt  src
build.xml
This is the main ant build file, this should be called if you build all manuals
configurations
Generating the different flavours of SHR manual (Freerunner, N900, etc) is configured here by different configuration files.
external
The toolchain for building the manuals is here.
OUTPUT
The base directory for generated manuals
readme.txt
A short description what the current directory is for.
src
The base directory of the manual sources.