Manual/Manual Setup

Warning: The information on this page is obsolete and kept mainly for historical purposes.

We use Sphinx as documentation tool.

Introduction

The user manual of Mahara has its home on git like the code. That allows for easy control of the individual files. You are welcome to add to the manual and also translate it into your own language.

Here you will learn how to set up the manual on your computer.

The instructions here are written to work on Ubuntu. They should be easily transferred to another environment that meets the prerequisites.

Prerequisites

AsciiDoc

The manual is written in AsciiDoc, an easy to learn document markup language that allows to be converted into a number of output files such as HTML, PDF, DocBook without the need to learn full XML commands.

You will need to download AsciiDoc which currently exists for Linux and Windows. Mac users can also use it when they install Xcode (beware: huge file) and MacPorts.

Text editor

Once you have downloaded AsciiDoc, you can write the manual files in your favorite text editor. Some come with syntax highlighting which makes it easier to spot problems early on.

Initial installation

1. Install AsciiDoc

AsciiDoc has an Ubuntu package. Other distributions can be downloaded from the installation page. On Ubuntu:

sudo apt-get install asciidoc

2. On Ubuntu: Download the AsciiDoc source files if you want to use vim The Ubuntu package does not come with the folders for enabling syntax highlighting in vim. Thus, you need to download the source files and extract them somewhere on your computer into a temporary directory.

Then go to the vim directory in the asciidoc folder and move the ftdetect and syntax folders to the vim directory:

sudo mv -r ftdetect /etc/vim
sudo mv -r syntax /etc/vim

3. Get the manual by doing a checkout of the manual:

cd ~
mkdir code
cd code
git clone git://gitorious.org/mahara/manual.git

4. Make changes to the manual's txt files.

Compile the manual

All you need to do (on Ubuntu) when you want to compile the manual, is to use the "make" command to trigger the Makefile which checks for any updates on the files in the directory and updates them.

The make file included in git produces HTML output files.

If you want to compile a specific file only:

make file.txt

If you want to re-compile a file, e.g. after changing the css file, but the txt file itself hasn't changed:

touch file.txt
make

Structure of the manual

The manual folder is divided into folders and files. The folders represent the top-level navigation of Mahara. A number of other folders and files exist:

• css: contains the stylesheets
• images: contains the images that are used in the manual
• images_originals: contains original svg files for any special images that may have to be adapted
• intro: introduction to the manual
• misc: miscellaneous content that doesn't (yet) have another home
• mahara.conf: AsciiDoc configuration file for the Mahara manual
• Makefile: compiles any txt file into html when it has been updated
• manual.txt: parent document for the manual in which all other manual files are included