TN 002

Alpha Technical Note #002

How to update the doc

Introduction
Guided tour of the documentation sources
Modifying the doc
Generating the doc
Related Links

Introduction

This note is intended for documentation writers who want to modify some parts of Alpha's documentation.
It explains how the documentation is written and how it is generated. There are several ways Alpha can find help required by the user. The help file called Doc Files Help gives a complete description of the different possibilities.
We focus here, not on the help mechanism, but on the way the existing help files can be modified, expanded, rephrased etc.

Guided tour of the documentation sources

Alpha's help is now written using a markup language named Aida (see the Aida project at SourceForge). The final documentation in HTML format is generated from the Aida source files.
The documentation sources are part of the Alpha source code. If you do not already have a working copy of the source code, see QA #1: How do I get Alpha's source code ?.
The documentation sources are found in the Doc directory inside the Current folder. The Doc directory is divided into subdirectories containing various kinds of documentation. You will generally be interested in the following ones:

the AlphaTcl directory contains help files related to some packages included in the AlphaTcl library. They are divided into subfolders: Features, Menus, Modes, and SystemCode.
the Commands directory contains the documentation for each core command. Each core command has a description in the Syntax subdir. Moreover the complex commands (with subcommands and many options) have an exhaustive documentation found in the Reference subdirectory.
the Manuals directory contains the user and developer manuals.
the Topics directory contains help files concerning more specific aspects of Alpha's capacities.

The Doc folder also contains macros files which can be loaded in the Aida files. The top macros files (which calls all the others) is AlphaHelpMacros.tcl.

Modifying the doc

You can edit any source file and modify it. If you want to take full advantage of the possibilities offered by the Aida syntax, you should read the following documents:

Generating the doc

The Doc folder contains a Makefile with a lot of make rules used to generate the final documentation by converting the aida sources into the target format.
Alpha has an aida processor included in the application bundle. You do not have to know how the processor must be invoked. The make rules take care of this. All you have to do is to call the relevant make rule to process your file. These rules have a consistent syntax: the name of the rule generally takes the form prefix-name where prefix is a string corresponding to the subdirectory and name is the name of the file without its extension.
The converted files will be found in the Alpha working directory in Current/Libraries/AlphaTcl/Help (or in one of its subdirectories).
Here are a few examples:

to generate the reference documentation for the [binding] core command:
```
    make ref-binding
```
to generate the Quick Start help file:
```
    make manual-QuickStart
```
to generate the Dictionaries Help help file:
```
    make feature-DictionariesHelp
```
to generate the Keyboard Shortcuts help file:
```
    make topic-KeyboardShortcuts
```

In case of doubt about the exact syntax of a rule, have a look at the Makefile or type the following command:

    make help

Introduction

Guided tour of the documentation sources

Modifying the doc

Generating the doc

Related Links