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
• ...

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.

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 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 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 name only 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://www.aros.org 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 artifact 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 du