Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[MadAngus]

Post 2
Source: bruceuncle

Thanks for filling me in on the project.  And congratulations on the work you've already done getting the permissions, etc. to make it all legit.

I completely agree with the idea of uniformity in the documentation.  It helps enormously with people's ability to digest the content!

I'm not so sure about keeping the original page numbering systems (01.2.03 etc.) as it makes it very difficult to use it as a reference on screen (or eBook).  I appreciate the need to retain the style for sentimental reasons.  But maybe it would be better to use both that and a conventional page number?  So Contents pages would look something like this:

Section 03 Getting Started
     Chapter 03.01 Getting Started   ..........9
          03.1.01 Absolute Beginners   ..........9
          03.1.02 The Edit Screen   ..........10
          03.1.03 Typing in the Edit Window   ..........11
          03.1.03 Your first programs   ..........11
          03.1.04 Direct Mode   ..........12
          03.1.05 Loading a program   ..........13

One other thing that bothers me is the stuff that's 'missing' from the AMOS Pro Manual.  It's detailed in the integrated AMOS Pro Help system, but that in itself is not a very useful tool when it comes to getting a 'feel' for the language.  It's a bit like the problems I have with using the Messysoft .NET class libraries.  I'm always finding myself writing stuff that's already in the libraries and I could have used if only I knew it was there!

I tried initially converting the Pro Manual to a Word Document.  First problem was that each PDF line is a paragraph.  So tidying it up would have been a major effort.

Ideally, we should update the manual in-line with the extra stuff in the Help File.  But that is also quite a task.  I hit this problem with the Quick Ref guide for the Interface sub-system.  Using just the Manual, it was reasonably small, about 3 - 4 pages.  Adding in the stuff I unearthed in the Help File has blown it out to 6 pages.  Not quite as small as I would have liked.

Anyway, I've got the first draft completed.  I'll email PDFs of it and the bookmarked Pro Manual.  Plus an editable Interface Quick Ref in .docx or .odt format (see next para).

What format(s) can you use for editable stuff?  I'm using Word 2010, mainly to get used to using the wretched thing for commercial work.  But I realise that that may not be everyone's cup of tea.  Word does have a save as .odt facility and that does seem to work OK.  I can at least reload it into Word and the document looks the same as the .docx version.

Rather than prattle on, I'll just end with a reinforcement of my willingness to help in this project (except 24 x 7 dedication! ).

Keep yourself sane,
bruceuncle

[MadAngus]

Post 3
Source: Madangus
You've hit on some good points including one that I haven't made quite made clear in the Project page, thanks feedback helps point out things I've become blind to.

Page numbering (03.1.01), I have always found numbering of this type to be confusing, read on and find out how this would be corrected.

This thing I haven't made quite clear (my error), is that the project is a multi-track project. The first track is an exact duplicate set of the original manuals, this is for the classic AMOS users. This gives them an online set as well as their printed set (if they've got one), if they don't have the manuals then this gives them the original manuals to work from. This set will always be maintained with an addendum for errors and corrections.

The second track is the resource kit focusing purely on AMOS Pro, this is what we're both aiming for. In this track we rip up the original manuals and completely restructure the document set. This is where we can use consecutive page numbering, and add all newly discovered content. We would end up with a more standard set of documents as I have listed on the project page and below. You'll know this style from many other sources.

AMOS Pro Getting Started Guide (Standard guide found in most apps)
AMOS Pro for Beginners  (I'll port the Easy AMOS Manual to AMOS Pro for this)
AMOS Pro Introduction to 3D (Use's the AMOS 3D Manual)

The next four manuals use the AMOS Pro manual, except the content is broken up and placed where appropriate.
AMOS Pro User guide
AMOS Pro Programmers Guide
AMOS Pro Language reference
AMOS Pro Quick Reference

New content can be added to any of these manuals and any other manuals/guides that are developed.

Further porting to other projects like jAMOS is just a matter of changing references and GUI screenshots.

Help File, right I'll need to add that to the list.

The method I use to create these documents is to rip out the raw text (without any formatting or structure) from other PDF's and Scans/OCR of my originals, paste that raw text into OpenOffice, manually re-typeset and re-structure the document, then export to PDF. Later this year I'll have written a OpenOffice basic program to port the manuals to both HTML and PHP/XML.


Send me the MS Office .docx files along with the other's and I'll see if OpenOffice can open the .docx, I only need to get at the text, I can get the context of the document's and structure from the PDF's.

Your hacking and discovery of new content is excellent work and takes this project to another level. The other advantage this project gets is the help from an experienced programmer who can point out when the documentation is going in the wrong direction, after all programmer's are the target audience.

As the the old saying goes "If you've got an itch scratch it", so tackle what ever area you find interesting, and as has been said to me "in your own time".

[Edit]
Oops! I should have attributed the method of creating these documents (raw text processing) to asymetrix, as it was due to his pointer that I decided on this method. It is the best option, trust me.

[Hungry Horace]

Amazing reading guys

Really happy to see this project moving forward.

I've updated the AMOS Factory front page with a whole set of manuals. I'm sure we can add more if required.

http://amos.pspuae.com

FOL - i am very disappointed that other potential front-page url's do not work!!

MadAngus - can you point FOL in the direction of that ODF reader for him to install on the server? I have used re-direct pages for the manuals which are currently not available in HTML format.

I would like to see that front page as a "quick access" route for the purpose of AMOS Coders research/reminders (which i know is how i've found it helpful in the past, although I now keep PDF copies on my USE stick) , whilst any goals of preservation etc, we will probably keep contained within the forums and download sections - i hope this is ok?

[MadAngus]

MadAngus - can you point FOL in the direction of that ODF reader for him to install on the server? I have used re-direct pages for the manuals which are currently not available in HTML format.

Done.

[FOL]

Ouch that hurts, .

It was a mammoth task I had to do, took something like two weeks to fix site after hack.
I thought I had fixed everylink, .

FOL - i am very disappointed that other potential front-page url's do not work!!

MadAngus - can you point FOL in the direction of that ODF reader for him to install on the server? I have used re-direct pages for the manuals which are currently not available in HTML format.

[MadAngus]

AMOS Pro Resource Kit Open Discussion

Provided below is a basic outline of the form and structure the manuals could have. Most coders should recognise this form and structure, older coders will definitely recognise it . Please post your comments and opinions about your experiences with this structure or any other structure, problems and difficulties you've had with it, and how you would suggest these issues be avoided. This will help us to provide you with a better Resource Kit.

For example:
At times it can be difficult to find what you are looking for therefore provide both an alphabetical index and a categorised index.

We will need to figure out which parts of the documentation goes where, basically we need to create a contents for each manual and move the appropriate parts to the relevant section. Some are obvious others are not, any help with the breakdown would also be appreciated.

Any other areas you think should be discussed, please feel free to elaborate.

Basic form and structure:

AMOS Pro Getting Started Guide

• Where to get the software
• Install/Uninstall
• Basic troubleshooting
• Your first program

AMOS Pro for Beginners
Use the Easy AMOS Manual as the entry level guide, except change all Easy AMOS references/screenshots/code to be AMOS Pro specific?

AMOS Pro Introduction to 3D
Same as the beginner's guide using the AMOS 3D Manual?

AMOS Pro User guide

• The Integrated Development Enviroment
• The Compiler

AMOS Pro Programmers Guide

• Language Stucture
• Libraries
• Programing techniques

AMOS Pro Language reference

• Function Name
• Syntax
• Remarks
• Return Value
• See Also
• Example snippets

AMOS Pro Quick Reference
Each Function given a brief half page summary of what is in the language reference?

[MadAngus]

Just sent an email to spellcoder to see if he is OK with us including the AmigaCoding AMOS content into the resource Kit. Hope his email on this site is current.

[bruceuncle]

Just an update on where the AMOS Pro Help File stuff is at.

I've got all the help topics into a database and have a first draft of a formatted manual extracted from that, c/w Contents and Index entries.  There's still one or two topics 'missing' due to errors in the help system's mapping file - they have to be added by hand.  And there's some tidying up to do with typos in the original.  I should also be able to rebuild the original AMOSPro_Help.Map and AMOSPro_help.txt files to correct the mapping errors in them - but not until the manual's complete!  The same with the two Latest_News_*.* help file sets.

MadAngus is vetting this stuff for inclusion in the AMOS Pro Resource Kit.  I'm liaising with him as to how, when, if and where this stuff becomes available for publication as he's already laid some great foundations for this project.  And we both want a uniformity of style, etc for this stuff so it doesn't become just a grab-bag of unrelated bits and pieces.  An integrated approach is always the best way to go.

Thanks to his good works, there are already two extras in the downloads sections.  One is a 'bookmarked' PDF version of the AMOS Pro Manual.  The other is a Quick-Reference Guide to the AMOS Pro Interface language (note that the V1.0 in its file name is nothing to do with the AMOS Pro version - it's the document version - the info is for AMOS Pro V2).  These would best be regarded as stop-gap releases whilst we get the final stuff into shape.

I also intend to do quick-ref guides for the AMAL and Menu sub-languages 'real soon now'  (or at least, after the Help File docs are finalised).

The Help File manual is not intended to replace the original AMOS Pro Manual, but to possibly supplement it and definitely act as an organised source of material for the AMOS Pro Resource Kit docs.  It's more a quick-ref of the whole AMOS Pro language, as anyone who's used the help system will realise.  The original manual offers richer explanations and examples.  The reason for it arose from the fact that the Help File has a lot of stuff in it that wasn't in that original manual  .  So I started  to look at how to dig it out and make it more accessible...  Good fun! 

My personal thanks to MadAngus for all his help in introducing me to where this project is going and how I may be of help.  I'm always happy to contribute whatever I can to assist.

Now back to the digging...

[MadAngus]

Exceptional work bruceuncle.

Thanks to his good works, there are...

Nah, have to give you full credit for the data mining and exploration you have done on these. It would have taken me a month of Sunday's to do what you have achieved in such a short time. Well done.


The document (Help File + Index + Contents) you refer to as, "more a quick-ref of the whole AMOS Pro language" can be used as just that, it's Ideal. From looking at this document and some of the quick reference books I have, I've got a few ideas how this could progress to complete Quick Reference.

1a.) As we have mentioned dual index's, this could provide both. The index already added and another index using the contents as a base with the associated commands listed under it (Categorised), this would simplify command searching for end-users, especially beginners.

E.G.
Array Operations
--MATCH
--SORT

Program run commands
--BREAK ON
--BREAK OFF
--COMMAND LINES
...
...

1b.) Once you have added in all the relevant content I can generate a concordance file based on the two index's and generate the linked index references that would be required for an online document (i.e. PDF). The OpenOffice basic coding will take me a while but it's something I was planning on doing anyway.

2.) Breakdown each entry into the following (where relevant)

• Function Name
• Syntax
• Remarks
• Return Value
• See Also
• Example snippets

Although there are example snippets already in the document, I'd like to see a 3 or 4 line snippet followed by the expected output. I often find that minimal snippets in other references are not always clear in their meaning or expected output. However these would be added at a later date once the Quick Reference itself was completed, a second edition maybe.

3.) Once complete the quick reference can be used as the template for the Language reference, expanding the entries with the descriptions from the other manuals. With Listings on page as well as the pointer to the example file.

4.) The quick reference books I have are usually a smaller page size (A5-ish) than normal books (B5-ish), with my c++ quick-ref being nearly 500 pages long. A5 is the book size I would be targeting for the quick ref.

I'm going to bring the quick reference forward as a priority once I've completed the newsletters. They are quite awkward and time consuming to do, due to the original print quality, lots of OCR errors, and the layout takes more work than the standard manuals. It's taking 3-4 days to do 1 issue (20 pages). I'll continue work on the classic manuals as I go along.


The quick-ref guides for the AMAL and Menu sub-languages you mentioned, are you going to do them in the same format as the interface language guide. Although the info can be added and expanded in the resource kit manuals, I also like the idea of these references as quick cards, very handy for developers.


You mentioned that MS Office cannot create linked index's. Not surprisingly OpenOffice followed suit in not providing that feature either. A bit disappointing as the OpenOffice team had all the code and implementation methods already completed. With OpenOffice you could create a concordance file and the index would be auto-generated from that. However when editing the Index properties Hyperlinks cannot be added simply because the OpenOffice team did not transfer that feature from the Table Of Contents properties page.

The unfortunate side effect of this is manually created links. For AMOS The Creator, 840 bookmarks and 840 Hyperlinks had to be created manually. 1680 manually created tags takes a looooong time, well about a week.

Definition Concordance File:
A concordance file consists of a text file that contains an index of all main words in a book. In OpenOffice the concordance file has an xml structure. OpenOffice uses this to scan the document and create references to all words matching the index entries in the concordance file. These references are then used to generate an index.

[bruceuncle]

Exceptional work bruceuncle.

Aw shucks!   

The document (Help File + Index + Contents) you refer to as, "more a quick-ref of the whole AMOS Pro language" can be used as just that, it's Ideal.

I like the idea of quick reference guides too.  That's why I did the Interface one already posted - I needed it for myself  .

I'm a bit concerned that we don't blur the distinctions between 'language and programming manual', 'tutorial'  and 'quick reference': 

-	I've always regarded a 'manual' as being the basic (bugger - another pun!) learning tool and 'bible'.  Yer sits down with it and slog through it, patiently absorbing the info and doing the examples.
-	The 'tutorial' is a learning tool that takes it a step further and explores 'areas of interest' with copious full working examples.
-	The 'quick reference' is a memory-jogger for people who have mostly waded through the first two.  It should be as concise as possible and just show a brief description,  syntax definition, parameter and return value definitions, and (especially in the case of AMOS Basic) bit-field definitions.  The odd paragraph of info is acceptable to explain syntax conventions and anything unusual about the language.

In that context, the 'snippets' in a quick-reference shouldn't really be there - just the syntax variations.  It's a memory-jogger rather than a full explanation.  The user should go to the 'manual' or 'tutorial' if they're confused by the 'quick-reference'.

Although there are example snippets already in the document, I'd like to see a 3 or 4 line snippet followed by the expected output. I often find that minimal snippets in other references are not always clear in their meaning or expected output. However these would be added at a later date once the Quick Reference itself was completed, a second edition maybe.

That's why I'd rather see the 'quick-ref' with minimal snippets that just define the usage syntax.  The example snippets (and more extensive examples) should go in the 'manual' and 'tutorial' docs.

Having stated that, of course the AMOS Help file on which this document is based only partially follows those rules  .  At least the authors took the trouble to split them into separate chunks.  There's the 'manual' style stuff at the start (How to Use the Help System and Syntax Conventions) with the 'quick-ref' style for Editor Keys and the language itself.  Plus a few helpful 'tables' (Scancodes and Keycodes) at the end.  The 'Stop Press' at the very end is back to the 'manual' style again.

My inclination would be to chop the document into just these categories as a 'quick-ref':

Syntax Conventions	-	manual style, but brief
Language Syntax	-	quick-ref style only
Editor Keys	-	quick-ref style only
Tables	-	quick-ref style only

Any expansion on that starts to get a bit too close to being a 'manual'. 

Of course, the 'manual' itself can go to town on examples and so on as long as it doesn't attempt to become a 'tutorial'.

It's inevitable that there will always be some slight blurring of the distinctions between these document types.  But keeping them a separate as possible should be the goal.

That's why I made this point:

The Help File manual is not intended to replace the original AMOS Pro Manual, but to possibly supplement it and definitely act as an organised source of material for the AMOS Pro Resource Kit docs.

Does that make any sense?

4.) The quick reference books I have are usually a smaller page size (A5-ish) than normal books (B5-ish), with my c++ quick-ref being nearly 500 pages long. A5 is the book size I would be targeting for the quick ref.

I can see your point.  And for a commercial ref book that's probably the way to go (printing and packaging costs, etc).  But who's going to be the target for these docs?  I suspect they'll either be viewed on-screen (HTML and PDF versions) where page size is irrelevant, or printed on a home printer.  And who can handle those sizes on a home printer?     Although I must admit to printing two-up and double-sided on A4 to shrink paper usage myself sometimes .  Would like some feedback from the intended audience before committing on that point.

The quick-ref guides for the AMAL and Menu sub-languages you mentioned, are you going to do them in the same format as the interface language guide. Although the info can be added and expanded in the resource kit manuals, I also like the idea of these references as quick cards, very handy for developers

.

Yeah, I quite liked that format even though it's not exactly a pocket-sized ref-card style.  Again, I can only print on A4 although I can print on thick A4 card and chop into A5 on the colour printer.  A personal gripe is that, as I get older, I find tiny-font card-style refs a bit of a pain to read.  My e-book reader came with a manual the size of a cigarette packet (for younger viewers, cigarettes were a nasty habit from olden-times) which required a magnifying glass even for younger readers.  I'm thinking of donating it to a local doll's house...

The unfortunate side effect of this is manually created links. For AMOS The Creator, 840 bookmarks and 840 Hyperlinks had to be created manually. 1680 manually created tags takes a looooong time, well about a week.

I've got this stuff stored in a structured database.  So please let me know what exactly you need to do this the easy way.  I always prefer writing code to do tedious jobs rather than slog through doing it by hand.  It also avoids typos and errors - assuming the source texts are error-free.  That's what computers are for!    In fact it's a real nice change to be dealing with such a small database rather than the multi-million row commercial monsters I'm used to.  I've also had a lot of experience with text-formatting code over the years, so don't hesitate to ask.  I can soon tell you if any ideas are feasible or not.  And I really would hate to see anyone 'doing it the hard way'!  Your concordance file looks a likely candidate...

[MadAngus]

 

spellcoder has just given permission to use the content of his site in the resource kit. I will keep in touch with spellcoder as to what will be used, rest assured the resource kit will give full attribution/credit to all those who have directly or indirectly contributed.

[MadAngus]

[Release]

AMOS Club Newsletters Volume 1 (PDF) conversion is now available in the download section. Happy reading. 

bruceuncle with the help of Hungry Horace has provided a corrected AMOS Suuffle Extension listing (part of issue5/6). This is included in the archive.

Consists of the following Issues:

Issue 0 - 8 Pages
Issue 1 - 20 Pages
Issue 2 - 18 Pages
Issue 3 - 18 Pages
Issue 4 - 19 Pages
Issue 5/6 Double Issue - 34 Pages

[EDIT] The image below is for Hungry Horace if he wants to use it for the AMOS Factory Frontpage.

[bruceuncle]

The deeper I've delved into what info is available for this project, the more I realise that my original thoughts were not really practical  .

The idea of a 'quick' ref for the entire language is not really feasible as the sheer size of it rules out the notion of 'quick'.  I would humbly suggest going with the AMOS Pro Language Reference as the major work and limiting the AMOS Pro Quick Reference to sub-languages.

To explain what I mean, the first drafts of the AMOS Pro Quick Reference comes out at around 200 pages.  By no means a 'quick' document.  As I add in the 'see also' refs, basic examples and expand on the original texts, the size is blowing out even more (circa 500 pages at last estimate!).  It's only advantage over an AMOS Pro Language Reference is that it would be slightly smaller!

So, I would suggest the following:

The AMOS Pro Quick Reference becomes the AMOS Pro Language Reference.  It differentiates itself from the AMOS Pro Programmers Guide by being the 'dictionary' of the language.  Access routes being both as laid out in the original Help File format (Contents) and encyclopaedic (levels of Index).

Quick Reference Guides are produced for specialised sub-languages and useful tables:

• Interface
• AMAL
• Menu
• Ask Editor and Call Editor Commands
• Library Equates and LVOs
• Editor Keys
• Tables
• Any other bits requiring the memory jogging format

with the format for each following the Interface one already published in A4 ( ) size.

MadAngus provided suggested fonts for these documents and I've tried them out on the drafts.  I like what I see - especially the fixed-width DejaVu Sans Mono font for code.  I'll re-publish the Interface Quick Ref in that format so's we start as we intend to proceed.

The format for the manual being as MadAngus suggested for the AMOS Pro Language Reference and in B5 ( ) size.

Progress Report:

I've just pulled all the example AMOS program sources into ASCII format and shoved them into the database.  I now know all about the Ask Editor and Call Editor commands and a bit more than I bargained for with a couple of undocumented 'features' and a bug in the equates file!  Good fun to be actually writing stuff in AMOS rather than writing about AMOS.

These sources will now be pulled into the main document using the existing links to example programs in the help file, then cut down to the few lines required for each example.  That means that the code examples in the text will exactly match their associated example program sources.  It also means that there aren't many commands and functions for which we'll need to 'invent' examples.

It leaves me with the manual task of cutting the code samples down for each topic.  Initially, they're the full source for each example - way over the top!  But hey, I can delete stuff real fast when I want to..

In parallel with that, I've been carefully editing the original help texts to expand them, correct errors, control uniformity of format, etc.  About 30% of my way through to date.  As all this is being done in the database, it's easy to shift stuff around and make changes without losing the document structure and links, or introducing errors.

The database then spews all this into an RTF file with styles and links already set, so's the 'real' work can start on the finished product in the word processor.  A trial of that bit's already been done as a 'proof of  concept' so we know it works.  Wish me luck!

[MadAngus]

Good work bruceuncle.

I suggest we differentiate between the quick references to make it clearer what the intention of the document is.

Quick Reference Cards e.g. Interface Quick Ref -> Interface Quick Ref Card
Quick Reference Guide e.g. Osbourne C/C++ Programmers Reference ISBN: 0-07-882367-6

Also, I agree that Quick Reference Cards should be in A4 Landscape as with the AMOS 3D and Interface Quick Ref Cards.

[bruceuncle]

Agreed.   

Did you really mean A4 Landscape for the 'cards'?  The Interface one is A4 Portrait, but I've got to re-format it for the recommended fonts anyway as they push stuff around a bit too much compared to the fonts in the V1.00 doc.  I did try an A4 Landscape tri-fold format initially but gave up on it as there's simply not enough room without going to dolls house font sizes.

I'm happy either way as long as they're consistent.  Let me know.

Now back to work...