AROS Documentation Manual

ostrzeżenie

This document is not finished! It is highly likely that many parts are out-of-date, contain incorrect information or are simply missing altogether. If you want to help rectify this, please contact us.

This manual describes the AROS documentation system. It is intended to be read by documentation writers as well as developers wishing to extend or tinker with the system itself. To this end, the manual is split into three parts: a common introduction to the system, how to use it for writing documentation and lastly technical notes and specifications. Apart from information about using the system itself, the second chapter also contains some general guidelines to follow when writing documentation for AROS.

spis treści

Introduction

Documentation is vital for the any project, making it useful. Usually, in a project with such a limited developer efforts as ours, documentation is significantly delayed or just absent. Also, most of programmers aren't that good in writing documentation, so that what was already written usually isn't very readable. It is needed to combine the developers and users efforts in documenting to reach the goal of an "AROS Ultimate Documentary". So if you know any users that can help us, just let them! =)

FIXME: Write more?

Writing documentation

The documentation format we use is reStructuredText (or ReST for short) as specified by the Docutils Project. ReST is an easy to read and write, what-you-see-is-what-you-get, extensible, plaintext markup syntax.

You can describe it as a hybrid between a implicit markup syntax and a explicit markup syntax, which makes it easy to learn and highly readable while still being powerful and extensible. The Introduction to reStructuredText contains some good points about the goals of the syntax.

Since the format is basically plaintext it is very easy to learn by simply inspecting existing documentation and using some common sense, but nevertheless it is recommended to at least quickly read through the ReStructuredText Primer before starting to work on AROS documentation.

For more information about the format, the following documents are recommended reading:

Quick reStructuredText Reference

The documentation archive

In order to change or write documentation you need a checkout of the subversion archive 'documentation'. The archive contains:

some common documents like contact.en, links.en etc.
a directory 'db' with some database facts about the project
a directory 'documentation' with user and developer documentation
a directory 'images' with images used on our pages, like banners and logos. This directory must be in place, because the scripts look for images here.
a directory 'introduction' with introduction to project, found in relevant menu of a website
'misc' directory with some additional stuff
a directory 'news' with the news updates which you see on the main page. Filenames in news/data has format of YYYYMMDD.<suffix>
a directory 'pictures' with images related to developer`s photos and screenshot gallery
a directory 'scripts' with the scripts used to build the HTML and WWW targets
a directory 'targets' with additional files needed to build targets
...

przypis

Both the subversion archive and the included directory with the user and developer manuals both have the name 'documentation'. Don't mix them up.

Subdirectories

You can create additional directories in 'documentation/users' and 'documentation/developers'. The build system recursively scans the subdirectories. It is recommended that you create a file 'index.en' in the new directories.

Internationalization

The build system supports I18n for the 'www' target. You have to append a language suffix to the document file name (e.g. commands.en). Currently there is support for English (.en), German (.de), Finnish (.fi), Italian (.it), Russian (.ru), Swedish (.sv) and Dutch (.nl). If you wish to translate documentation into more languages then please contact us via the website mailing list.

When you create a link to a document you have to omit the suffix (e.g `Commands <user/commands>`_). But if you use the 'include' directive for translated documents you must keep the suffix.

The build system uses the English version when no translated page is available.

Sample code

The directory 'documentation/developers/samplecode' is for source code examples. The content is copied unmodified to the targets.

Pictures

The names and paths of the pictures are hard-coded in the python script 'buildit.py'. If you want to add pictures you have to change the script. Feel free to make a feature request in the developer mailing list if you want this to be changed.

Commit

Before you commit the new or modified documents you should build both the HTML and WWW targets locally. Look for error messages and fix them. Check the result in a web browser. Normally, the changes are applied to http://www.aros.org within some hours after a commit.

Technical notes

Databases

There are several small databases, which you can find in the db directory, all of which are plain text files but using a couple of slightly different formats. This is mostly a historical artifact and should perhaps be rectified in the future, but for now it's easiest to keep them as-is.

credits

This is a list of people which have contributed to AROS. The build system first creates the file 'credits.en'. This file is used for both WWW and HTML targets. Please note that you also have to change the file workbench/system/AboutAROS/db/credits in the AROS repository.

quotes

Remarkable quotes of AROS celebrities. The format is spell;author. The build system copies this file to the WWW target.

mirrors

Since AROS is hosted on Sourceforge there aren't any mirrors. This file is ignored by the build system.

tasks

TODO database. This file hasn't been maintained for a long time and isn't used for the targets.

Sizes

The files aros.size and contrib.size aren't used anymore and will probably be deleted.

Building

Requirements

You will need the following to build the AROS documentation from scratch:

Python 2.2.1

To build the website you will additionally need:

The Python Imaging Library 1.1.3

MacOS X comes with Python pre-installed, but to build the website you will need:

The Darwinports package
The Darwinports Python Imaging Library 1.1.3

Setting up

Before you can start building the documentation, there might be some setup required if the needed version of the Python interpreter is not named "python" on your system. If it is, you can simply skip this section.

First, copy the default settings:

% cd AROS/documentation/scripts/config
% cp defaults user

Next, edit the user file and make sure that the variables are correct for your system. An example configuration file might look like this:

PYTHON=python

PYTHON indicates the name of the Python interpreter; it may also be an absolute path if you don't have it in the search path. You might need to set it to python2 or python2.2 on some systems.

Targets

There are currently two targets supported:

www

This target generates the AROS website which includes all documentation, the news, picture galleries with thumbnails and status information. The documentation will integrate nicely with the rest of the site.
html

This target generates standalone HTML from the documentation, suitable for offline viewing and inclusion into documentation packages.

Procedure

To build a specific target, simply invoke the build script with the target name as the first argument. The current directory needs to be the root of the documentation tree. For example, to build the website do:

> cd AROS/documentation
> ./build www

If you want to build the standalone HTML documentation:

> cd AROS/documentation
> ./build html

Tip: adding a language suffix (e.g. en, du or it) after the target name generates only pages for that given language. All missing or non-translated pages are off course still substituted with their English counterparts. This results in strongly decreased compile times.

> cd AROS/documentation
> ./build www du

The generated files will be put in ../bin/documentation/<target-name>, e.g.. ../bin/documentation/www for the www target. Specific language files are put into ../bin/documentation/<target-name>/<language-name>.

Additionally, there is a clean target, which will delete the entire ../bin/documentation directory.

przypis

There are currently quite many intermediate files generated in the source directories, so you cannot put it on a read-only filesystem. If you have checked out the sources from SVN there's no need to worry: the generated files are ignored as appropriate.