Ultimate Amiga

Network Boards => AMOS Language Discussion => AMOS Factory => AMOS Pro Documentation => Topic started by: MadAngus on February 16, 2012, 12:30:38 AM

Title: AMOS Pro Resource Kit Project Breakdown/Plan.
Post by: MadAngus on February 16, 2012, 12:30:38 AM
This topic is to ease the management of the Resource Kit Project Breakdown/Plan please post any comments in the project thread -> Here (http://www.ultimateamiga.co.uk/index.php/topic,9418.0.html).

[Thread Last updated 22/08/2012]
Added the TOME Extension Reverse engineering project to the Notes post (Related Projects)

[Added 04/03/12]
As the project progresses the Breakdown/Plan will be subject to change.

Introduction.

The AMOS Pro Resource Kit Project aims to restructure the current set of AMOS manuals into an extended set of documentation (see below) specific to AMOS Pro, adding undocumented features and new content.

AMOS Pro Resource Kit Document Set

The intended audience, me of course ;D. Actually, I was looking for a project that I would be willing to give a long term commitment to, in the region of 10 years (not expecting that from anybody else). The project started initially with the aim of providing the Amiga AMOS community with a set of AMOS manuals in PDF format with linked  bookmarks, TOC's and Index's. After some time working on this side off the project I decided that I would like to combine all usable information from the manuals, Help Files, Update readme's, PD Library Disks etc. into a set of manuals specific to AMOS Pro, aka The AMOS Pro Resource Kit.

[Edited 22/08/12] There was never a specific group targeted as an "intended audience", rather all levels from novice to experienced programmers are to be catered for. As you will see from the Project Summary (Here (http://www.ultimateamiga.co.uk/index.php/topic,9418.0.html)) the development timescale for the documentation project is over a 3 year period, 2012/2014. This timescale is not specific to creating just the resource kit but includes the porting of the resource kit to project Avolution plus adding additional material specific to Avolution. Also the development of the documentation will continue and be maintained after this period.

Project Avolution is an AMOS Basic based game development environment I started a few months ago. Just plodding along with it and playing with a few ideas at the moment. It's not the same as jAMOS nor is it intended to compete with jAMOS I now intend to incorporate jAMOS/xAMOS into project Avolution.
I digress...

...Back on subject
[Edited 29/02/12] As the intended audience extends to all levels so does the requirement to cater for the variety of preference (or flavors) of manual styles. In that respect an addendum to the original AMOS Pro manual will have to be written containing any undocumented features and any new and relevant information. As well as the aforementioned addendum, the classic manual set and software set will also be included in the resource kit. These inclusions will ensure the history of AMOS is maintained.
Title: Breakdown/Plan
Post by: MadAngus on March 02, 2012, 05:03:08 PM
Manual Structure/Makeup:
As there are differing ideas of what constitutes a manual and reference etc, I have provided below some details of the intended makeup of the manuals I have listed in the project summary.
Of note is the three different types of reference, I use all three, and find they cater well individually for different conditions.

AMOS Pro Getting Started guide [Edited 21/03/12]
A quick installation and usage guide for those who want to jump straight in. Includes installing AMOS in WinUAE.


Easy AMOS Pro [Added 29/02/12]
Easy AMOS Users guide ported to be AMOS pro specific and targeted at AMOS novices and beginners.


AMOS Pro Introduction to 3D [Added 29/02/12]
AMOS 3D Users guide ported to be AMOS pro specific, maybe become part of the AMOS Pro Programmers Guide (More on this TBD).


AMOS Pro User guide [Edited 25/03/12]
This expands on the getting started guide and adds additional content that doesn't necessarily fit in the Programmers Guide.
This may eventually make the getting started guide redundant, maybe?
Outline Topic List: [Added 29/02/12]


AMOS Pro Programmers Guide [Edited 29/02/12]
This will be the main guide for developing with AMOS. Novices and beginners would generally start with the AMOS Pro for Beginners guide or "EASY AMOS PRO" as I am now calling it.
AMOS Pro users' guide Outline will be used as a starting point (More on this TBD).

[Added 04/03/2012]
The structure of the Language reference and Quick Reference will be based on the Help File contents categories. These categories will be used to produce the final Table of Contents and Categorised index. A list of the categories is attached at the end of this post 'Reference_Categories.txt'. Note this list is not final.

AMOS Pro Language reference

Sample: (Source: Amos Pro User Guide - Modified)
----------------------------------------------------------------------
FunctionJOY
Descriptionfunction: read status of joystick
Syntaxstatus=Joy(port number)
RemarksThis inspects what is happening with the joystick and makes a report. If the joystick you are interested in is plugged into the joystick port, the computer must be told to look at port number (1). If you are using the mouse port call that port number (0).

When you run the example routine, reports are given about the movements of the joystick and the status of the fire-button in the form of binary numbers. The pattern of ones and zeros in the report can then be inspected. Binary bits shown as zero indicate that nothing is happening, whereas if any of the bits in the report is shown as a one, it means that the joystick has been moved in the direction that relates to that bit. The return values list those bits along with their meanings.
Return Value
Bit numberMeaning
0Joystick has been moved Up
1Joystick has been moved Down
2Joystick has been moved Left
3Joystick has been moved Right
4Fire-button has been pressed
ExampleDo
    J=Joy(1)
    Print Bin$(J,5),J
Loop

The Language reference entries may contain long example listings for each entry. No more than a 1 page example per entry and only if deemed appropriate.
[Edit] long example listings will be reserved for the online help. The Language reference entries will only contain 10-20 line listings where deemed necessary.
See AlsoEach aspect of the joystick status can be accessed individually, using the following functions: JLEFT, JRIGHT, JUP, JDOWN
----------------------------------------------------------------------
Example Documentation:
Visual Basic language reference
Borland Delphi 3 Visual Component Library Reference
Borland C++ 3.1 Library Reference



AMOS Pro Quick Reference [Edited 29/02/12]
[ADDED 29/02/12] Each Function given a brief half page summary (longer if deemed necessary) of what is in the language reference.

Sample: (Source: Amos Pro User Guide - Modified)
----------------------------------------------------------------------
FunctionJOY
Descriptionfunction: read status of joystick
Syntaxstatus=Joy(port number)
RemarksReports the movements of the joystick and the status of the fire-button. The port used for the joystick must be defined.
Joystick port  =  (1)
mouse port = (0)
Return Value
Bit numberMeaning
0Joystick has been moved Up
1Joystick has been moved Down
2Joystick has been moved Left
3Joystick has been moved Right
4Fire-button has been pressed
ExampleDo
    J=Joy(1)
    Print Bin$(J,5),J
Loop

The Quick Reference is restricted to small 3 or 4 line example snippets.
See AlsoRelated functions: JLEFT, JRIGHT, JUP, JDOWN
----------------------------------------------------------------------
Example Documentation:
Osbourne C/C++ Programmers Reference ISBN: 0-07-882367-6
O'Reilly CSS Pocket Reference ISBN-13: 978-0-596-5105-8



AMOS Pro Reference Cards (Not Listed in project summary)
Contains a tabulated list of commands their syntax and a brief description. Does not contain example snippets. Subject/Topic specific.

Quick Reference Card List: [Added 29/02/12]

Sample 1: (Source: AMOS Interface Command Summary)
----------------------------------------------------------------------
CodeDescriptionSyntax
LACreate a Label.LA label_number;
----------------------------------------------------------------------

Sample 2: (Source: Amos Pro User Guide - Modified)
----------------------------------------------------------------------
FunctionDescriptionSyntax
JOYfunction: read status of joystickstatus=Joy(port number)
----------------------------------------------------------------------
Example Documentation: (Both available in the download section)
AMOS Interface Command Summary
AMOS 3D QuickCard

Title: Notes
Post by: MadAngus on March 02, 2012, 05:03:32 PM
Notes: [Edited 22/08/12]

Resource Kit name [Edited 19/03/12]
Due to the inclusion of jAMOS and Avolution, "The AMOS Framework Resource kit" is being proposed as a the name for the resource kit.
Different manual sets will be provided for jAMOS and Avolution.

Copyright [Edited 18/03/12]
Just to be absolutely clear all parts of the resource kit will be freely available for download and use for both commercial and non-commercial projects. Any additional manual and tutorial source code will be distributed under a BSD license or copy-left licence so anyone can use it.
Documents are copyright François Lionet and respective contributors, manuals from this project may not be printed, sold commercially. Note, advertisement supported sited are considered to be a commercial entity.

Resource Kit page numbering
This will be standardised, page 1,2,...,101 etc. AMOS Pro user guide page numbering system (01.2.03 etc.) will not be used.

Font Sizes and Page Sizes.
Although I may have to reduce the font sizes in the classic manuals to replicate the original page numbering and page content, this will not apply to the resource kit, where the minimum font size for body text is 10 point.
     I personally dislike (putting it mildly) A4 format books, even A4 HTML based eBooks, and as I intend to print and bind my own copy of the resource kit manuals they will need to be structured within a standard book size, B5 paper size being the closest. Considering that PDF documents can be stretched and printed to A4, I do not see an issue with this. The exception to this is the QuickCard references. These type of references are well suited to the A4 page size.

Dual Index's will be used in the manuals were relevant. e.g.
Alphabetical    Categorised
BREAK ON
BREAK OFF
COMMAND LINES
MATCH
SORT
Array Operations
--MATCH
--SORT
Program run commands
--BREAK ON
--BREAK OFF
--COMMAND LINES

Project Specific Functions [Edited 19/03/12]
Where functions or usage differs between AMOS Pro, jAMOS and Avolution, separate specifications will be provided. Also where a function/usage is specific to either jAMOS or Avolution this will also be indicated.
e.g. (sample only, not fact)
MID$ (AMOS Pro)
...
MID$ (jAMOS)
...
MID$ (Avolution)
...
Different manual sets will be provided for jAMOS and Avolution.

File Format Output (from OpenOffice): [Added 02/03/12]
For output to and from a SQL/PHP database for web docs and wiki edit including generation of XHTML web pages (for offline reading) Apache Xerces / XSLT will be used. PDF output is automated in OpenOffice. This will be combined with OpenOffice Basic to automate the system.


Other Documentation:
Developer's Manual: Also not stated in the project summary, but part of the resource kit, the entire set of AMOS Pro v2.0 libraries need to be disassembled, functions/methods mapped out, undocumented content extracted, etc.
From this a developer's manual containing UML models, code breakdowns, etc. will be generated.

AMOS Developer Technique Guides:  [Edited 19/03/12]
This document project will research all known games programing techniques and provide documentation on how to implement them  Different manual sets will be provided for jAMOS, Avolution and AMOS (Software limitations allowing).


Extensions developer guide: [Edited 19/03/12]
Expands on the extension development information already given in the manuals. In addition this will contain documentation and tutorials for developing Avolution and jAMOS extensions (Eclipse plugins), as both these projects use the Eclipse.org development framework.
Different manual sets will be provided for jAMOS and Avolution.

Database developer guide: [Edited 19/03/12]
More targeted at the future potential of jAMOS and Avolution for connecting and working with databases with these projects.
Not part of the AMOS Pro Resource Kit.

jAMOS Users guide: [Edited 19/03/12]
Targeted purely at jAMOS installation, usage and extended features. Functions and methods common in usage with AMOS Pro will be highlighted in the jAMOS Users guide integrated into the AMOS Pro manuals.

Extensions Language Reference: [Edited 04/03/12]
Based on the "User Extensions Command List" produced by Lonewolf10, extend the documentation to the style defined for the AMOS Pro Language Reference. The User Extensions Command List Post is ->Here (http://www.ultimateamiga.co.uk/index.php/topic,9177.msg41517.html#msg41517). If and when this stage is reached Lonewolf10 will be contacted for permission to go-ahead or possibly collaborate.

Related Projects: [Edited 22/08/12]
Easy AMOS Tutor : ported to an AMOS Pro Extension. (BSD License)
AGA-H : AMOS Pro AGA Extension for accessing the AGA hardware. (BSD License)
Document Markup: Wiki style Markup facilities for users to provide online corrections to documents.
TOME Extension: Reverse engineered for use in development environments. [Added 22/08/12]
AMOS Pro 2.0: Resourced for documentation and the Avolution project. [Added 22/08/12]

AMOS Developer Network (ADN) Library:
[04/03/12 Moved here due to the sheer scale of the project]
This will be a database driven offline (Possibly Online) archive with a web based GUI. The PD Library will be categorised, with each entry corresponding to a PD Disk and the contents of that disk. Furthermore each disk will have it's individual contents in readable format within the web UI, with each PD Disk contents entry further categorised. A search feature will be provided to allow browsing for desired content. This archive will not be restricted to the PD Disk but will contain other contributed files.
Title: dbODF project plan
Post by: MadAngus on March 05, 2012, 10:25:36 AM
[Project Moved 05/12/2012]
Th dbODF project has essentially been moved offline. Any progress updates will be posted in my projects log in the development diaries board. Any UA site specific comments will be posted in admin section.