The documentation archive

In order to change or write documentation you need a clone of the Git repository '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 an introduction to the project, found in the relevant menu of a website
• a 'misc' directory with some additional stuff
• a directory 'news' with the news updates which you see on the main page. Filenames in news/data have format of YYYYMMDD.<suffix>
• a directory 'pictures' with some images related to developers' photos and a 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
• ...

Subdirectories

It's possible to 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 any new directory.

Internationalization

The build system supports internationalization for the 'www' target. To make this possible, every document filename should have a language suffix appended (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.

Autodocs

Autodocs are a method to embed documentation in source code. It is mainly used for Shell commands and functions of runtime and linker libraries.

The rules for an autodoc block are:

• Block must start with a slash and at least 6 stars. (it's usually a line with 77 stars.)

• Block ends with at least 7 stars. (again usually 77 stars.)

• You can find the rules for documenting library functions in the document about system development.

• Autodocs for Shell functions are similar. Here is an example for the function "Alias":

  /*****************************************************************************
  
      NAME
  
          Alias
  
      SYNOPSIS
  
          NAME,STRING/F
  
      LOCATION
  
          Sys:c
  
      FUNCTION
  
          Alias allows you to create an alternate name for other DOS commands.
          If Alias is used with no parameters, it will display the current
          list of Aliases defined within the current shell.
  
          Using a pair of square brackets within an alias allows you to
          provide the 'new' dos command with parameters.
  
          If no parameters are specified, the current list of aliases are
          displayed.
  
      INPUTS
  
          NAME    - The name of the alias to set.
  
          STRING  - The value of the alias NAME.
  
      RESULT
  
          Standard DOS error codes.
  
      NOTES
  
      EXAMPLE
  
          Alias DF "Type [] number"
  
              By typing "DF S:Shell-Startup" in the shell, you are actually
              executing the command "Type S:Shell-Startup number". This will
              display the contents of the S:Shell-Startup file in the shell
              with line numbers on the left hand side.
  
      BUGS
  
      SEE ALSO
  
          Unalias
  
      INTERNALS
  
  ******************************************************************************/
  

• The titles (NAME, SYNOPSIS, etc.) must be written in upper case and must start at column 5.

• The text blocks should start at column 9.

• If you want to mark a function as internal put the letter "i" somewhere within the first 6 stars in the initial comment line. This way the autodoc is ignored by the build script.

• The "SEE ALSO" chapter is parsed and hyperlinks are created. The rules are:

  • The entries must be separated by comma or newline.
  • A solitary name is interpreted as Shell command.
  • A name with round brackets (e.g. "Draw()") is interpreted as function which exists in the same library.
  • An entry like "exec.library/FreeMem()" causes a link to the document of the given library.
  • A path which ends with ".h" (e.g. "graphics/bitmap.h") is turned into a link to a header file.
  • Anything else is just interpreted as plain text.

The autodocs are translated to the ReST format by the script "autodoc.py". This script can be called from the main build script like this:

./build alldocs

The script must have access to the AROS source code. Thus the AROS sources and the documentation archive must be checked out like this:

AROS
    ...
    workbench
    ...
    documentation
        scripts

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://aros.sourceforge.net/ within one day after a commit.

Style guide

• Be consistent.
• Enable 8 bit character sets like ISO8859-1 in your text editor.
• Don't use slang abbreviations, like "apps", "docs".
• For apostrophes use only ' (decimal ASCII code 39). Don't use accent characters for this.
• Insert line breaks. Don't make lines longer than 80 characters.

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 artefact and should perhaps be rectified in the future, but for now it's easiest to keep them as-is.

Building

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

PYTHON=python

> cd AROS/documentation
> ./build www

> cd AROS/documentation
> ./build html

> cd AROS/documentation
> ./build www fi