Initial commit.

[amiga/xmodule.git] / manuals / XModule.texi

\input amigatexinfo
\input texinfo
@c $VER: XModule.texi 3.9 (21.1.97)

@c Remember to update these variables with each release
@set prgname XModule
@set prgver 3.9

@setfilename XModule.guide
@settitle Documentation for XModule @value{prgver} (@value{prgdate})
@setchapternewpage odd
@c @set amiga_convert_nodes <-- this makes node names look like shit!

@titlepage

@title CrossModule
@subtitle @value{prgver}  @today{}
@author by Bernardo Innocenti

Copyright @copyright{} 1993,94,95,96,97 by Bernardo Innocenti, all rights reserved.
Freely distributable.

@page
@vskip 0pt plus 1filll

@end titlepage

@c ******************
@c *      Top       *
@c ******************

@ifinfo
@node Top, Overview, , (dir)
@top

This manual documents @value{prgname} version @value{prgver} released on
@w{@today{}}. It is formatted for viewing with @w{AmigaGuide V@value{agver}}.

Copyright @copyright{} 1993,94,95,96,97 by Bernardo Innocenti, all rights reserved.
Freely distributable.

If you haven't done it yet, please take a look to the release notes first.
@c does not work with latest GeekGadgets snapshot
@c @ref{Top, , release notes, README, README file}.

@menu
* Overview::             An overview of @value{prgname}.
* Distribution::         Licence & Disclaimer.
* Getting Started::      How to run @value{prgname}.
* User Interface::       General notes on the user interface.

* Panels::               Description of all @value{prgname} windows.

* Effects::              List of all the player effects.
* Format Conversion::    Description of module conversion with @value{prgname}.
* Optimization::         How to save memory and disk space with modules.
* ARexx Interface::      Every program should have one nowadays, doesn't it?

* Known Bugs::           Notes on things that are still not working@dots{}
* Future Plans::         What @value{prgname} should feature in the next releases.
* Programmers::          Notes on the C source and TexInfo documentation.
* XModule Format::       Description of the module format used by @value{prgname}.

* History:(History)Main. See what has changed since the last version of @value{prgname}. READ THIS!

* Credits::              Some people I wish to express my gratitude to.
* Author Info::          How to contact me.

* Concept Index::
@end menu
@end ifinfo

@c ******************
@c *    Overview    *
@c ******************

@node Overview, Distribution, Top, Top
@chapter Overview
@cindex Overview of @value{prgname}
@cindex Introduction

 The Amiga computer has standard file formats for almost
everything.  Graphics, text, animation, hypertext and many other
data types can be easily imported into any program that supports the
given standards, but this is not true for music.  Too bad the music
interchange file format defined by Electronic Arts (the old IFF SMUS)
was too poor to be usable in high-quality music sequencers.  Therefore,
every music editor created its own proprietary module format, so that,
for instance, you cannot load into ProTracker music written with
Oktalyzer.

@dfn{@value{prgname}} (pronounced @dfn{Cross Module}) born as a simple
music module conversion utility that tried to solve this problem.  The
project started in early 1993, as a friend of mine (FBY) needed to
convert his modules to ProTracker to perform some effects.  He had an
old PD conversion utility called @dfn{Tracker} that worked only in
particular conditions and was very bogus.  I decided to contact
the author and he let me have the source for Lit.30000 (about $20).

The original program has been completely rewritten from scratch, as the
source was poorly coded.  Now @value{prgname} is a completely different
program, which sports many other features, as module optimization, a
nice user interface and complex module editing functions and it is
quickly turning into a full featured music editor.

This is why I like to call @value{prgname} a @dfn{module processor}. @value{prgname}
is to music processing what ADPro and ImageFX are to image processing.



@c ******************
@c *  Distribution  *
@c ******************

@node Distribution, Getting Started, Overview, Top
@chapter Distribution
@cindex Distribution

@value{prgname} is a @dfn{Freeware} program.  This means that you (probably)
have got it free and @strong{you must not ask any money} if you
decide to copy it for someone else.  If, instead, someone sold you
@value{prgname} for a price higher than the media used to store it on
(i.e.@:, $1 for a DD disk), tell him he should try making money honestly.

I am not asking you to pay for @value{prgname} because I hate the
Shareware concept.  I use a lot of great PD software on my computer,
so I feel that I somehow have to pay my debt and I want to distribute
@value{prgname} as free software; a little gift to all the Amiga
community.  Feel free to distribute @value{prgname} to your friends and
enemies, but, if you do so, you @strong{must} keep the documentation and
the other distribution files together with the executable. The source
code is not required, but I am distributing it to let others take advantage
of my work, so, if possible, try to also include the source.

Aminet and @w{Fred Fish} are especially granted permission to include
@value{prgname} into their PD libraries.  Other PD libraries
are welcome as well.

If you intend to include @value{prgname} or parts of it in a commercial package,
please at least send me a free copy of the product.  I would be honored
to see one of my programs being part of a commercial package.

You can modify or improve @value{prgname} (@pxref{Programmers}), only be
so kind to return the new source code to me, so I can put the new features
in the next release.  @emph{Please}, do not strip my name from the
documentation, the program source, or the executable.

This product is provided @strong{as is}@footnote{In other words:
@value{prgname} never formatted my hard disk nor killed my dog, so I suppose
it won't cause any damage to your system either, but, just in case, do not
blame me if something nasty happens.}, without warranties of any kind: the
author of this program cannot be held liable for any defects in the executable
nor in the documentation or in any other files contained in this package.
Any damage directly or indirectly caused by the use/misuse of @value{prgname}
is the sole responsibility of the user her/him-self.



@c *******************
@c * Getting Started *
@c *******************

@node Getting Started, User Interface, Distribution, Top
@chapter Getting Started
@cindex Usage
@cindex ToolTypes
@cindex Arguments, command line
@cindex Starting @value{prgname}


@value{prgname} requires Kickstart version 2.0 or greater.  The reason is
that I hate programming on old 1.3 and I will not do it any more.  If you
still have not upgraded to 2.0, you'll miss the chance to run
@value{prgname} and many other wonderful programs.  So what are you
waiting for?

@value{prgname} also takes advantage of some 2.1 and 3.0 features, such as
DataTypes, AmigaGuide, Locale and many enhancements for the user
interface.

You can invoke @value{prgname} either from the Shell or Workbench.
@value{prgname} accepts both command line and ToolTypes arguments.
Workbench and Shell parameters are the same.  The full AmigaDOS
template is:

@example
@group
@value{prgname} FROM/M,PUBSCREEN/K,PORTNAME/K,SETTINGS/K,
 CX_POPUP/T,CX_POPKEY/K,CX_PRIORITY/K/N,
 ICONXPOS/K/N,ICONYPOS/K/N,ICONNAME/K
@end group
@end example

@noindent
The @code{FROM} keyword specifies modules to load at startup time.
Standard AmigaDOS wildcards can be used to match more than one module.
From Workbench, you multi-select module icons instead of specifying a
ToolType.

Specifying the @code{PUBSCREEN} keyword, followed by a public screen name,
allows you to open @value{prgname} on an existing public screen.  The given
name should match exactly (case matters), or the system won't be able to
find the requested screen.  If the requested screen does not exist, a new
public screen will be opened, cloning the resolution and colors of the default
public screen (usually the Workbench screen).  Specifying an empty string
(@samp{""}) you will automatically pick the default public screen.
Note that this behavior is not standard: most commodities will abort if the
requested public screen does not exist.  The default is to use or create a
public screen called @samp{@value{prgname}}.

@code{PORTNAME} will change the name of @value{prgname}'s ARexx port.
If a port with this name already exists, a number (eg: @samp{.1}) will be
appended to the name, until a unique name is found.  You can disable the ARexx
port providing an empty string (eg: @samp{""}) for @code{PORTNAME}.  The port name
defaults to @samp{XMODULE}.  For more information about the ARexx port, see
@ref{ARexx Interface}.

@code{SETTINGS} causes @value{prgname} to use the given settings file instead
of looking for the default preferences file.

@code{CX_POPUP} controls wether the user interface should show when
@value{prgname} starts.  The default is to always show the interface.  When used
from the shell, @code{CX_POPUP} acts as a toggle, turning off the user interface.
From Workbench, you specify @code{CX_POPUP=YES} or @code{CX_POPUP=NO} to show and
hide the user interface, respectively.  @xref{Commodities}.

@code{CX_POPKEY} specifies the hotkey that pops up @value{prgname}'s user interface.
The given string should be a valid Commodities input description.  You can disable
@value{prgname}'s Commodities broker specifying an empty string (eg: @samp{""})
for @code{CX_POPUP}.  The default is @samp{ctrl alt x}.  @xref{Commodities}.

@code{CX_PRIORITY} sets the Commodities priority for the @value{prgname} broker.
An high priority causes the input to be processed by @value{prgname} before other
commodities with a lower priority. The priority ranges from +127 to -128.
The default priority is 0.  @xref{Commodities}.

@code{ICONXPOS} specifies the X position of @value{prgname}'s AppIcon.  The default is
to let Workbench choose a suitable position for the icon.

@code{ICONYPOS} specifies the Y position of @value{prgname}'s AppIcon.  The default is
to let Workbench choose a suitable position for the icon.

@code{ICONNAME} specifies the name of @value{prgname}'s AppIcon.  The default name is
@samp{@value{prgname}}.


@c ******************
@c * User Interface *
@c ******************

@node User Interface, Panels, Getting Started, Top
@chapter User Interface
@cindex User Interface
@cindex GUI

@value{prgname}'s GUI follows Commodore's 2.0 style guidelines.  Under Kickstart 3.0
and above, @value{prgname} takes advantage of new OS capabilities to enhance some
aspects of the GUI.

@menu
* Windows Layout::
* Shortcut Keys::
* On-Line Help::
* Localization::
* Commodities::
* Default Icons::
@end menu


@c ******************
@c * Windows Layout *
@c ******************

@node Windows Layout, Shortcut Keys, , User Interface
@section Windows Layout
@cindex Windows Layout
@cindex Layout, of Windows
@cindex Font Sensivity

Gadget and menu layout is font sensitive, but using some fancy fonts could
result in a somewhat weird look.  If you are using a very big font and a
window becomes too big to fit in the screen, @file{topaz/8} will be used as
a fallback for rendering that window.

Most windows are completely scalable and their contents will adapt to the
size you choose, just like a MUI application.  But @value{prgname} does
not use MUI, so I had to do all the GUI engine myself, and it was quite an
hard work for me.  @value{prgname} GUI is not as nice as can be MUI, but
it's much faster and requires much less memory.

When you close a window, it will remember its position and size when you
open it again.  The same is true for window zooming operations.

@value{prgname} will also try to make the active window visible by
scrolling the screen automatically.  This feature comes handy if you use
a virtual screen which is wider and/or taller than the default.


@c ******************
@c *  Shortcut Keys *
@c ******************

@node Shortcut Keys, On-Line Help, Windows Layout, User Interface
@section Shortcut Keys
@cindex Shortcut Keys
@cindex Keys, Shortcuts


 In all windows, the following shortcut keys are active:

@table @kbd
@item ESC
Close the active window.  Does not work with ToolBox window, as it would
make it too easy to accidentally exit the program.

@item HELP
Bring up AmigaGuide on-line help.  @xref{On-Line Help}.

@item TAB
Cycles forward through string and numeric gadgets within the active
window.  @kbd{SHIFT-TAB} will cycle backwards.  @kbd{TAB} also
activates the first string or numeric gadget if none is selected.

@item Alt-TAB
Activates the next @value{prgname} window. @kbd{ALT-SHIFT-TAB}
activates the previous window.

@item RETURN
Activate the first string or numeric gadget in the active window.

@item Cursor UP/DOWN
Move up and down in a viewlist whenever the active window contains one.
@kbd{SHIFT-Cursor} moves 5 items up/down. @kbd{ALT-Cursor} moves to the
top or to the bottom of the list.  This shortcut requires at least
Kickstart 3.0.
@end table

In addition, gadgets with underscored characters in labels, can be
operated hitting the highlighted key.  @kbd{SHIFT-key} acts the opposite
of the unshifted key (sliders are decremented by one, cycle gadgets will
cycle backwards, etc.@:).  Keyboard shortcuts will not work for all gadget
kinds under Kickstart 2.0.



@c ******************
@c *  On-Line Help  *
@c ******************

@node On-Line Help, Localization, Shortcut Keys, User Interface
@section On-Line Help
@cindex On-Line Help
@cindex Help, On-Line

This feature requires @file{amigaguide.library}, which is distributed
with Workbench version 2.1 and up, and @file{@value{prgname}.guide}
located in the current directory or in the same directory of
@value{prgname}'s executable or in the @file{HELP:language/} directory,
where @samp{language} is any of your Locale preferred languages.
AmigaGuide(TM) is also available as a freely distributable package
for 1.3-2.0 users.

To get help on a gadget, press @key{HELP} while the mouse pointer is
over the gadget.  To get help on a string gadget, activate it and
press @key{HELP}.  Hitting @key{HELP} while the mouse isn't over a
gadget, will give you help on the active window.

To get help on a menu item, hilight the item and press @key{HELP} while
keeping the right mouse button pressed.



@c ******************
@c *  Localization  *
@c ******************

@node Localization, Commodities, On-Line Help, User Interface
@section Localization
@cindex Localization
@cindex Language selection
@cindex Writing a new language catalog

Localization requires @file{locale.library},  which is distributed
with Workbench version 2.1 and up, and the catalog file
@file{@value{prgname}.catalog} located in the same directory of
@value{prgname}'s executable or in the @file{LOCALE:catalogs/language/}
directory, where @samp{langage} is is any of your Locale preferred
languages.

If you speak a language for which a catalog isn't yet available, please
consider writing it yourself and then send it to me, so it will be
included in the next release of @value{prgname}.  Look at the empty
catalog translation file @file{Empty.ct} in the @file{Catalogs/}.
It can be used to create new catalog descriptions for @value{prgname}.
Then, use a tool like @cite{FlexCat}, @cite{KitKat} or @cite{CatComp}
to compile it into a catalog file.  Please read the @cite{HowToTranslate.doc}
before you start translating: it contains many tips and suggestions
which may come useful.


@c ******************
@c *   Commodities  *
@c ******************

@node Commodities, Default Icons, Localization, User Interface
@section Commodities support
@cindex Break signals

@value{prgname} is a Commodity and can be controlled by the
Commodities Exchange program.

@value{prgname} will pop up when its hotkey is typed; the main window
will activate and the screen will move to the front.  If
@value{prgname}'s interface is hidden, it will be revealed.

The user interface can be hidden with the Exchange program.
When the user interface is hidden, the only ways you have to still
operate @value{prgname} is through the ARexx port or the AppIcon.

You can also control @value{prgname} by sending the following
signals to its process:

@table @bullet
@item @kbd{CTRL-C}
Quit @value{prgname}.

@item @kbd{CTRL-D}
Disable the Commodities broker (equivalent to selecting @code{Inactive}
with Commodities Exchange).

@item @kbd{CTRL-E}
Enable the Commodities broker (equivalent to selecting @code{Active}
with Commodities Exchange).

@item @kbd{CTRL-F}
Deiconify @value{prgname} (equivalent to double-clicking on the AppIcon).
@end table



@c ******************
@c * Default  Icons *
@c ******************

@node Default Icons, , Commodities, User Interface
@section Default Icons
@cindex Icons, changing defaults
@cindex def_Instrument
@cindex def_Module

When @value{prgname} creates an icon for a file, it looks for the user
preferred icon for the type of data being saved.

The template icons can be placed in the @file{Icons} drawer which is
located in the same drawer where the @value{prgname} executable resides.
@value{prgname} will also look for its icons in the @file{ENV:Sys/}
directory.  If you choose to use @file{ENV:Sys/}, you will probably want
to store the icons in @file{ENVARC:Sys/} to have them copied automatically
to @file{ENV:Sys/} every time the system boots up.

Template icons should be only of type @dfn{Project}.  When @value{prgname}
does not find a template icon, it uses the default Project icon instead.

Whenever the default icon does not have its own default tool, it will be
set to @value{prgname}'s executable.

The following default icons are supported:

@table @minus
@item @file{def_Module}
@item @file{def_Instrument}
@end table



@c ************
@c *  Panels  *
@c ************

@node Panels, Effects, User Interface, Top
@chapter Panels
@cindex Panels
@cindex Windows

Sorry, XModule's documentation is still incomplete.  Not all
the following links are finished.

@menu
* ToolBox::
* Pattern Editor::
* Instruments::
* Song Information::
* Sequence::
* Save Format::
* Clear Song::
* Sample Editor::
@end menu



@c ******************
@c * ToolBox Window *
@c ******************

@node ToolBox, Pattern Editor, , Panels
@section ToolBox Window

@subsection Gadgets

@vtable @code
@item Patterns (P)
Opens or activates the @ref{Pattern Editor} window.

@item Instruments (I)
Opens or activates the @ref{Instruments} window.

@item Sequence (Q)
Opens or activates the @ref{Sequence} editor.

@item Songs (S)
Opens or activates the @ref{Song Information} window.

@item Optimization (O)
Opens or activates the @ref{Optimization} window.

@item Play (P)
This option has not been implemented yet.
@end vtable



@subsection Project Menu

@vtable @code
@item New (Amiga-N)
Creates a new empty song.

@item Open (Amiga-O)
Opens a song over the current one.  A file requester will be put
up to let you choose the module.  The file requester is asynchronous,
so you can continue operating @value{prgname} while keeping the requester
open.  You can use multiselection to open several modules at once.

@item Save (Amiga-S)
Saves the current song to the same path it was loaded from.

@item Save As (Amiga-A)
Opens a file requester and saves the current song to the selected file
name and path.

@item Clear Module (Amiga-K)
Opens or activates the @ref{Clear Song} panel.

@item About (Amiga-?)
Brings up a requester showing various information on @value{prgname}.

@item Help (HELP)
Shows the main node of the AmigaGuide on-line help. @xref{On-Line Help}.

@item Iconify (Amiga-I)
Closes all open windows and screens and puts an AppIcon on the Workbench.
You can De-Iconify @value{prgname} by double clicking on the icon or by
using @code{Show Interface} in the Commodities Exchange program.
@xref{Commodities}.

@item Quit (Amiga-Q)
Quits @value{prgname}.  A requester will ask if you are sure if the
@code{Settings/Confirm Exit} menu item is checked.
@end vtable



@subsection Settings Menu

@vtable @code
@item Save Format
Opens or activates the @ref{Save Format} window.

@item User Interface
Opens or activates the @ref{User Interface} window.

@item Save Icons?
When this menu item is checked, @value{prgname} will automatically add
an icon to the files it saves. @xref{Default Icons}.

@item Confirm Overwrite?
When this menu item is checked, @value{prgname} will ask before
overwriting an existing file when saving something.

@item Confirm Exit?
When this menu item is checked, @value{prgname} will ask
if you are really sure before quitting.

@item Verbose?
When this menu item is checked, @value{prgname} will be output more
detailed information on various operations.

@item Open Settings
Opens a file requester asking for an XModule preferences file.  The
changes will take place immediately.

@item Save Settings
Saves the current settings to @file{PROGDIR:XModule.prefs}, which
is where preferences are looked for first.

@item Save Settings As
Opens a file requester and saves the current settings to the selected
file and path name.
@end vtable



@c ******************
@c * Pattern Editor *
@c ******************

@node Pattern Editor, Instruments, ToolBox, Panels
@section Pattern Editor Window
@cindex Pattern Editor Window
@cindex Notation

@subsection Overview

 The pattern editor is used to actually edit notes into your song.
A song is made up of several patterns which are played one after the
other following the order defined in the @ref{Sequence} editor.

 A pattern is subdivided into @dfn{tracks}. Each track is made of
several note slots.  Each note slot has four basic fields: the
actual note, the number of the instrument used to play this note,
a field for the @dfn{effect} (also called @dfn{command}) and a
@dfn{value} for the effect, the meaning of which depends from
the type of effect (@pxref{Effects}).  A @dfn{line} is an horizontal
set of note slots.  The lines are numbered starting from 0 (line
numbers are displayed in the leftmost column of the pattern editor).

 A pattern can have 1 to 32 tracks.  The more the tracks, the more the
notes that can be played at the same time.  When @value{prgname} plays
a pattern, it reads the lines one by one, playing all the notes and
executing all the effects as soon as it encounters them.  A pattern
line can be imagined as one sixteenth of a beat when the pattern is
played at the default speed and tempo.

 A pattern row looks like this:

@example
C-2 5 C40
~~~ | |~~
|   | ||
|   | |+---- Effect Value
|   | +----- Effect Command
|   +------- Instrument
+----------- Note
@end example

 Notes are shown in anglosaxon notation, followed by the octave number.
So @code{C-2} is a second octave @code{DO} in classic notation and
@code{A#3} is a third octave diesis @code{LA}.  There are 5 octaves
numbered from 0 to 4; a @code{C-2} note is twice the frequency of a
@code{C-1}, and it's instrument will be played at double speed.

 The duration of the note is determined by the space left from one note
to the next.  For example, if a note is immediately followed by another
note on the same track, it's duration will be one sixteenth of a beat
at four quarters.  If two notes are put one at line n and the other
at line n+4 (leaving three blank spaces between), the duration of the
first note will be exactly one quarter.

 Calculating the duration of a note can become trickier when weird
combinations of speed and tempo are used.  Also, notes can be
associated to instruments which have an endless loop (like a flute)
or to instruments that only last for a short time and then stop
(like a snare drum).  In the latter case, the duration of a note could
be shorter than it's distance from the following note.  Experience
will help understanding these simple rules.


@subsection Editor Keys

@table @kbd
@item up
@itemx down
@itemx left
@itemx right
Move the cursor one position towards the respective direction. Keeping
cursor keys pressed will repeat the movement until the key is released.

 Cursor keys in combination with the @kbd{SHIFT} key will move the cursor
a whole page up/down or one track left/right, keeping it on the same
column.

 Cursor keys in combination with the @kbd{ALT} key will move the cursor
to the top/bottom/leftmost/rightmost position.

 Cursor keys in combination with the @kbd{CTRL} key will scroll the view
without moving the cursor. This is useful to reveal something without
having to reposition the cursor.

@strong{NOTE:} You can adjust the repeat speed and delay with the
@cite{Input} system preferences.

@item TAB
Move to the note column of the next track.  Pressing @kbd{TAB} on the last
track, will bring the cursor to the first track.  @kbd{SHIFT-TAB} moves
backwards.

@item DEL
Delete the field under the cursor.  @kbd{SHIFT-DEL} kills all the note slot
(note, effect and value).
@end table



@subsection Project Menu

@vtable @code
@item Open Pattern (Amiga-O)
Opens a file requester where you can select a pattern to be loaded in
place of the current one.

@item Save Pattern (Amiga-S)
Saves the current pattern to a file with the same name of the pattern.
If the pattern has no name, a file requester will open.

@item Save Pattern As (Amiga-A)
Opens a file requester where you can select the file and path name where
the current pattern will be saved to.
@end vtable



@subsection Edit Menu

@vtable @code
@item Mark (Amiga-M)
Toggles mark mode in the pattern editor.

@item Cut (Amiga-X)
Copies the currently marked region to the clipboard and erases it from
the pattern.

@item Copy (Amiga-C)
Copies the currently marked region to the clipboard.

@item Paste (Amiga-V)
Gets the last pattern stored into the clipboard and pastes it in the
current pattern starting at the current cursor position.

@item Erase (Amiga-E)
Clears the currently marked region.

@item Undo (Amiga-U)
Restores the pattern to the state it was before the last
modification.

@item Redo (Amiga-Y)
Remakes the last change undone with the Undo function.
@end vtable



@c ******************
@c *   Instruments  *
@c ******************

@node Instruments, Song Information, Pattern Editor, Panels
@section Instruments Editor Window
@cindex Instruments Editor Window

@subsection Gadgets

@vtable @code
@item Instruments List (Cursor up/down)
This list shows all the instruments of a song.  The leftmost column
is the instrument number (hexadecimal), followed by its name.
Some musicians usually use the instrument names to include short
texts inside the modules they distribute.  Picking an instrument
from this list will set it as the current instrument.  An empty
instrument slot with no name will have the word @samp{--empty--}
in place of its name.

@item Instrument Name (RETURN or TAB)
(The string gadget immediately below the Instruments list). Allows
editing the name of the currently selected instrument.

@item Volume (V)
Default instrument volume.  Ranges from 0 (mute) to 64 (maximum
volume).

@item Fine Tune (F)
Sets the instrument fine tune.  0 is the default tuning.  Negative
values cause the instrument to be played at a slightly lower
frequency.  Positive values cause the instrument to be played at
a slightly higher frequency.

@item Lenght
Displays the instrument lenght in bytes.

@item Kind (K)
This function has not yet been implemented.

@item Edit (E)
Opens or activates the @ref{Sample Editor} panel.
@end vtable



@subsection Instruments Menu

@vtable @code
@item Load (Amiga-L)
Loads an instrument in the current intrument slot.  A file requester
will be put up to let you choose the instrument.  The file requester
is asynchronous, so you can continue operating @value{prgname} while
keeping the requester open.
@item Save (Amiga-S)
Saves the current instrument to a file with its current name.

@item SaveAs (Amiga-A)
Opens a file requester and saves the current instrument to the
selected file name and path.

@item Remap (Amiga-R)
Remaps all the instruments removing all empty slots between them.
The song patterns are updated to keep the correct instruments.
This function is useful to save a module to a format which has a
limited number of instruments, like @ref{SoundTracker}.
@end vtable



@c ********************
@c * Song Information *
@c ********************

@node Song Information, Sequence, Instruments, Panels
@section Song Information Window
@cindex Song Information Window

@subsection Gadgets

@vtable @code
@item New
Creates a new module and makes it the current module.

@item Del
Deletes the current module from memory. If the module has been
modified since last saving, a requester will give you the chance
to abort the operation.

@item Open... (O)
Opens a song over the current one.  A file requester will be put
up to let you choose the module.  The file requester is asynchronous,
so you can continue operating @value{prgname} while keeping the requester
open.  You can use multiselection to open several modules at once.
This gadget behaves exactly like the @code{Open} menu item in the @ref{ToolBox}
panel.

@item Save (S)
Saves the current song to the same path it was loaded from.
This gadget behaves exactly like the @code{Save} menu item in the @ref{ToolBox}
panel.

@item Song Name (N)
Displays the name of the current song.  You can use any character in the song
name, but keep in mind that the name you type will be used by default as the
filename for the song, so be careful with special characters such as @samp{/}
and @samp{:}!

@item Author (A)
Displays the author of the current song.  @value{prgname} tries to guess the
author when it loads a module whose format has no direct support for embedded
author name. @value{prgname} scans the instruments names looking for a line
beginning with a pound sign (@samp{#}). This convention started with
@cite{IntuiTracker}, an old module player for the Amiga. If the author name
can't still be found, @value{prgname} looks again for an occurence of @samp{by },
@samp{by:} or @samp{(c)}, which is usually followed by the author name.
The author name is ignored when saving to a format which does not support
embedding the author name.

@item Tempo (T)
Displays the default tempo for the current song.  Valid range is 32-255, the
dafult is 125. The default tempo is used when the song starts playing and can
be overridden by the Set Tempo command.  @xref{Effects}.

@item Speed (P)
Displays the default speed for the current song.  Valid range is 1-31, the
dafult is 6. The default speed is used when the song starts playing and can
be overridden by the Set Speed command.  @xref{Effects}.

@item Restart (R)
Displays the position where playback will continue once the song end has
been reached.  The restart position is lost when saving to formats which
do not support it.

@item Patterns
Displays the total number of patterns in the song.

@item Tracks
Displays the maximum number of tracks in the song.

@item Length
Displays the number of positions in the song sequence.

@item Total Module Size
Shows an approximation of the memory used up by the song and its data.
This value will usually be similar to the file size.

@item Total Instruments Size
Shows an approximation of the memory used by all the instruments of the
current song.
@end vtable

@subsection Song Menu

@vtable @code
@item Merge Songs (Amiga-M)

@item Join Songs (Amiga-J)

@item Clear (Amiga-K)

@end vtable



@c ************
@c * Sequence *
@c ************

@node Sequence, Save Format, Song Information, Panels
@section Sequence Editor Window
@cindex Sequence Editor Window

@subsection Gadgets

 Had no time to write it, sorry. ;-)

@subsection Menu

 Had no time to write it, sorry. ;-)



@c ***************
@c * Save Format *
@c ***************

@node Save Format, Clear Song, Sequence, Panels
@section Save Format Window
@cindex Save Format Window

@subsection Gadgets

 Had no time to write it, sorry. ;-)

@subsection Menu

 Had no time to write it, sorry. ;-)



@c **************
@c * Clear Song *
@c **************

@node Clear Song, Sample Editor, Save Format, Panels
@section Clear Song Window

@subsection Gadgets

 Had no time to write it, sorry. ;-)

@subsection Menu

 Had no time to write it, sorry. ;-)



@c *****************
@c * Sample Editor *
@c *****************

@node Sample Editor, , Clear Song, Panels
@section Sample Editor Window

@subsection Gadgets

 Had no time to write it, sorry. ;-)

@subsection Menu

 Had no time to write it, sorry. ;-)



@c *********************
@c *      Effects      *
@c *********************

@node Effects, Format Conversion, Panels, Top
@chapter Effects
@cindex Effects
@cindex Commands

 Had no time to write it, sorry. ;-)



@c *********************
@c * Format Conversion *
@c *********************

@node Format Conversion, Optimization, Effects, Top
@chapter Format Conversion
@cindex Format Conversion
@cindex Module Formats

@value{prgname} can load and save modules created by other
music editors.  The following is a list of all supported module formats:

@menu
* XModule: XModule Format.
* NoiseTracker::
* ProTracker::
* SoundTracker::
* StarTrekker::
* UNIC-Tracker::
* FastTracker::
* TakeTracker::
* Oktalyzer::
* MED::
* OctaMED::
* ScreamTracker::
* MIDI File::
@end menu


As a matter of fact, there are things that simply cannot be done
because of the big differences between different module formats.
Below is a list of the internal limitations of each module format.
When you save to a particular format and the module exceeds one of
these values, or makes use of features not implemented, some data
will be stripped away to produce at least a partial conversion.

@example
@group
@c Is there a better way to make a table like this?

Program          Instr  MaxPatt PattLen SongLen InstrLen Tracks
---------------------------------------------------------------
Oktalyzer         36      128     128     128     128K      4
SoundTracker      15       64      64     128      64K      4
NoiseTracker      31       64      64     128      64K      4
StarTrekker       31       64      64     128      64K     4/8
ProTracker        31      100      64     128      64K      4
Fast Tracker I    31      100      64     128      64K    4/6/8
MED/OctaMED       63      256     256     256   No Limit  1-64

XModule           63      256   32768   32768   No Limit  1-32


Where:
#Instr   is the maximum number of instruments,
MaxPatt  is the maximum number of patterns,
PattLen  is the maximum number of lines per pattern,
SongLen  is the maximum number of positions in a song,
InstrLen is the maximum size of an instrument in bytes,
Tracks   is the maximum number of tracks in a pattern.
@end group
@end example

 Effects are the hardest thing to convert.  While Speed and Volume
are almost the same between different music editors, some effects (such as
Oktalyzer's H and L) cannot be converted because there are no equivalents in
other music editors.  Therefore, you will have to modify the score manually
if you intend to convert a module while keeping such effects.  In addition,
some effects behave in different ways even if they claim to do the same
thing.

 Last but not least, some music editors support synthetic or hybrid
instruments.  @value{prgname} does not convert such instruments,
because I can hardly think of a way to implement a sample to synth
conversion (any ideas?). I used to like synthetic music, but it
seems that all those great composers on the good old C64 have
vanished@dots{}  Why have you musicians become so lazy? 8-(



@c ******************
@c *  NoiseTracker  *
@c ******************

@node NoiseTracker, ProTracker, , Format Conversion
@section NoiseTracker
@cindex NoiseTracker

Noise/ProTracker 31 instruments module.  This is absolutely the
most common module format; almost any music editor and module
player (even the crap ones for the PeeCee) understand this
format.  Noise/ProTracker modules can be recognized by looking for
the ID @samp{M.K.} at offset 1080 ($438 in hex) in the file.
Andrew Scott, the author of MidiMod, says that @samp{M.K.} are
the initials of Mahoney & Kaktus, the two guys who designed this
format.  Peter Kunath, the author of DeliTracker, points out that
@samp{M.K.} are more likely to be the initials of Michael Kleps
(aka Unknown/DOC).

Unfortunately, there is an infinite variety of standard
NoiseTracker modules with fancy IDs. In fact, most tracker
clones put their own ID instead of the standard one even if
there is no reason to do it.  If you find such a module, try
replacing the ID with an hex editor and you will be able to
load it most of the times.



@c ******************
@c *   ProTracker   *
@c ******************

@node ProTracker, SoundTracker, NoiseTracker, Format Conversion
@section ProTracker 100 Patterns
@cindex ProTracker
@cindex M!K!
@cindex 100 Patterns ProTracker modules

@value{prgname} will automatically switch to @code{ProTracker 100}
whenever the module being saved exceeds the 64 patterns limit of
NoiseTracker modules.
Modules with more than 64 patterns have the ID @samp{M!K!} instead
of the standard Noise/ProTracker ID (@samp{M.K.}).

@strong{Note:} You @emph{must} load such a module with ProTracker 2.3 or
better in order to play/edit it.  Older players will either refuse
to load it or they'll turn the module into scratch dance.

ProTracker 3.0+ has a completely new file format, but this isn't
supported yet, as I've never seen a module of this kind yet.



@c ******************
@c *  SoundTracker  *
@c ******************

@node SoundTracker, StarTrekker, ProTracker, Format Conversion
@section SoundTracker 15 Instruments
@cindex SoundTracker

This format is pretty useless as SoundTracker is becoming really rare.
Do not save SoundTracker modules unless you really need to, because
most players/editors will stop supporting this format very soon.
There is no way to identify a SoundTracker module, therefore
@value{prgname} will ask you to confirm a SoundTracker module when
the file being loaded matches no other known module format.



@c ******************
@c *  StarTrekker   *
@c ******************

@node StarTrekker, UNIC-Tracker, SoundTracker, Format Conversion
@section StarTrekker
@cindex StarTrekker

StarTrekker is another NoiseTracker clone, which is capable of
playing modules with 4 or 8 channels and supports MIDI devices.
The format of 4 channels modules is the same of NoiseTracker, except
for the @samp{FLT4} ID.  Modules with 8 channels have the ID
@samp{FLT8}, and keep the extra data in a second file, whose
structure I don't know.  If you want support for 8 channels
StarTrekker modules, please send me some information on its
format.



@c ******************
@c *  UNIC-Tracker  *
@c ******************

@node UNIC-Tracker, FastTracker, StarTrekker, Format Conversion
@section UNIC-Tracker
@cindex UNIC-Tracker

Actually, I've never seen UnicTracker, but I sometimes ripp Unic modules
with ExoticRipper, so I decided to give support for this weird Tracker
clone too.  The format is very similar to that of ProTracker modules,
except for the @samp{EMW3} ID.



@c ******************
@c *  FastTracker   *
@c ******************

@node FastTracker, TakeTracker, UNIC-Tracker, Format Conversion
@section FastTracker 1.0
@cindex FastTracker
@cindex 6CHN
@cindex 8CHN

The format of FastTracker 1.0 modules is exactly the same
of @ref{TakeTracker}, but they can have only 6 or 8 channels.
@value{prgname} does not support FastTracker 2.0 modules (those
with extension @file{.xm}) yet.

@c ******************
@c *  TakeTracker   *
@c ******************

@node TakeTracker, Oktalyzer, FastTracker, Format Conversion
@section TakeTracker
@cindex TakeTracker
@cindex 32 Channels ProTracker Modules

These are Standard ProTracker modules, but they can have up to 32
channels.  Their ID is @dfn{5CHN}, @dfn{6CHN}, and so on, up to
@dfn{32CH}.  This format comes from some damn PeeCee tracker, which
I've never seen.  Anyway, adding this format was a matter of five
minutes.


@c ******************
@c *   Oktalyzer    *
@c ******************

@node Oktalyzer, MED, TakeTracker, Format Conversion
@section Oktalyzer 1.1
@cindex Oktalyzer

Oktalyzer is an old editor which can play up to 8 channels by mixing
instruments in real time.  Oktalyzer modules start with the ID
@samp{OCTASONGGMOD}.  Development of Oktalyzer has been
discontinued, as the author seems to be programming on Windoze now.
It's really a shame, as many musicians found that Oktalyzer was one
of the most powerful trackers for the Amiga.



@c ******************
@c *      MED       *
@c ******************

@node MED, OctaMED, Oktalyzer, Format Conversion
@section MED
@cindex MED

 Not all features of MED are supported by @value{prgname}.
Synthetic and hybrid instruments are ignored.



@c ******************
@c *    OctaMED     *
@c ******************

@node OctaMED, ScreamTracker, MED, Format Conversion
@section OctaMED
@cindex OctaMED
@cindex MMD Format

 MMD2 modules are not supported.  @value{prgname} will only
load the first song in multisong modules.

 @value{prgname} currently has an internal limit of only
32 tracks, while OctaMED can do up to 128 tracks.  However,
OctaMED can only play the first 8 tracks, so what are
the other tracks for? ;-)



@c ******************
@c * ScreamTracker  *
@c ******************

@node ScreamTracker, MIDI File, OctaMED, Format Conversion
@section ScreamTracker
@cindex ScreamTracker
@cindex S3M Format

 ScreamTracker 3.01 is a damn PeeCee program made by those Future Crew
guys who are trying to turn clones into Amigas.  ScreamTracker has the
amazing feature of playing 32 tracks, 16 of which are for 8-bit
digital samples.  The other 16 tracks play ADLib FM synths (not
supported by @value{prgname}).



@c ******************
@c *   MIDI  File   *
@c ******************

@node MIDI File, , ScreamTracker, Format Conversion
@section MIDI File
@cindex MIDI File

 MIDI is the industry standard musical score format (the same way Windoze
is the industry standard graphic interface :-).  The MIDI concept is very
different from tracker modules.  There are no sequence and patterns, but a
long stream of events (notes) that have to be sent to some MIDI compliant
device, one after the other, at specific time intrvals, based on the
duration of each note.  There are no instruments inside MIDI files;
instead, each note is associated with a preset number that matches a
particular instrument in the device to which the MIDI events are sent.

 @value{prgname}'s MIDI file saver is based on Andrew Scott's MidiMod
program and I wish to thank him for granting me permission to use his
code in @value{prgname}.



@c ******************
@c *  Optimization  *
@c ******************

@node Optimization, ARexx Interface, Format Conversion, Top
@chapter Optimization
@cindex Optimization

 Module optimization is achieved by removing all unused data in such a way
that the module will sound the same as before.  @value{prgname} can process a
module to reduce its size as much as possible.  It is generally a good idea
to optimize a module before distributing it, but never while you are still
composing it, because you could easily loose some data that you didn't want
to discard.  Do not expect to gain a lot of bytes optimizing modules: saving
20% of the total size is usually a very good result.

@table @bullet{} @code
@item Unused patterns
 Some formats (e.g.: Sound/Noise/ProTracker) store empty patterns
in a module if a pattern with a greater number is used.  For instance,
a song using patterns 1, 2 and 5 will contain patterns 3 and 4 as well.

@strong{Warning}: If a song contains a part that has not been finished
yet and has not already been inserted in the position table, you will
lose it.

@strong{Warning}: When a song is saved to Noise/ProTracker, patterns beyond
the last used patterns are discarded regardless of this switch.  This
is due to a limitation of Noise/ProTracker module format.

@item Pattern Cutting
When a pattern is breaked with the Pattern Break effect, it is cut to the
line containing the break.  When saving to a format that does not support
variable length patterns (eg.: @ref{SoundTracker}), the pattern is grown
again, so this optimization won't help with such formats.

@item Unused instruments
 A composer may decide to use an instrument and then change his mind,
but forget to clear the instrument.  In this case the module will
contain an instrument that is never played.  These instruments
are simply stripped away.

@item Sample data after a loop
 The part of an instrument following a loop is never played and is
therefore discarded.

@item Instruments zero tails
 Long zero tails eat up memory and produce no sound.  This optimization
is performed only on loopless instruments, as a zero sequence inside a
loop @emph{does} make difference.  @value{prgname} leaves at least two zero
bytes to avoid the nasty click produced by the speaker dropping its volume
to zero too quickly.
@end table


@c *********************
@c *  ARexx Interface  *
@c *********************

@node ARexx Interface, Known Bugs, Optimization, Top
@chapter ARexx Interface

WARNING: XModule's ARexx port is a little brain dead at the
moment, sorry.


List of ARexx commands:

@menu
* Activate: ARexx ACTIVATE.             Not yet implemented
* Clear: ARexx CLEAR.                   Not yet implemented
* Close: ARexx CLOSE.                   Not yet implemented
* Column: ARexx COLUMN.                 Not yet implemented
* Copy: ARexx COPY.                     Not yet implemented
* Cursor: ARexx CURSOR.                 Not yet implemented
* Cut: ARexx CUT.                       Not yet implemented
* Deactivate: ARexx DEACTIVATE.         Not yet implemented
* Erase: ARexx ERASE.                   Not yet implemented
* GoToBookMark: ARexx GOTOBOOKMARK.     Not yet implemented
* Help: ARexx HELP.                     Displays help on a particular topic
* Line: ARexx LINE.                     Not yet implemented
* LockGUI: ARexx LOCKGUI.               Blocks user input in @value{prgname} windows
* New: ARexx NEW.                       Creates a new song
* Open: ARexx OPEN.                     Opens a song over the current one
* Optimize: ARexx OPTIMIZE.             Performs an @ref{Optimization}
* Paste: ARexx PASTE.                   Not yet implemented
* Print: ARexx PRINT.                   Not yet implemented
* Quit: ARexx QUIT.                     Exits @value{prgname}
* RequestFile: ARexx REQUESTFILE.       Not yet implemented
* RequestResponse: ARexx REQUESTRESPONSE. Not yet implemented
* RequestNotify: ARexx REQUESTNOTIFY.   Not yet implemented
* Save: ARexx SAVE.                     Saves the current song
* SaveInstrument: ARexx SAVEINSTRUMENT. Saves the current instrument
* ScreenToBack: ARexx SCREENTOBACK.     Brings @value{prgname}'s screen to front
* ScreenToFront: ARexx SCREENTOFRONT.   Brings @value{prgname}'s screen to back
* SelectInstrument: ARexx SELECTINSTRUMENT. Selects the current instrument
* SetBookMark: ARexx SETBOOKMARK.       Not yet implemented
* ShowMessage: ARexx SHOWMESSAGE.       Prints a message in the log window
* UnLockGUI: ARexx UNLOCKGUI.           Restores user input in the user interface
* Version: ARexx VERSION.               Returns version information about @value{prgname}
@end menu




@c **************
@c *  ACTIVATE  *
@c **************

@node ARexx ACTIVATE, ARexx CLEAR, , ARexx Interface
@section ACTIVATE

@subsection Template
@example
ACTIVATE
@end example

@subsection Description

-

@subsection See Also

-



@c ***********
@c *  CLEAR  *
@c ***********

@node ARexx CLEAR, ARexx CLOSE, ARexx ACTIVATE, ARexx Interface
@section CLEAR

@subsection Template
@example
CLEAR
@end example

@subsection Description

-

@subsection See Also

-

@c ***********
@c *  CLOSE  *
@c ***********

@node ARexx CLOSE, ARexx COLUMN, ARexx CLEAR, ARexx Interface
@section CLOSE

@subsection Template
@example
CLOSE
@end example

@subsection Description

-

@subsection See Also

-

@c ************
@c *  COLUMN  *
@c ************

@node ARexx COLUMN, ARexx COPY, ARexx CLOSE, ARexx Interface
@section COLUMN

@subsection Template
@example
COLUMN
@end example

@subsection Description

-

@subsection See Also



@c **********
@c *  COPY  *
@c **********

@node ARexx COPY, ARexx CURSOR, ARexx COLUMN, ARexx Interface
@section COPY

@subsection Template
@example
COPY
@end example

@subsection Description

-

@subsection See Also

@xref{ARexx CUT,CUT}, @xref{ARexx PASTE,PASTE}, @xref{ARexx ERASE,ERASE}.



@c ************
@c *  CURSOR  *
@c ************

@node ARexx CURSOR, ARexx CUT, ARexx COPY, ARexx Interface
@section CURSOR

@subsection Template
@example
CURSOR
@end example

@subsection Description

-

@subsection See Also



@c *********
@c *  CUT  *
@c *********

@node ARexx CUT, ARexx DEACTIVATE, ARexx CURSOR, ARexx Interface
@section CUT

@subsection Template
@example
CUT
@end example

@subsection Description

-

@subsection See Also



@c ****************
@c *  DEACTIVATE  *
@c ****************

@node ARexx DEACTIVATE, ARexx ERASE, ARexx CUT, ARexx Interface
@section DEACTIVATE

@subsection Template
@example
DEACTIVATE
@end example

@subsection Description

-

@subsection See Also



@c ***********
@c *  ERASE  *
@c ***********

@node ARexx ERASE, ARexx GOTOBOOKMARK, ARexx DEACTIVATE, ARexx Interface
@section ERASE

@subsection Template
@example
ERASE
@end example

@subsection Description

-

@subsection See Also



@c ******************
@c *  GOTOBOOKMARK  *
@c ******************

@node ARexx GOTOBOOKMARK, ARexx HELP, ARexx ERASE, ARexx Interface
@section GOTOBOOKMARK

@subsection Template
@example
GOTOBOOKMARK
@end example

@subsection Description

-

@subsection See Also



@c **********
@c *  HELP  *
@c **********

@node ARexx HELP, ARexx LINE, ARexx GOTOBOOKMARK, ARexx Interface
@section HELP

@subsection Template
@example
HELP
@end example

@subsection Description

-

@subsection See Also



@c **********
@c *  LINE  *
@c **********

@node ARexx LINE, ARexx LOCKGUI, ARexx HELP, ARexx Interface
@section LINE

@subsection Template
@example
LINE
@end example

@subsection Description

-

@subsection See Also



@c *************
@c *  LOCKGUI  *
@c *************

@node ARexx LOCKGUI, ARexx NEW, ARexx LINE, ARexx Interface
@section LOCKGUI

@subsection Template
@example
LOCKGUI
@end example

@subsection Description

-

@subsection See Also



@c *********
@c *  NEW  *
@c *********

@node ARexx NEW, ARexx OPEN, ARexx LOCKGUI, ARexx Interface
@section NEW

@subsection Template
@example
NEW
@end example

@subsection Description

-

@subsection See Also



@c **********
@c *  OPEN  *
@c **********

@node ARexx OPEN, ARexx OPTIMIZE, ARexx NEW, ARexx Interface
@section OPEN

@subsection Template
@example
OPEN
@end example

@subsection Description

-

@subsection See Also



@c **************
@c *  OPTIMIZE  *
@c **************

@node ARexx OPTIMIZE, ARexx PASTE, ARexx OPEN, ARexx Interface
@section OPTIMIZE

@subsection Template
@example
OPTIMIZE
@end example

@subsection Description

-

@subsection See Also



@c ***********
@c *  PASTE  *
@c ***********

@node ARexx PASTE, ARexx PRINT, ARexx OPTIMIZE, ARexx Interface
@section PASTE

@subsection Template
@example
PASTE
@end example

@subsection Description

-

@subsection See Also



@c ***********
@c *  PRINT  *
@c ***********

@node ARexx PRINT, ARexx QUIT, ARexx PASTE, ARexx Interface
@section PRINT

@subsection Template
@example
PRINT
@end example

@subsection Description

-

@subsection See Also



@c **********
@c *  QUIT  *
@c **********

@node ARexx QUIT, ARexx REQUESTFILE, ARexx PRINT, ARexx Interface
@section QUIT

@subsection Template
@example
QUIT
@end example

@subsection Description

-

@subsection See Also



@c *****************
@c *  REQUESTFILE  *
@c *****************

@node ARexx REQUESTFILE, ARexx REQUESTRESPONSE, ARexx QUIT, ARexx Interface
@section REQUESTFILE

@subsection Template
@example
REQUESTFILE
@end example

@subsection Description

-

@subsection See Also



@c *********************
@c *  REQUESTRESPONSE  *
@c *********************

@node ARexx REQUESTRESPONSE, ARexx REQUESTNOTIFY, ARexx REQUESTFILE, ARexx Interface
@section REQUESTRESPONSE

@subsection Template
@example
REQUESTRESPONSE
@end example

@subsection Description

-

@subsection See Also



@c *******************
@c *  REQUESTNOTIFY  *
@c *******************

@node ARexx REQUESTNOTIFY, ARexx SAVE, ARexx REQUESTRESPONSE, ARexx Interface
@section REQUESTNOTIFY

@subsection Template
@example
REQUESTNOTIFY
@end example

@subsection Description

-

@subsection See Also



@c **********
@c *  SAVE  *
@c **********

@node ARexx SAVE, ARexx SAVEINSTRUMENT, ARexx REQUESTNOTIFY, ARexx Interface
@section SAVE

@subsection Template
@example
SAVE
@end example

@subsection Description

-

@subsection See Also



@c ********************
@c *  SAVEINSTRUMENT  *
@c ********************

@node ARexx SAVEINSTRUMENT, ARexx SCREENTOBACK, ARexx SAVE, ARexx Interface
@section SAVEINSTRUMENT

@subsection Template
@example
SAVEINSTRUMENT
@end example

@subsection Description

-

@subsection See Also



@c ******************
@c *  SCREENTOBACK  *
@c ******************

@node ARexx SCREENTOBACK, ARexx SCREENTOFRONT, ARexx SAVEINSTRUMENT, ARexx Interface
@section SCREENTOBACK

@subsection Template
@example
SCREENTOBACK
@end example

@subsection Description

-

@subsection See Also



@c *******************
@c *  SCREENTOFRONT  *
@c *******************

@node ARexx SCREENTOFRONT, ARexx SELECTINSTRUMENT, ARexx SCREENTOBACK, ARexx Interface
@section SCREENTOFRONT

@subsection Template
@example
SCREENTOFRONT
@end example

@subsection Description

-

@subsection See Also



@c **********************
@c *  SELECTINSTRUMENT  *
@c **********************

@node ARexx SELECTINSTRUMENT, ARexx SETBOOKMARK, ARexx SCREENTOFRONT, ARexx Interface
@section SELECTINSTRUMENT

@subsection Template
@example
SELECTINSTRUMENT
@end example

@subsection Description

-

@subsection See Also



@c *****************
@c *  SETBOOKMARK  *
@c *****************

@node ARexx SETBOOKMARK, ARexx SHOWMESSAGE, ARexx SELECTINSTRUMENT, ARexx Interface
@section SETBOOKMARK

@subsection Template
@example
SETBOOKMARK
@end example

@subsection Description

-

@subsection See Also



@c *****************
@c *  SHOWMESSAGE  *
@c *****************

@node ARexx SHOWMESSAGE, ARexx UNLOCKGUI, ARexx SETBOOKMARK, ARexx Interface
@section SHOWMESSAGE

@subsection Template
@example
SHOWMESSAGE
@end example

@subsection Description

-

@subsection See Also



@c ***************
@c *  UNLOCKGUI  *
@c ***************

@node ARexx UNLOCKGUI, ARexx VERSION, ARexx SHOWMESSAGE, ARexx Interface
@section UNLOCKGUI

@subsection Template
@example
UNLOCKGUI
@end example

@subsection Description

-

@subsection See Also



@c *************
@c *  VERSION  *
@c *************

@node ARexx VERSION, , ARexx UNLOCKGUI, ARexx Interface
@section VERSION

@subsection Template
@example
VERSION
@end example

@subsection Description

-

@subsection See Also






@c ******************
@c *   Known Bugs   *
@c ******************

@node Known Bugs, Future Plans, ARexx Interface, Top
@chapter Known Bugs
@cindex Known Bugs
@cindex Bugs, known ones
@cindex Bug reports

 Murphy's laws state that nothing can be perfect, not even computer
programs.  @value{prgname} is far from being perfect and I need
your help to fix as many bugs as possible.  If you discover a bug
which isn't reported in the list below (note: there is no list at
the moment; this is a beta release, remember?), please notify me.

 When you report a bug, state exactly what happens and indicate
how to reproduce the conditions that generated the problem.
Reports like @cite{@value{prgname} sometimes crashes converting my
favorite module} does not help at all.  Include your name if you want
to be credited in future @value{prgname} releases.

 If the program refuses to convert a module, mail it to me on
a disk or upload it somewhere I can reach it and I'll try to fix the
problem as soon as possible.

 @value{prgname} has been tested on several machines running Kickstart 2.0,
3.0 and 3.1.  It should work on any 68K family processor (was tested on
68000, 68030 and 68040) and is Enforcer and Mungwall proof.  I have also
tested @value{prgname} with virtual memory programs such as VMM and found
that everything seems to work correctly.



@c ******************
@c *  Future Plans  *
@c ******************

@node Future Plans, Programmers, Known Bugs, Top
@chapter Future plans

@table @bullet{} @code


@item Other module formats
Some formats I'd like to give support for in @value{prgname} as soon
as possible:

@itemize @minus
@item
FastTracker II (@file{.XM})
@item
MultiTracker (@file{.MTM})
@item
OctaMED MMD2
@item
Face The Music (@file{.FTM})
@item
Quadra Composer
@end itemize

If you have documentation regarding a format you would like to see in the
next release, please send it to me together with a couple of modules and,
if possible and legal, the program that created them.  I'll try to
implement the new format only if it is somewhat easy: it is very hard to
convert, say, Future Composer to SoundTracker.  Please, do not send a
module without at least a text file describing its structure, as I am
not willing to spend my nights hex-dumping modules :-).

If you want to write a new loader/saver hook, please get the
@value{prgame} developer package and read the included documentation.
You will also find many examples and also the full source code of
@value{prgname}.

@item @TeX{}
Another format I'd like to add is Amiga@TeX{}.  If you know
@TeX{}, you'll surely be wondering what a typesetting program can be
used for in music.  Well, Amiga@TeX{} is at the moment is the best
implementation available on any computer of the @TeX{} typesetting
environment, and its distribution includes @dfn{Music@TeX{}}, a powerful
music language which can output notes in a great standard staff notation.
I know no other program on the Amiga that can print notes of such fine
quality (if you do, let me know!), so I think that many musicians would
appreciate such an option.

@end table



@c ******************
@c *  Programmers   *
@c ******************

@node Programmers, XModule Format, Future Plans, Top
@chapter Programmer notes
@cindex Programmers, notes for
@cindex Modifying @value{prgname}
@cindex Compiling @value{prgname}

 @value{prgname} has been written in C and compiled with SAS C 6.51,
Other compilers may require some changes in the source code.

 The program is written in respect of the Amiga multitasking operative system
and complies with Commodore programming guidelines.  All allocated resources
will be (hopefully) freed before program termination.  I wrote @value{prgname}
with the goal in mind of keeping the executable fast and small.

 This manual has been typeset using MakeInfo, a GNU PD utility ported
to the Amiga by Reinhard Spisser and Sebastiano Vigna.
I found that the time I saved writing one file for three was nearly
compensated by the time spent learning how to operate MakeInfo.

 Besides, English is not my first language (as you might have guessed) and
I bet this document is full of grammar mistakes.

 If you intend to translate, improve or somewhat edit this document, please
work on the supplied TexInfo file and then process it with the utilities
supplied in the MakeGuide distribution.  You can find MakeGuide in several
PD libraries such as Aminet.

 Do not hesitate sending criticisms to my work, and, even better,
advices on how to improve the program and its documentation.  @xref{Author Info}.



@c ******************
@c * XModule Format *
@c ******************

@node XModule Format, Credits, Programmers, Top
@chapter XModule Module Format
@cindex File Format used by XModule

Before going into the details of the @value{prgname} module format, I'd like to
explain why I felt the need to invent yet another module format.  There were
plenty of them, but none had the flexibility I was looking for. The only one
exception is in my opinion OctaMED's MMD.  But the MMD file format is very
complicated, hard to read and poorly documented.  When I designed it, I wanted
XMOD to be as flexible, easy, efficient and expandable as possible.  If you are
developing a music program, please consider supporting XMOD.  If you have troubles
with the following format description, contact me and I'll be glad to help you.

@value{prgname} modules are standard IFF files.  They consist of a sequence of chunks
(also called @dfn{proprieties}) each storing a particular type of information related
to the module.  Text chunks, such as NAME and AUTH chunks are variable sized and NOT
null terminated.  When you read such a chunk, you should take care to clip the string
to your maximum buffer size.  NAME and AUTH fields are optional and should be assumed
empty when missing.

As with every IFF file, you should not depend on the order and size of any chunk.
However, as usual with most IFF formats, header chunks must always precede related
BODY chunks.  XModule requires this for PHDR chunks because it isn't possible to load
a pattern without knowing its length and number of tracks.  Some chunks may grow in
size in future versions of XModule.

@example
FORM XMOD

  [NAME]
    The name chunk contains the original name used to save the module.

  MHDR
    Module header.  Contains a ModuleHeader structure as defined in
    <XModuleClass.h>.

  [ANNO]
    Some XModule copyright information.

  FORM SONG
    The song FORM contains all data relative to one song.  Any
    number of songs can be stored into one module.

    [NAME]
      Name of the song.

    [AUTH]
      Author of the song.

    [ANNO]
      Song description.

    SHDR
      Song Header.  Contains a SongHeader structure as defined in
      <XModuleClass.h>.

    SEQN
      Song Sequence.  The contents of this chunk are unsigned words
      representing the pattern to play at a particular position.
      The size of this chunk should be twice the Length field of
      the SongHeader.
      When a song contains multiple sections, one SEQN chunk will
      be stored for each of the song sections (not yet implemented).

    FORM PATT
      Each occurrence of this FORM contains one pattern.  Patterns
      are numbered starting from 0.  Each pattern has its own
      length and number of tracks.

      [NAME]
        Name of this Pattern.

      PHDR
        Pattern Header.  Contains a PatternHeader structure as
        defined in <XModuleClass.h>.

      BODY
        The BODY chunk is stored as an array of PatternNote
        structures.  Tracks are stored one after the other.
        There are NumTracks*Length Note structures in the BODY
        chunk.

    END FORM PATT

    FORM 8SVX
      Each SONG contains one or more occurences of this FORM,
      one for each sample.  XModule currently saves and loads
      only the NAME, VHDR and BODY chunks.  Be prepared to
      decode Fibonacci Delta Encoded BODY chunks. An additional
      non-standard chunk is saved:

      INST
        XModule instrument info.  Contains an InstrumentInfo
        structure  as defined in <XModuleClass.h>.

      When the BODY chunk is missing, the sample must be
      loaded from the instrument library using the contents
      of the NAME chunk as the file name.

      See the IFF 8SVX documentation for more details.

    END FORM 8SVX

  END FORM SONG

END FORM XMOD
@end example



@c ******************
@c *    Credits     *
@c ******************

@node Credits, Author Info, XModule Format, Top
@chapter Credits
@cindex Credits
@cindex Acknowledgements
@cindex Thanks

 These people have helped me in developing @value{prgname}:

@itemize @bullet
@item
Fabio Barzagli, for beta testing @value{prgname} and for giving me
all his awesome modules!

Keep on making good music, Fabio!

@item
Jarno Paanen, for sending me the obfuscated source of his 32 channel
replay engine and for the e-mail support.

Perhaps I would have understood more by disassembling the PS3M executable. :-))

@item
Peter Kunath, for his unvaluable help.

No comment... :-)

@item Stephen Cantini, Michael Reichenbach and Julien Wilk, respectively for
writing the italian, german and french catalog.

Thank you all! I'm sure @value{prgname} users in your countries will apreciate
your efford.

@item Pauli Porkka, for his kindness, for letting me win a free DASMP
key, for the sources and for all the e-mails.

Will you support my format in the next DASMP release?

@item
The Amiga, for being the best computer in the world. :^)

Commodore: You've put really a lot of effort trying to kill the Amiga,
but you didn't succeed!
@end itemize



@c ******************
@c *  Author  Info  *
@c ******************

@node Author Info, Concept Index, Credits, Top
@chapter How to contact the author
@cindex How to contact the author
@cindex Author's address
@cindex Contact the author, how to

If you want to make me aware of your suggestions, bug reports, ideas
or you want to send me a gift, a good module or, why not, some money :-),
reach me in any of the following ways:

@table @bullet{} @code
@item E-Mail
@example
@group
UseNet:   xmodule@@shock.nervous.com (preferred)
FidoNet:  Bernardo Innocenti 2:332/125.1
AmigaNet: Bernardo Innocenti 39:102/205.1
@end group
@end example

@item SystemShock BBS
@example
@group
Line 1:  +39-55-499038 (28,800bps - V34)
Line 2:  +39-55-472514 (14,400bps - V32bis)
Sysop:   Bernardo Innocenti (me)
Message area 300: XModule Support
File Request magic name "XMODULE" to get the latest public version.
@end group
@end example

@item Snail-Mail
@example
@group
Bernardo Innocenti
Via Ventiquattro Maggio, 14
50129 - Firenze
ITALY
@end group
@end example

@item FAX
@example
@group
+39-55-8877771
Attn:  Bernardo Innocenti
Subj:  Amiga/@value{prgname}
@end group
@end example
@end table


I'll try to reply to all my e-mail, but I'm too lazy to reply
snail-mail, unless it is very important.  Your suggestions
will be taken into account unless they are @cite{I want
@value{prgname} to do ice tea}-style.


@node Concept Index, , Author Info, Top
@unnumbered Concept Index

@printindex cp

@contents
@bye